★ FEATURED ARTICLE 这两年一直有人问我同一个问题个人博客到底怎么搭才省心买台服务器跑动态程序时间全耗在环境维护和补漏洞上用现成的写作平台数据又不在自己手里。折腾了几个方案之后我把博客最终落在“静态站点生成 代码托管平台的Pages服务”这套组合上稳定跑了很长时间。这篇文章就把我从零到一搭建个人博客的完整过程拆开讲包括每一处选型的原因、执行时的参数、上线后踩过的坑以及故障排查的思路。内容偏实操适合准备搭博客但还没动手的开发者也适合已经被各种方案绕晕、想找一套省心流程的人。1. 为什么是“静态博客 平台Pages”这个组合1.1 动态方案的钱和时间都花在哪了先说结论如果你的博客就是写写文章、放放代码片段、偶尔更新一下项目文档动态站点的绝大多数能力都用不上。过去我也在服务器上搭过博客程序Nginx、数据库、缓存、安全补丁、定时备份每一个环节都需要操心。流量低的时候一台服务器每天百分之九十九的时间都在空转但账单照付。更麻烦的是安全维护博客程序被扫描、被爆破是家常便饭不勤快打补丁很快就变成别人挂马的中转站。这是我在动态方案上最大的体会我真正想要的是“写内容”但每天在干的是“养服务器”。投入和产出的方向完全反了。1.2 Pages服务帮你省掉的是什么代码托管平台提供的Pages服务本质上是一套自动发布链路。你只需要把博客源文件推到代码仓库平台会按照你预设的构建命令把文章生成成纯静态页面再发布到它自带的访问节点上。整个过程不需要你接触服务器、不需要配置进程守护、不需要处理数据库连持续部署的脚本都不用写。我愿把它理解成“把代码仓库变成了博客的发布按钮”本地写完文章推一下就发布了构建日志在网页上直接看失败了能很快定位。对个人博客这种低频、低并发的场景这个模式几乎是量身定做的。1.3 这套方案的适用边界当然它适合的是内容型站点不是所有网站。如果你的站点需要用户登录、需要后台管理、需要实时交互、需要动态查询数据库那静态托管就不合适老老实实上服务器。我个人判断标准很简单一个页面能不能提前生成好如果能就适合静态化如果每次访问的结果都因人而异那就不能。从维护角度说这套组合最大的优势是“故障面很小”。本地工具 代码仓库 静态托管每一层都足够简单各管各的出问题很容易定位。这也是我后来坚决不回头的原因。2. 开工前要处理好的三件事仓库、环境、域名2.1 创建代码仓库时的关键选项Pages服务依赖代码仓库所以第一步是在代码托管平台注册账号并创建一个新仓库。创建时有几个选项会直接影响后面的部署值得先说清楚。第一是仓库可见性。Pages服务通常不限制仓库必须公开但你要确认平台策略。如果博客只是给自己用私有仓库更稳妥如果想让别人能看到源码就选公开。我建议默认私有因为博客源码里有时候会放草稿、私人笔记公开后不好清理。第二是初始化选项。创建仓库时平台会问是否生成README、.gitignore等文件这里建议全部留空创建一个完全空的仓库。原因是很多博客框架初始化时有自己的目录结构如果你提前让平台生成了README后面合并时会多出一些无意义的版本冲突。2.2 本地环境其实只要两样东西本地需要准备的是Node.js运行环境和版本管理工具。Node.js是绝大多数静态博客框架的运行时依赖版本管理工具则是你和Pages服务之间的传送带——Pages的发布触发机制就是“检测到代码推送”。装完之后建议先验证一下环境是否正常node -v npm -v git --version能打印出版本号就说明环境可用。这里我特别提一句很多人在博客框架装不上时第一反应是代码写错了实际上往往是Node.js版本太旧或太新。不同框架对Node.js版本有要求装之前先看一眼框架文档要求的版本范围能省掉后面一小时的排查。2.3 域名提前规划别等部署完再慌Pages服务默认会给你一个二级域名用来做临时访问验证没问题但正式对外最好绑定自己的域名。这需要你提前买好域名并且想清楚用哪种形式做主力访问地址是裸域名直接访问还是带www的二级域名。我建议主域名和www都解析到Pages服务后续只把其中一个作为首页规范地址。这样无论用户输入哪种形式都能打开搜索引擎也不容易出现重复收录的问题。域名解析规则的填写方式要等部署完拿到Pages分配的默认域名后再确定所以这个阶段只需要把域名买好其他不用动。3. 本地建站初始化、主题配置与写作流程3.1 用一条命令完成站点初始化框架的选择我不过度展开市面上主流的静态博客框架基本都是这个工作流装命令行工具、初始化目录、写Markdown、生成静态页面。我用的框架也是这个套路。初始化命令大致长这样具体命令以你选的框架文档为准npm install -g blog-cli # 安装命令行工具示例 blog init my-blog # 初始化站点目录 cd my-blog blog server # 启动本地预览初始化完成后目录里会有一个source目录用来放文章源文件还有一个public目录用来放构建产物。这点需要记牢source是源头public是结果Pages发布的是public里的内容不要手工改public里的文件因为它每次构建都会被覆盖。3.2 最小配置改好这四个字段就够了站点根目录下会有一个配置文件格式通常是YAML。我第一次看到那个文件时有点懵字段非常多。实际部署阶段真正要改的只有四个字段。配置项建议值说明站点标题你的博客名字会显示在页面标题和站点介绍中站点URL你的正式域名部署后必须改成真实域名语言zh-CN影响日期等格式的展示主题你选定的主题名决定页面长什么样一定要特别关注“站点URL”字段。这个字段如果填错了或者部署后忘了从默认值改成真实域名博客页面上所有使用绝对地址的链接都会指向错误位置表现就是首页能打开但文章页、资源文件全部404。这个问题的排查放在后面第6部分详细说这里先记住URL字段必须和最终访问域名完全一致。3.3 文章头部信息与图片路径的规范每篇文章是一个Markdown文件文件开头需要一段头部信息用来声明标题、日期、标签等信息--- title: 我的第一篇文章 date: 2024-01-01 10:00:00 tags: [随笔, 技术] categories: [学习笔记] ---这块的坑主要在图片。写文章时引用图片我建议统一放到source目录下的固定文件夹里然后在文章里使用相对路径或固定前缀路径引用。我最开始图省事直接在文章里写本机绝对路径结果本地预览正常一部署就全是裂图。后来统一改成相对路径这个问题再没出现过。3.4 本地预览时需要检查的点每次写完文章先本地起服务预览一遍再推送。这一步能挡掉大部分低级错误。我习惯重点检查三处首页文章摘要是否正常显示、新文章的内页能否正常打开、图片是否全部加载。这三样过了基本就能推了。4. 部署到Pages构建配置与首次发布4.1 构建命令和输出目录要严格对应在平台的Pages服务设置里需要填写三样东西构建命令、输出目录、推送分支。这三项的填写要和你本地实际使用的框架严格对应不能想当然。配置项我的填写为什么这样填构建命令框架官方规定的生成命令平台会替你在云端执行这条命令输出目录public框架构建产物默认输出到这个目录推送分支main我统一用main分支作为发布分支这里我见过不少人填错输出目录明明框架输出到public配置里却填了dist结果平台构建成功了也找不到能发布的文件最后给了一个空页面。遇到部署后空白页面第一反应先检查输出目录填得对不对。4.2 推送代码并触发首次构建把本地站点初始提交推进仓库这一步就是真正的“发布动作”git init git add . git commit -m init blog git branch -M main git remote add origin https://平台域名/用户名/仓库名.git git push -u origin main推送成功后Pages服务会自动开始构建。整个构建过程一般几十秒到几分钟不等取决于文章数量和主题复杂度。构建日志可以在平台后台看到留意有没有报错。4.3 首次部署后的自检清单首次部署完成不要急着宣告成功先过一遍自检清单检查项检查方法常见问题首页可访问浏览器打开默认域名构建失败或输出目录错误导致空白文章页可访问点击首页文章链接站点URL配置错误导致404静态资源可加载打开浏览器开发者工具看网络请求图片路径写死导致资源404导航链接可用逐个点击导航入口生成时URL前缀未同步这四项验完博客才算真正上线。5. 自定义域名与HTTPS最后一道工序5.1 域名解析记录怎么填在平台上拿到默认访问域名后就可以去域名服务商后台配置解析了。通常需要添加一条CNAME记录把主域名指向平台分配的默认域名。如果你想让www前缀也能访问就再给www子域名加一条同样的CNAME记录。这里最容易出问题的点在于解析生效时间。DNS解析生效不是即时的可能要几分钟到几小时。我见过不少人刚加完解析本地一刷新还是打不开就以为填错了反复删了重加反而把状态搞乱。建议加完后先等一会儿用线上的DNS查询工具确认解析状态再继续下一步。5.2 在Pages服务端绑定域名并开启HTTPS解析配置好了回到平台后台把域名填进Pages服务的自定义域名设置里。平台会做一个校验校验通过后域名就绑定成功了。绑定成功后再开启HTTPS证书证书的申请和签发一般是平台自动完成的等待时间通常不长。我个人的操作顺序是先等解析生效再绑定域名最后开HTTPS。顺序反过来的话可能出现证书校验失败因为平台校验域名归属时解析还没生效就会给出一个让人摸不着头脑的报错。5.3 裸域名和www怎么统一绑定好之后我建议把主域名和www都做了解析但只保留一个作为正式入口。我用的是裸域名作为主入口www自动跳转到主域名。如果平台没有提供跳转设置就在咨询服务端规则里配置或者接受两个地址都可用只要不出现“今天的文章页面用www打开链接却跳到裸域名”这种不一致即可。这类细节不影响发布但影响专业感。5.4 访问速度的实际感受Pages服务的节点位置会影响国内打开速度这一点需要提前有心理准备。如果平台提供国内访问节点通常需要你提前确认好域名接入相关的审核流程如果使用海外节点打开速度偶尔会偏慢但整体可用。不同平台的差异比较大建议在买域名之前就把这部分调研清楚别等全部搭好了再换平台那就等于重新折腾一遍。我自己的选择偏稳定优先速度能接受就行毕竟博客内容比那几百毫秒重要得多。6. 上线之后我踩过的坑和日常维护经验6.1 坑一文章页全部404我遇到过最典型的故障是首页能打开、文章页全部404。查了一圈最后定位到是站点URL配置填成了默认的localhost地址。部署到线上后文章页生成的永久链接全是localhost开头自然打不开。这个问题的排查思路可以复现一下先随便打开一篇文章页看浏览器地址栏里显示的是什么域名。如果地址是localhost或者平台默认域名而不是自己的正式域名基本就是站点URL配置有误。改完配置重新构建再刷新页面问题就消失了。这个坑最值得写出来因为构建日志里不会有任何报错。6.2 坑二构建成功后页面是旧内容另一次我明明推送了新文章构建日志显示成功但访问页面还是旧内容。这种问题大多是缓存导致的CDN节点或者浏览器缓存没有及时刷新。解决方法是先用无痕窗口访问验证确认是新内容如果无痕窗口里还是旧的就在平台后台手动触发一次重新构建强制刷新发布内容。这里我想额外提一个经验不要为了省事频繁“重新构建”Pages服务对构建次数通常有一定限制合理利用就好。推送构建失败时优先在本地复现构建命令看本地是否报错再决定要不要反复触发线上构建。6.3 坑三图片时好时坏图片问题出现得也很多。一种情况是文章里混用了绝对路径和相对路径本地看好的部署后就裂图另一种情况是文件名含有特殊字符比如中文字符在部分节点上解析异常。我的建议是图片文件名统一改成英文或拼音图片统一放在同一目录下引用方式保持一致。别小看这个细节它能让图片相关的问题彻底消失。6.4 备份与评论功能的落地源文件本身就是最好的备份我通常维护一个私有仓库专门存博客源码和图片资源这个仓库和发布仓库分开避免误操作覆盖。文章更新时只要先推私有仓库再推发布仓库就能保证任何时候都有最近的一份可恢复版本。评论功能是静态博客的天然短板毕竟没有服务端数据库。我的做法是接入第三方评论组件它的数据依托在代码仓库的Issue系统上访客留言后评论区自动归档成一条条Issue。接入过程不复杂麻烦的一点是初始化和样式微调但搞定之后基本不需要再管。这里提醒一句第三方评论组件依赖外部服务如果目标读者访问你博客已经偏慢可以考虑干脆关掉评论或者引导读者通过邮件交流很多技术博客都这么做没什么不妥。6.5 我目前的维护节奏现在我的日常维护流程已经固定成一条极简链路写Markdown → 本地预览 → git推送 → 等构建完成。整个过程不超过五分钟日常运维成本几乎为零。偶尔需要改主题样式改完推送重新生成就算完成。这套方案我用了很长时间最大的感受是它把“建站”真正变成了“写字”用户不需要再关心服务器、数据库、安全补丁这些多余的事。最后补一个实用的小技巧把整个流程中的初始化命令、构建命令、部署配置要点整理成一段笔记放在本地。这样不管以后换电脑还是换平台照着笔记十分钟就能恢复整套环境。我自己的这套笔记一直在更新每次踩了新坑就补一条现在它已经变成我博客工作流里最重要的一份参考资料。
阅读完成 · 觉得有帮助？
