静态博客与Pages服务：零维护个人博客搭建完整指南

这两年一直有人问我同一个问题：个人博客到底怎么搭才省心？买台服务器跑动态程序，时间全耗在环境维护和补漏洞上；用现成的写作平台，数据又不在自己手里。折腾了几个方案之后，我把博客最终落在“静态站点生成 + 代码托管平台的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”字段。这个字段如果填错了，或者部署后忘了从默认值改成真实域名，博客页面上所有使用绝对地址的链接都会指向错误位置，表现就是首页能打开，但文章页、资源文件全部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，配置里却填了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 首次部署后的自检清单

首次部署完成，不要急着宣告成功，先过一遍自检清单：

这四项验完，博客才算真正上线。

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推送 → 等构建完成。整个过程不超过五分钟，日常运维成本几乎为零。偶尔需要改主题样式，改完推送重新生成就算完成。这套方案我用了很长时间，最大的感受是它把“建站”真正变成了“写字”，用户不需要再关心服务器、数据库、安全补丁这些多余的事。

最后补一个实用的小技巧：把整个流程中的初始化命令、构建命令、部署配置要点整理成一段笔记放在本地。这样不管以后换电脑还是换平台，照着笔记十分钟就能恢复整套环境。我自己的这套笔记一直在更新，每次踩了新坑就补一条，现在它已经变成我博客工作流里最重要的一份参考资料。