静态博客这件事，我断断续续折腾了七八年，从最早手动把 HTML 拖到 FTP 上，到后来用动态程序搭站、每个月盯着服务器账单，再到现在彻底回到"本地写 Markdown + 提交一次代码就自动发布"的路子。绕了一大圈，结论很朴素：如果一个博客的核心诉求只是写东西、能被人看到、不被运营成本绑架，那静态博客加代码托管平台就是当下性价比最高的方案，没有之一。这套组合的搭建成本可以压到零元，时间成本也就在十分钟上下——前提是你知道哪几个地方必须动、哪几个地方千万别动。

我把它写成一份完整的操作记录，从方案为什么这么选、工具怎么挑、每一步命令背后的意图是什么，到最后那些只有踩过才懂的坑，全都摊开说清楚。适合三类人：一是完全没碰过命令行、但愿意照着敲的新手；二是搭过动态站点、正被续费和漏洞补丁折磨的老站长；三是已经有一个博客、但更新流程太重导致写两天就荒废的人。整套流程不依赖任何付费服务，也不要求你懂前端框架，会用记事本和终端就够了。

1. 方案设计：为什么静态博客值得花这十分钟

在动手之前，我习惯先把"为什么这么选"想明白。因为工具是会换的，思路不会。你把底层逻辑搞清楚了，哪怕三年后流行的是完全另一套东西，你也能十分钟迁移过去。这一节我想把静态方案和动态方案的边界讲透，把零成本这件事拆成可核对的三块拼图，再给出我筛选生成器的三个硬指标。

1.1 静态站与动态站的真实分界线

很多人对静态博客有个误解，以为"静态"就是不交互、不现代、功能残缺。实际不是这么回事。静态站点在构建阶段就把所有页面渲染成现成的 HTML 文件，访问者拿到的是完整成品；动态站点则是每次请求现场拼装，从数据库取数据、跑模板、返回页面。这个差别带来的连锁反应，远比想象中大。

我列个对照表，是我这些年实际感受到的差异，不是文档里的理论：

看清楚这张表之后，取舍就变得很简单：如果你的博客以长文输出为主，评论和复杂交互不是刚需，静态方案几乎全面占优。反过来，如果你要做论坛、要做会员体系、要让多人在线协作投稿，那就老老实实上动态方案，别硬凹。

我个人的判断标准更粗暴一点：一个个人博客，如果一年更新不到二十篇，那它的核心价值就在"内容留存"和"被检索到"，这时候动态方案那些花哨功能的边际收益极低，而维护成本是实打实每个月都要付的。这就是我最终回归静态的原因。

1.2 零成本到底由哪几块拼成

"零成本"这个词容易被误解成"什么都不要钱"，其实准确说法是"在没有明显流量压力的情况下，各项服务的免费额度足够覆盖个人博客的全部需求"。这套方案的成本结构可以拆成三块，每一块都需要一个替代品：

• 生成器：负责把 Markdown 变成 HTML。用开源的，永久免费，这部分成本恒为零。
• 托管与构建：负责存放代码、自动构建、对外提供访问。用代码托管平台自带的 Pages 服务和构建流水线，个人量级完全在免费额度内。
• 域名：这是唯一可能产生费用的部分，但也可以规避——直接用平台分配的二级域名，完全够用。

真正要留意的是第三块。很多人一上来就买域名、买证书，结果站还没写两篇，先花出去一笔。我的建议是先用平台分配的默认地址跑通全流程，等内容稳定更新一个月以上、确认自己不是三分钟热度，再考虑挂自定义域名。顺序反了，很容易变成"域名买了，站荒了"。

至于免费额度的边界在哪里，说个大致感觉：纯静态文件、没有大图片、月访问量在几千到一万次以内，各家平台的免费档都很难被撑爆。真正会触发限制的是两点——单次构建时长过长（通常因为文章数量极多或图片没压缩），以及仓库体积过大（通常因为把原始大图直接提交进了版本库）。这两点后面都会讲到怎么规避。

1.3 挑生成器，我只看三个硬指标

市面上的静态站点生成器少说几十种，网上的对比文章一大堆，但真正影响日常使用的其实就三条。我按自己的优先级排序：

第一条，构建速度。这直接决定了你的"写作反馈循环"有多爽。文章攒到一两百篇之后，慢的生成器一次全量构建要几十秒甚至几分钟，你改一个错别字想看一眼效果，得等一分钟，这个体验非常劝退。我吃过这个亏，早期用某套 Node 生态的重型方案，文章上到一百五十篇左右，本地预览启动要四十多秒，后来换成一个用 Go 写的单文件程序，同样内容量构建只要几百毫秒。这种差距是每天都能感受到的。

第二条，依赖复杂度。有些生成器需要一整套运行时环境加一堆插件依赖，换个电脑、换台系统，环境重建能耗掉半天；有些则是单个可执行文件，下载下来就能跑，跨平台零配置。对新手来说，后者的友好度是碾压级的——你不需要理解依赖管理，也不需要处理版本冲突。

第三条，主题与文档的可得性。这点常被忽略但极重要。生成器再强，如果没有现成好看的主题、没有清晰的中文文档，新手光调样式就能劝退。我的经验是：优先选那些主题库丰富、且社区里有大量"改主题"范例的方案，这样你遇到问题时搜一下大概率有人踩过同样的坑。

我的实际组合：Go 语言编写的单文件生成器 + 一套二次元风格很克制的中性主题。选它不是因为功能最强，而是因为"下载即用、构建极快、主题改起来像改 HTML 一样直观"。

顺带说一句工具链上的小事。编辑器方面我用的是支持 Markdown 实时预览的文本编辑器，插件只装了三个：语法检查、图片粘贴自动上传、以及一个能快速插入 Front Matter 模板的片段插件。别装太多，插件越多启动越慢，写作工具的第一要求是"打开就能写"。

2. 动笔之前：十分钟里最容易被浪费的准备工作

很多人卡在"十分钟搭不完"，原因往往不是操作复杂，而是准备工作没做完就开始动手，中途被打断去找环境、找密码、找路径。我把准备工作压缩成三件必须提前确认的事，做完这三件，后面的每一步都是顺的。

2.1 本地环境的最小清单

不需要装一整套开发环境，只要满足以下两条里的一条即可：

• 方案 A（推荐给新手）：装一个版本控制客户端和对应命令行工具，再装生成器的单文件程序。前者负责把本地文件推送到远端仓库，后者负责本地预览。两个加起来安装包不到一百兆。
• 方案 B（推荐给完全不想碰命令行的人）：只用网页端的代码托管平台，直接在浏览器里新建文件、在线编辑。这条路能走通，但主题配置和批量改文件会很痛苦，只适合"先跑起来看看效果"。

我建议走方案 A。命令行看着吓人，但整套流程用到的命令不超过八条，两次之后就形成肌肉记忆了。安装完成后必须验证两件事：命令行工具能输出版本号，以及生成器程序能被正常调用。这两条验证不通过就往下走，后面一定会在某个奇怪的环节卡住，而且报错信息通常看不懂。

这里有个小技巧：把生成器程序放到一个固定的、路径里没有中文和空格的目录下，然后把该目录加入系统环境变量。这样在任何位置都能直接调用，不用每次写一长串绝对路径。我见过不少人卡在"命令找不到"，排查半天发现是路径里带了个空格。

2.2 仓库与访问地址的两种路径

第二件要提前定的事：你的内容最终以什么地址对外呈现。有两条路：

路径一，用平台分配的默认地址。零配置、零费用、开箱可用，缺点是地址里带一串平台标识，不好记也不好念。如果你的博客定位是"个人记录、给熟人看、搜索引擎能抓到就行"，这条路的性价比最高。

路径二，挂自定义域名。需要你先拥有一个域名，然后在平台侧做解析配置，并开启自动证书。好处是地址干净、可长期持有、换平台时地址不变。代价是要多花十来分钟配置，而且域名本身有年费。

我的建议是先用路径一把流程跑通，验证从写作到发布的完整链路没有问题，再考虑升级到路径二。因为域名解析涉及缓存生效，有时候要等十几分钟甚至几小时，如果一开始就掺进来，你会分不清是"配置错了"还是"还没生效"，排查成本陡增。

注意：如果你打算用仓库里的默认分支作为发布源，务必提前确认该分支名。部分平台默认分支叫 main，部分叫 master，构建配置写错了会一直报"找不到内容"，而这个报错信息通常不会直接告诉你原因。

2.3 先约定目录结构，后面少改十次配置

第三件准备工作，是在纸上（或脑子里）先把目录结构定下来。生成器初始化时会生成一套默认结构，但默认结构往往不适合长期写作，尤其是文章一多、分类一多的时候。我用的结构是这样的：

站点根目录/ ├── content/ # 所有文章，按年份分文件夹 │ ├── 2024/ │ └── 2025/ ├── static/ # 图片、附件等原样拷贝的资源 │ ├── images/ │ └── files/ ├── themes/ # 主题 ├── config.yaml # 全局配置 └── build/ # 构建产物（不提交进版本库）

关键点在于两个：第一，文章按年份分目录，避免单一目录下堆积几百个文件，找起来眼花；第二，构建产物目录一定要写进忽略规则，绝不能提交进版本库，否则每次构建都会产生几百个文件的变更记录，仓库很快就臃肿得没法看。

这套结构定下来之后，后面所有的配置、插件、脚本都围绕它来写，几乎不用再动。我见过太多人一边写一边改目录，结果图片路径失效、文章链接全断，返工时间远超前期规划的时间。

3. 核心实操：从空文件夹到线上可访问

前面三节铺垫完，接下来是真正的动手部分。我把整个过程拆成四步，每一步都说明白"这条命令在干什么"和"这个参数为什么这么填"。你照着做，正常情况十分钟内能看到自己的页面。

3.1 初始化与主题落地

第一步是生成站点骨架。各家生成器的命令不同，但形式高度一致：

# 通用形式，具体命令以你选的生成器官方文档为准 <generator-cli> new site my-blog cd my-blog

这条命令做的事情很简单：按内置模板创建目录结构、生成一个默认配置文件、创建空的文章目录。执行完之后，你不需要急着写文章，先做主题。

主题的引入方式有两种，我强烈建议用子模块方式或者直接下载解压，而不是用包管理器安装。原因很实际：主题的样式文件你十有八九要改（改个配色、调个字号、换个字体），如果走包管理器，改完之后一旦更新主题就会被覆盖；而子模块或解压的方式，你的修改是独立存在的，可控。

# 方式一：克隆主题仓库到主题目录 git clone <theme-repo-url> themes/my-theme # 方式二：直接下载压缩包解压到 themes/ 下，改个文件夹名

主题落地之后，第一件事是在配置文件里把主题名对上，然后本地启动预览：

<generator-cli> server

正常情况下终端会打印一个本地地址，浏览器打开就能看到默认页面。如果这一步报错，九成是主题名写错了，或者主题目录里缺少关键的模板文件。别慌，先看报错里提到的文件名，对照主题目录看是否存在，问题基本就定位了。

实操心得：本地预览默认是热重载的，改文件会自动刷新。但如果你改了配置文件（不是文章），往往需要重启预览进程才生效。这个小差异让我早期浪费了不少时间，一直以为配置没写对，其实是没重启。

3.2 配置文件里真正要动的六项

默认配置文件有几十项，但真正必须改的只有六项。我逐项说明为什么要改，以及常见的填错方式：

第一项，站点基础地址。这一项决定了站内所有绝对链接的生成方式。填错了会导致样式文件、图片全部 404。规则是：如果你用平台默认地址，就填平台给的完整地址（带 https 前缀、不带末尾斜杠）；如果暂时不确定，可以先留空，改用相对链接模式。

第二项，站点标题与副标题。这个影响页面标题和搜索引擎摘要。标题别写太长，超过三十个字符在搜索结果里会被截断。

第三项，默认内容语言。影响页面的语言标记和部分主题的字体渲染。填成正确的语言代码，中文排版会正常很多，尤其是标点符号和字间距。

第四项，文章永久链接格式。这是最容易被忽略但影响最深远的一项。我的建议是从一开始就定成"年份/月份/文件名"的层级结构，一旦发布过文章再改格式，所有外部链接全断。

# 配置示例（结构通用，字段名以你的生成器为准） baseURL: "https://your-name.example.com/" title: "我的技术笔记" language: "zh-cn" permalinks: posts: "/:year/:month/:slug/"

第五项，构建输出目录。默认通常是 public 或 build，改成你习惯的名字即可，但一定要同步更新忽略规则和平台的构建配置，三处必须一致。

第六项，分页数量。首页一页放几篇。这个值建议在 10 到 20 之间，太少显得空，太多首屏加载慢。

3.3 接入托管平台的自动构建

这一步是整套方案的核心机制。原理说透了其实很简单：你把源文件和 Markdown 提交到代码仓库，托管平台检测到推送，就按照你提供的一条构建命令，在一台临时机器上把站点生成出来，然后把生成好的纯静态文件分发到它的全球节点上。整个过程你不需要操心服务器。

配置集中在仓库的设置页，通常需要填三件事：

填完之后推送一次代码，观察构建日志。日志里会显示每一步耗时，正常情况下从触发到可访问在三十秒到两分钟之间。如果失败，日志会明确指出是哪个步骤出错——这一步的日志一定要看懂，它是后面所有排查的基础。

注意：第一次推送不要把构建产物目录提交上去。有些人生成完就直接全量提交，结果平台又构建了一遍，输出目录里套着输出目录，页面能打开但样式全乱。忽略规则的写法取决于你的版本控制工具，核心就是一行：把构建目录排除掉。

3.4 让自定义域名和证书自动跑起来

如果你决定走自定义域名这条升级路线，配置顺序很重要：先在域名侧加一条解析记录，指向平台给出的目标地址；再在平台侧填写域名并开启自动证书；最后等解析生效。

解析记录的类型通常是 CNAME，主机记录填子域前缀（比如 www 或 blog），记录值填平台提供的目标地址。这一步最容易出错的地方是在记录值末尾多写了斜杠或者少写了点，导致解析不生效。填完可以用命令行查一下解析结果：

# 查询某域名的解析情况 nslookup blog.example.com

如果返回的地址和你填的一致，说明解析已经生效。接下来是证书，现在主流平台都支持一键自动签发和续期，你不需要手动上传任何文件，只需要确保解析已经生效、平台能完成验证。证书签发通常在几分钟内完成。

这里要提醒一句关于 HTTPS 的细节：开启证书之后，务必确认站内所有资源引用都是 https 协议或者相对路径。混用 http 会导致浏览器把整个页面标记为不安全，虽然不影响访问，但对个人品牌形象是个减分项。

4. 写作工作流：把更新变成不需要意志力的事

站点搭起来只是开始，真正决定这个博客能活多久的，是更新流程的摩擦力有多大。我的原则是：从产生写作冲动到内容上线，中间的操作步骤不能超过三步，总耗时不能超过两分钟。超过这个阈值，人就会找借口拖延。这一节讲怎么把流程压到这个程度。

4.1 用一个模板榨干 Front Matter 的价值

每篇文章开头那段元信息（通常叫 Front Matter）决定了它怎么被渲染、怎么被分类、怎么被检索。新手最容易犯的错是每篇都手写，字段名还写错。正确做法是做一份模板，新建文章时直接复制。

--- title: "文章标题" date: 2025-01-15T10:30:00+08:00 draft: false slug: "my-article-slug" tags: ["工具", "效率"] categories: ["实践记录"] summary: "一句话摘要，会出现在列表页和搜索摘要里" --- 正文从这里开始……

几个字段值得单独说。slug决定了这篇文章的网址，一旦发布不要再改，改了外部链接就断。建议用英文小写加连字符，短而清晰，别用中文也别用日期当 slug。draft是草稿开关，写一半的东西设成 true，构建时会被自动排除，不会误发布。summary值得认真写，它既影响列表页的观感，也影响搜索结果里的摘要显示，写好了能明显提升点击率。

我的做法是在模板里预置好分类和常用标签，新建时只改标题和 slug，其余保持默认。这样一篇新文章从创建到能开始写正文，只花十秒。

4.2 图片处理：决定站点速度的隐形杀手

我见过太多博客，文字内容不多，但首页加载要五六秒，原因几乎清一色是图片没处理。三张手机直出照片，每张五六兆，直接拖进文章里提交，页面就废了。

处理原则有三条，按重要性排序：

第一条，格式优先选现代格式。同等画质下，新式图片格式的体积通常只有传统格式的三到五成。如果主题支持，优先用它。不支持的场景再退回传统格式。

第二条，宽度控制在内容区宽度的两倍以内。绝大多数博客正文区宽度在 700 到 900 像素之间，考虑高分屏，图片宽度做到 1400 到 1600 像素就完全够用。手机直出照片动辄 4000 像素宽，全是浪费。

第三条，图片不进版本库的"原图区"。我一般会保留一个本地原图文件夹，只把压缩后的成品提交进去。这样仓库不会膨胀，克隆和构建都更快。

# 批量压缩示例（工具名以你实际使用的为准） # 思路：指定最大宽度 + 质量参数，输出到 static/images/ <image-tool> input.jpg --resize 1600 --quality 82 --output static/images/post-001.jpg

实测下来，一张 5 兆的手机照片按上面的参数处理完通常在 200 到 400 KB，画质在正文尺寸下几乎看不出差别。这个优化带来的首屏速度提升非常直观。

4.3 分支策略：给"写一半"留一条安全通道

单人博客也需要分支策略吗？需要，但可以极简。我用两条分支：

• 主分支：对应线上正式内容，只有确认无误的内容才合并进来。
• 草稿分支：日常写作、试验主题改动都在这上面。

这样有个明显好处：你可以把没写完的系列文章放在草稿分支里慢慢磨，主分支始终是干净的。更进一步，如果你的托管平台支持预览部署，草稿分支可以自动生成一个临时预览地址，你可以在手机上看排版效果，确认没问题再合并。

# 日常节奏示意 git switch draft # 写写写 git add content/ static/images/ git commit -m "新增：某主题的实践记录" git push origin draft # 确认无误后合并 git switch main git merge draft git push origin main

这套流程看起来多两步，但它给了你一个心理上的安全垫：知道主分支永远是好的，写作时就不会有"改坏了怎么办"的顾虑。这个心理成本其实比操作成本更影响产出。

5. 常见问题与排查实录

下面这些是我这些年被问得最多、也是我自己真实踩过的坑。按发生频率排序，每条都给定位思路，而不是只给答案——因为环境不同，答案未必一样，但思路是通用的。

5.1 构建失败速查表

构建失败是最常见的问题，日志通常很长，但真正有用的信息就那么几行。我整理了一张速查表，按报错特征反查原因：

这里特别说一下"构建成功但页面空白"这一类。它最迷惑人，因为日志里全是绿色的成功标记。定位方法很直接：在本地跑一次完整构建，然后打开输出目录，看里面到底有没有 index.html。如果本地有、线上没有，那就是输出目录路径对不上；如果本地也没有，那就是构建命令根本没产出内容，去看命令是不是漏了参数。

一个屡试不爽的技巧：把构建命令在本地终端里原样跑一遍。九成的线上构建问题，在本地复现时都能一眼看出原因，因为本地你能看到完整的、没有被日志截断的输出。

5.2 样式丢失与资源 404 的定位方法

页面能打开，但一片白底黑字，没有任何样式——这是第二高频问题。本质只有一个：CSS 文件的请求地址不对。

定位步骤我固定成三步：

1. 浏览器打开页面，按下开发者工具的快捷键，切到网络面板，刷新页面。
2. 找状态码是 404 的请求，看它请求的完整地址。
3. 拿这个地址和你实际的文件位置对比，差异在哪一目了然。

最常见的差异有两种。第一种是地址里多了一层或多层路径，通常因为站点基础地址配置里带了子路径，而资源引用是绝对路径。第二种是协议不一致，页面是 https 但资源引用是 http，被浏览器拦截。

处理方式也很固定：优先改用相对路径引用，或者把站点基础地址配置成最终的真实地址（带协议、不带末尾斜杠）。改完记得清一次浏览器缓存再验证，否则你看的还是旧文件，会误以为没生效。

5.3 访问速度优化：先分清是慢在哪一段

"我的博客打开很慢"这句话信息量太低，得先拆开看慢在哪一段。用开发者工具的网络面板看两个数字：首字节时间和总加载时间。

• 首字节慢（超过一秒）：说明是服务端或网络链路的问题。静态站点这种情况少见，通常发生在自定义域名解析到了不理想的节点，或者域名解析本身慢。可以考虑开启平台自带的加速功能，或者检查解析记录是否指向了就近节点。
• 首字节快但总加载慢：说明是资源体积问题。这时候去看网络面板里按体积排序，最大的那几个文件就是元凶，九成是图片或者没压缩的字体文件。

我做过一次对比测试，同一个站点，图片从平均 800 KB 压到 250 KB，首屏可交互时间从 3.2 秒降到 1.4 秒。这个提升幅度比换任何框架都明显，而且成本只是批量跑一次压缩脚本。

还有一个常被忽略的点：字体文件。很多主题默认加载好几套网络字体，中文字体文件动辄几兆。如果不是非用不可，建议改成系统字体栈，速度提升立竿见影，视觉差异在正文阅读场景下几乎感知不到。

6. 踩过之后才明白的几个细节

前面讲的是"怎么做"，这一节讲的是"做完之后会遇到什么"。这些内容在任何官方文档里都找不到，因为它们是时间和使用量堆出来的经验。

6.1 缓存：让你怀疑人生的那一层

内容明明改了，线上还是旧的。这种情况我第一次遇到时排查了整整一个下午，最后发现是缓存。

缓存在这条链路上有三层：浏览器本地缓存、平台边缘节点缓存、以及你自己的构建缓存。三层叠加，症状就是"改了但看不到"。

排查顺序建议自下而上：先强制刷新浏览器（多数浏览器支持跳过缓存的刷新方式），再换一个从没访问过该站点的浏览器或无痕窗口验证，最后看平台侧的部署记录，确认新版本确实已经上线。三层都排除了，才是真的有问题。

日常规避手段有两个：一是给资源文件加版本标识（很多生成器支持自动给 CSS、JS 加哈希后缀）；二是在配置文件里给不同资源设置不同的缓存策略，HTML 短缓存、静态资源长缓存。这套配置一次做好，后面基本不用再操心。

6.2 备份：你的内容比你的站点值钱

站点配置丢了可以重搭，文章丢了就是真的丢了。而静态博客有个天然优势：所有内容都是纯文本，天然适合版本控制。

但"提交进仓库"不等于"备份完成"。我见过有人把所有文章都放在一个仓库里，仓库所在账号出问题，内容就没了。稳妥做法是双远端：主仓库放在常用的托管平台，同时配置一个备用远端，每次推送同时推到两处。

# 添加第二个远端 git remote add backup <backup-repo-url> # 一次推送两处 git push origin main && git push backup main

更进一步，可以写个提交后自动执行的钩子，把这条命令固化下来，连记都不用记。这套机制运行两年，我一次都没用上，但知道它在那儿，写作时的心态是完全不一样的。

6.3 长期维护成本核算

最后算一笔账，把"零成本"这件事说清楚，避免有人被"免费"两个字误导。

直接的金钱成本：生成器零元，托管与构建在个人量级下零元，域名可选（不挂就是零元）。这一项确实是零。

间接的时间成本才是真正要衡量的：

看这张表能得出一个结论：这套方案的维护成本极低，真正的时间全花在写作本身上——而这恰恰是你想花时间的地方。对比动态方案，光是安全更新、数据库备份、服务器续费这三件事，一年就能吃掉好几个小时，还不算提心吊胆的心理成本。

我个人在实际操作中的体会是：静态博客最大的价值不是省钱，而是把"维护"这件事从日常心智里彻底移除了。你打开电脑，唯一要做的事情就是写。这种纯粹的写作状态，是任何功能丰富的建站系统都给不了的。

如果你想在这套基础上再往前走一步，我建议的方向是内容组织而不是功能堆叠。比如做一套自己的标签体系、给长文加目录锚点、给系列文章加前后篇导航。这些改动都不需要引入新服务，只是把已有内容重新组织，但对读者的阅读体验提升，往往比装十个花哨插件更明显。