1. 先算清楚这笔账静态博客到底省下了什么我这些年帮不少人搭过个人博客发现一个挺有意思的现象真正卡住他们的不是技术门槛而是选择了涉及范围最广的一条路——买服务器、装数据库、配置运行环境、定期打补丁、担心被人扫描。到头来博客写了三篇服务器续费了两年。后来我把这套流程推倒重来用静态博客 代码托管平台的组合去做从空目录到公网可访问熟练之后十分钟确实能完成一次。这套方案的核心不是“省钱”两个字而是把一件需要长期运维的事拆成了一次性配置加持续写作。你写完 Markdown 推一次代码剩下的编译、分发、证书续期全部由流水线接管没有数据库没有后台进程也没有半夜告警。这篇内容我打算讲清楚三件事为什么静态方案在个人博客这个场景下几乎是最优解、一台干净的电脑怎么在十分钟内把它跑通、以及跑通之后那些真正决定“能不能用上三年”的细节。适合的读者范围很宽——会复制命令、能看懂 YAML 缩进就行前端经验不是必需的如果你已经用过某个博客框架但一直没上线那更容易对上号因为我下面会重点讲那些“文档里不写、但一写就错”的地方。为了避开广告嫌疑文中涉及的平台和工具一律用代称我会把每个代称的特征描述清楚你按特征去对应市面上任意一款同类产品都成立。1.1 静态博客解决的到底是什么问题先把概念说实在一点。所谓静态博客指的是在构建阶段就把所有页面提前生成成 HTML 文件用户访问时拿到的是一堆已经做好的文件而不是由服务器临时查库、拼装、渲染出来的页面。这个差别看着小影响很大。动态博客每来一个访客服务器都要跑一遍程序逻辑访问量一上来 CPU 就吃紧被人恶意刷请求也扛不住静态博客的每个请求都只是“把文件递出去”天然抗压天然省钱天然没漏洞可挖——因为它压根没有可执行的后端逻辑暴露在公网上。对个人博客这种场景这个特性几乎是量身定做的。个人博客的典型特征是作者一个人更新频率不高内容以长文为主读者多为搜索或分享进来需要的是打开快、能被搜索引擎抓到、链接长期有效。这些需求静态方案全都满足而且满足得比动态方案更干脆。真正的功能短板出现在评论区、全文检索、访问统计这些地方但这些都有成熟的第三方轻量方案可以挂或者干脆用“邮件订阅 外链讨论区”的方式绕过去——我个人更推荐后者一个人维护博客能不引入需要自己照看的服务就不引入。还有一个常被忽略的价值静态博客的内容是可迁移资产。你的文章是一个个纯文本文件加上版本历史跟着代码仓库走。哪天你对某个平台不满意换个托管方几分钟的事链接结构甚至可以完全保持不变。这一点用过动态博客的人都懂从某套系统里把文章导出来图片路径全乱标签全丢那种经历一次就够了。1.2 “零成本”的边界在哪里别自己骗自己说零成本得说清楚哪部分零成本、哪部分不零。我把这套方案的支出结构拆成四块来看费用项是否真的零成本说明内容存储源码仓库是公开仓库的容量和协作额度通常远大于个人需求几千篇文章的纯文本加图片也就几百兆构建与发布流水线基本是免费额度按构建时长计算纯静态站点单次构建通常在几十秒到两分钟个人更新频率很难跑满访问分发静态托管 分发网络基本是按流量计费的免费额度对个人博客绰绰有余月度访问量在几万 PV 量级基本碰不到线域名不是平台自带的免费二级域名可零成本使用自定义域名需要按年付费所以准确的说法是技术上零成本品牌上不零成本。用平台分配的免费二级域名你会得到一个形如“项目名.平台域名”的地址能用、能分享、能被搜索收录但不好记、不够体面将来换平台还会断链。我的建议很明确——先用免费二级域名把整条链路跑通确认这套东西你确实会用下去再去买域名。顺序反了的话非常容易变成“域名买了一年站点还是空白页”。注意自定义域名通常涉及额外的解析配置和登记流程不同环境要求差异很大这部分不在本文范围里先用平台提供的默认地址验证功能即可。另外要提醒一句免费额度的“隐性成本”。多数平台的免费额度都有并发构建数、单次构建时长、月度构建总时长的限制。如果你在模板里塞了自动压缩全站大图、自动做多语言编译这类重活一次构建可能跑到十几分钟那就容易撞线。解决办法不是升级套餐而是把这些重活挪到本地做一次把处理结果提交进仓库——我在第 4 章会具体讲这个取舍。2. 架构拆解三层结构怎么搭才不容易塌这套系统的骨架其实就三层理解了三层任何一款具体工具的文档你都能快速看懂因为它们换汤不换药。我把它画成一句话内容层放源文件生成层把源文件编译成网页托管层把网页分发给读者。三层之间只有单向的数据流动从内容到生成到托管绝不反向这个约束是整个方案能长期稳定的根本原因。2.1 内容层Markdown 是唯一的真相内容层就是一堆 Markdown 文件每个文件对应一篇文章开头用一段结构化的元信息俗称 front matter描述标题、日期、标签、摘要、是否草稿。这段元信息是 YAML 格式用三条短横线包起来形如--- title: 我的第一篇正式文章 date: 2025-03-14 21:30:00 tags: [随笔, 工具] draft: false summary: 一句话说明这篇文章讲什么用于列表页和搜索结果摘要 --- 正文从这里开始正常写 Markdown 就行。为什么坚持用 Markdown 而不是所见即所得的富文本三个理由。第一它是纯文本任何编辑器都能开二十年后依然能读不存在“格式过时打不开”的问题。第二它是版本友好的用 Git 管理时每次改动都是一行行的差异而不是“整个文件二进制全变”出问题能精确定位。第三它逼你把注意力放在内容结构上——标题层级、列表、引用、代码块这些结构一旦规范后面做样式和做索引都会省很多事。这里有个细节坑第一次搭的人十有八九会踩元信息里的日期格式和时区。不同生成器对日期的解析规则不一致有的要求YYYY-MM-DD有的要求带时间有的默认按本地时区处理、有的按 UTC。如果你发现文章列表的排序莫名其妙或者某篇文章“消失了”八成是日期写错格式导致它被解析成一个未来时间或者无效值。我的做法是统一写成YYYY-MM-DD HH:mm:ss并在配置里显式指定时区偏移然后在本地预览时检查列表页顺序一次定死后面照抄。2.2 生成层模板加内容编译成静态文件生成层的工作可以被拆成四步理解这四步你排查问题时就不会瞎猜扫描遍历内容目录收集所有 Markdown 文件及其元信息转换把 Markdown 正文转成 HTML 片段同时对代码块做语法高亮套版拿模板布局文件把片段包起来生成完整页面同时生成列表页、标签页、归档页、分页页输出把结果写进一个专门的产物目录。关键点在于产物目录是构建输出不是源码。我第一次搭的时候犯过一个典型错误把产物目录也提交进了仓库结果每次构建都产生几千个文件的变更提交历史脏得没法看还出现过源码和产物不同步、线上和本地不一致的诡异现象。正确做法是把产物目录写进忽略清单只让流水线在构建时生成它。想验证也很简单源码仓库里应该只有配置、模板、内容、静态资源这四类东西除此之外的都值得怀疑。生成速度是选型时最容易被夸大的一项指标。我实测下来几百篇文章的规模主流生成器差别也就是几秒到十几秒对个人站点毫无意义。真正值得关心的是增量构建和模板调试的体验改一行样式本地预览能不能在一秒内热更新改一个布局构建报错信息够不够具体这些才是你天天要打交道的地方。2.3 托管层代码托管与静态分发的分工很多人把这两件事混在一起其实职责很清楚。代码托管平台负责存源码、管版本、跑流水线静态分发服务负责把产物目录变成一个可访问的网站处理 HTTPS 证书、缓存策略、路径重写。有些平台把两件事合在一处有些分开但逻辑等价。三层之间靠一条流水线串起来触发条件是“向主分支推送”。完整链路是这样你在本地写完文章git addgit commitgit push平台检测到推送启动一个干净的环境拉取源码、安装依赖、执行构建命令、拿到产物目录然后把产物同步到分发服务分发服务再把它推送到边缘节点。整个过程通常在一到三分钟内完成期间线上仍是旧版本切换是原子的——这点很重要意味着读者永远不会看到“构建到一半”的半成品页面。2.4 生成器怎么选三个维度的对照市面上主流的静态站点生成器可以粗分成三类我用代称描述特征你按特征对号入座即可。类型典型特征上手难度构建速度适合谁A 类老牌模板型生态最成熟主题和插件数量庞大配置以一份主配置文件为核心低中等文章多了会变慢想尽快上线、不想折腾设计的人B 类单文件快速型单个可执行文件无需安装运行环境构建极快模板语法自成体系中快有几百篇以上存量文章、追求构建效率的人C 类组件框架型基于现代前端组件体系可深度定制交互能做局部动态渲染中高中等偏慢有前端基础、想把博客做成半个产品的人我自己的判断标准很务实如果你现在只是想写文章选 A 类如果你已经攒了几百篇、构建时间开始难受迁到 B 类如果你明确知道自己要做非标准交互比如站内小工具、可视化文章选 C 类。别一开始就奔着“最强”去那不是选型那是给自己找活干。我见过太多人卡在“挑哪个框架”上纠结一周最后一篇文章没写——这才是最大的成本。3. 十分钟落地从空目录到公网可访问这一段是整篇的核心我会按真实操作顺序走一遍每一步都说明“为什么这么做”。前提假设一台装了命令行工具的电脑能用编辑器能看懂 YAML 缩进。为保持通用命令里的路径和项目名用占位符。3.1 环境准备只装两样东西真正必需的只有两样版本控制工具和运行时环境用来跑生成器。装完验证一下git --version node --version npm --version三条都有输出就说明环境齐了。如果第二条报“命令未找到”说明运行时没装或者没进环境变量——这是最常见的第一个卡点。装完记得重开一个终端窗口很多人就是因为旧窗口没刷新环境变量白白以为自己装失败了。再补一句经验如果你的系统上有多个运行时版本建议用版本管理器统一管否则不同项目依赖不同版本时会出现“本地能构建、流水线构建失败”的经典问题。判断依据很简单——本地node --version的输出必须和你流水线配置里指定的版本完全一致。这一条能省掉后面一大半莫名其妙的报错。3.2 目录结构与初始化现在开始两条命令拿到一个可用的骨架# 用生成器自带的脚手架初始化到 blog 目录 npx generator-cli init blog cd blog初始化完成后先别急着改配置花三十秒把目录看一遍。典型的目录长这样blog/ ├── config.yml # 主配置文件站点标题、地址、主题、菜单 ├── content/ # 内容目录文章和页面都在这里 │ ├── posts/ # 文章 │ └── about.md # 独立页面 ├── themes/ # 主题目录 ├── static/ # 静态资源图片、favicon、附件 ├── package.json # 依赖与脚本定义 └── .gitignore # 忽略清单务必包含产物目录先把忽略清单处理干净这是我建议新手做的第一件事。确认.gitignore里包含产物目录、依赖目录、系统临时文件。省掉后面一次“提交历史被污染”的返工成本极低。3.3 配置文件逐项拆解配置文件是骨架里最容易出错的地方我把几个必须改的项拆开讲配置项填什么填错的后果站点基础地址最终访问用的完整地址含协议资源路径、站点地图、分享卡片全部错乱站点标题与副标题你的博客名和一句话介绍只影响展示随便改文章路径规则建议用“年/月/标题”或“分类/标题”上线后再改会导致旧链接全部失效主题先用自带的默认主题换主题会覆盖自定义模板别一开始就硬改时区与你写作习惯一致的偏移量文章排序错乱、发布时间显示不一致其中站点基础地址这一项最要命也最容易被忽略。它的作用是拼接所有绝对路径。如果你先填了本地地址http://localhost:4000就去构建那发布到线上之后所有图片和样式表都会去请求本机地址页面直接白给你看。我第一次犯这个错排查了半小时才想起来是这一行没改。所以正确的顺序是先在配置里把正式地址填对本地预览用命令行参数临时覆盖而不是把它改成localhost再改回来。3.4 写第一篇内容与本地预览新建一个 Markdown 文件放在文章目录下元信息照 2.1 的模板写正文随便写两百字然后启动本地预览npm run dev如果脚本名不一样去package.json的scripts里看一眼就知道不必照抄命令。启动后浏览器打开提示的地址你会看到一个能点、能翻页的站点。这一步能跑通说明内容层和生成层都没问题剩下的只是托管。这里补充一个实操心得本地预览的端口经常被占用如果启动报端口冲突不要慌生成器一般支持指定端口或者先把占用进程关掉。另外预览环境的地址和正式环境的地址不同所以涉及绝对路径的资源比如分享卡片图、站点地图在本地看起来可能是坏的这属于正常现象别在这里浪费时间。3.5 推送到远端与自动化流水线先在代码托管平台上建一个空仓库拿它的地址关联到本地然后推上去git init git add . git commit -m 初始化博客 git remote add origin 你的仓库地址 git branch -M main git push -u origin main接着配置流水线。不同平台的配置文件路径和字段名不一样但结构高度一致我用中文步骤名写一份结构示意你按所用平台的文档把字段名替换掉即可# 流水线配置示意字段名以所用平台文档为准 name: build-and-deploy 触发条件: 推送到 main 分支时执行 任务: - 步骤: 检出源码 - 步骤: 安装运行时版本必须与本地一致 - 步骤: 安装依赖用锁文件安装保证可复现 - 步骤: 执行构建命令 - 步骤: 将产物目录发布到静态分发服务几个关键点值得单独强调。安装依赖一定要用锁文件模式也就是npm ci这类强制按锁文件装的方式而不是随意的npm install前者能保证流水线装到的依赖版本和你本地一模一样后者在依赖有小版本更新时可能给你装出不同的东西造成“本地好好的、线上编译报错”。运行时版本要显式指定不要依赖环境中预装的版本。产物目录要单独指定成发布目标别让它把整个仓库都发上去——这会导致源码被公开下载虽然本来也是公开的但会多出几百个无意义的可访问路径。3.6 上线校验六项逐条过发布成功不等于能用我每次上线都会把这六项过一遍首页能打开样式正常没有大片白屏进一篇文章详情页确认图片能显示、代码块有高亮点一次翻页确认分页链接指向正确访问一个不存在的地址确认返回的是自定义的提示页而不是平台默认的广告页看源码确认页面里没有残留localhost之类的本地地址在手机上看一次确认布局在窄屏下没有横向滚动条。这六项里第 4 项最容易被忽略。默认情况下访问不存在的路径会落到平台自己的 404 页面那上面往往带着平台品牌信息观感很差。多数分发服务支持配置自定义提示页把产物目录里生成的页面路径填进去就行一行配置的事。4. 让它跑得快、跑得久优化与维护的关键细节能访问只是起点。真正决定这套东西好不好用的是三件事首屏速度、内容能不能被找到、以及三年后你还敢不敢动它。这一章全是我在实际运维中觉得最值钱的部分。4.1 图片是首屏速度最大的敌人静态站点本身没有什么服务端开销所以性能瓶颈几乎总是出现在图片上。给你算一笔账一张手机拍的原始照片宽度 4000 像素左右文件大小常在 3 到 4 MB。如果你的首页列表页每篇都放一张封面图一屏显示五篇那就是 15 MB 起步。按常见的移动网络条件估算光是把这些图下载完就要十几秒而访问者的耐心通常只有两三秒。处理方法很简单三步走# 思路示意尺寸压到目标宽度再转成现代格式 # 工具不限命令行或图形界面都行 压缩工具 --resize 1600x --quality 82 封面.jpg限制宽度正文配图宽度压到 1600 像素内足够封面图压到 1200 像素内头像和缩略图压到 400 像素内。多数场景下这个宽度在视网膜屏上依然清晰。换成现代格式同等观感下现代图片格式的体积通常只有传统格式的六成甚至更低一张 4 MB 的图压完常在 200 KB 上下。加上尺寸声明在模板里给图片标签写明宽高避免页面加载过程中布局反复跳动这个跳动会显著拉低体验评分。我自己的习惯是原始大图不进仓库只在仓库里放压缩后的版本原图另外存一份离线备份。这么做有两个好处仓库体积小、拉取快流水线构建也不会因为要处理大图而超时。压缩这一步完全在本地手动做不做成流水线的自动任务——自动压缩看着聪明实际上是构建时长和不可预测性的双重来源。4.2 站点结构与索引基础想让文章被搜到不需要多高深的手段把基础项做对就超过了大多数个人博客。四件事第一每篇文章的标题和摘要要写清楚。列表页和搜索结果里展示的就是这两个字段很多人偷懒让系统自动截取正文前几个字结果摘要是半句话点击率直接掉一半。第二生成站点地图并提交。绝大多数生成器都支持自动生成一份包含所有文章地址的索引文件你只需要在配置里确认开关打开把它放在站点根目录下再去搜索引擎的站长工具里提交一次。这件事做一次长期收益很大。第三保证链接结构稳定。为什么我在 3.3 里强调文章路径规则要提前定死因为一旦上线任何路径变动都会让已被收录的链接变成死链。如果确实要改务必做一次跳转映射把旧地址指向新地址别让积累起来的访问量白白流失。第四加上基础的分享卡片信息。在模板的头部区域补上标题、描述、封面图这几项元信息分享到社交平台时才会显示成一张卡片而不是一条干巴巴的链接。这是纯配置工作十几分钟能做完但观感提升明显。4.3 备份、迁移与内容资产归属这一节是我最想说的因为它不疼不痒但一旦出事就是大事。备份策略源码在远端仓库一份、本地一份这已经有两份了。但仓库本身是有可能被误操作甚至被删除的所以我会额外做一层保险——每周把仓库完整克隆到一个本地目录按日期命名存放。这件事用一个脚本加一个定时任务就能自动化写起来不超过二十行。别用“我以后会注意”来安慰自己我见过不止一个人因为一次误操作丢掉半年内容。迁移路径因为内容全是纯文本加标准 Markdown迁移成本极低。换生成器只需要处理模板和少量元信息字段差异换托管方改一下发布目标地址就行。真正需要注意的是链接结构迁移前导出一份现有全部地址的清单迁移后逐条比对把差异项补成跳转规则。这个动作花半小时能保住几年积累的收录。内容资产归属这一条容易被忽略——确认你用的主题和插件的许可条款允许你的使用方式尤其是商业性质的内容站。多数开源主题非常宽松但少数会要求保留署名删掉署名既不礼貌也可能违反条款。上线前花两分钟看一眼主题目录下的许可文件是个好习惯。5. 常见问题与排查实录那些文档里不会写的东西这一章全部来自实际踩过的坑。我按“现象 → 原因 → 处理”的方式整理你可以当速查表用。5.1 流水线显示成功但访问是 404这是最高频的问题。构建日志一片绿色网站打开却是什么都没有。原因基本逃不出三类现象最可能的原因处理方式首页 404其他路径也全 404发布目标目录配错了指向了一个空目录检查发布配置里的产物目录名和本地实际生成的目录名核对首页能开文章页全 404文章路径规则和产物实际结构不一致对比产物目录里的实际文件夹层级修正路径规则只有部分页面 404那些文件被忽略清单误伤了检查忽略规则确认没有把产物目录下的子目录排除掉排查这类问题有个非常有效的手段在流水线里加一步“列目录”把产物目录的结构打印到日志里。看一眼就知道文件到底生成在哪、叫什么名字比对着文档猜快十倍。5.2 页面能开但样式全丢或者图片全是裂的这个表现非常典型——页面是一片没有样式的纯文本。原因九成是路径问题。要么是站点基础地址填错了前面 3.3 讲过要么是部署到了子路径下而配置里没体现。判断方法很直接浏览器打开开发者工具看那些加载失败请求的完整地址。如果它指向localhost就是基础地址没改如果它少了一段前缀就是子路径配置缺失如果它多了一段重复的前缀那是地址末尾多写了斜杠。这三种情况我全遇到过对症下药一分钟能定位。5.3 流水线构建失败速查报错特征根因解决找不到命令运行时版本不匹配或依赖没装显式指定运行时版本用锁文件安装依赖依赖安装超时依赖源不稳定或依赖树过大换用镜像源配置精简不必要的依赖内存溢出被杀构建过程处理了大量图片或做了全量压缩把重活挪到本地产物提交进仓库某文件解析失败Markdown 元信息里含特殊字符未转义给元信息值加引号避免冒号和引号裸奔构建成功但发布失败发布凭据过期或权限不足重新授权检查目标服务的访问权限其中“元信息里含特殊字符”这条特别隐蔽。比如你的文章标题里有个冒号而你没加引号YAML 解析器就会认为这是键值对的分隔符直接报错。我现在的习惯是元信息里的所有值一律加双引号虽然啰嗦但从不出错。这个习惯帮我省掉了大量排查时间。5.4 几条踩过坑才懂的经验第一条别在主题目录里直接改模板。主题升级时会覆盖你的改动一夜回到解放前。正确做法是把主题当作依赖自定义的部分放在独立的覆盖目录或配置里。我吃过这个亏一次主题更新把首页改了三个小时的布局全冲掉了。第二条草稿机制要用起来。写到一半的文章把元信息里的草稿标记设成真构建时就会被跳过不会出现在列表和索引里。这比“先不发、写在本地备忘录”安全得多也不会出现“忘了改成发布状态”或者“不该发的时候发出去了”的尴尬。第三条提交信息写清楚。更新修改这种提交信息三个月后你自己都看不懂改了什么。我的格式是“类型: 具体内容”比如“文章: 新增静态博客搭建笔记”“修正: 修复归档页日期排序”。这样回头查历史时用关键字一搜就能定位到某次改动。第四条别追求一次配置完美。我见过太多人卡在主题美化、字体选择、动效调优上博客首页做得像产品官网文章列表里躺着两条内容。这套方案的全部价值在于让你尽快开始写剩下的都可以边写边改。先让它上线再让它变好看最后才考虑让它变聪明——这个顺序别颠倒。最后分享一个小习惯。我在仓库根目录放了一个清单文件每次想给站点加功能就先写进清单里标上“想要”和“需要”。一个月后回头看那些标“想要”的十有八九我自己都不想要了。这个做法帮我避免了很多无效折腾也让我把时间真正花在了写东西上——毕竟博客的核心从来不是那套技术栈而是里面有没有值得读的内容。
1. 先算清楚这笔账静态博客到底省下了什么我这些年帮不少人搭过个人博客发现一个挺有意思的现象真正卡住他们的不是技术门槛而是选择了涉及范围最广的一条路——买服务器、装数据库、配置运行环境、定期打补丁、担心被人扫描。到头来博客写了三篇服务器续费了两年。后来我把这套流程推倒重来用静态博客 代码托管平台的组合去做从空目录到公网可访问熟练之后十分钟确实能完成一次。这套方案的核心不是“省钱”两个字而是把一件需要长期运维的事拆成了一次性配置加持续写作。你写完 Markdown 推一次代码剩下的编译、分发、证书续期全部由流水线接管没有数据库没有后台进程也没有半夜告警。这篇内容我打算讲清楚三件事为什么静态方案在个人博客这个场景下几乎是最优解、一台干净的电脑怎么在十分钟内把它跑通、以及跑通之后那些真正决定“能不能用上三年”的细节。适合的读者范围很宽——会复制命令、能看懂 YAML 缩进就行前端经验不是必需的如果你已经用过某个博客框架但一直没上线那更容易对上号因为我下面会重点讲那些“文档里不写、但一写就错”的地方。为了避开广告嫌疑文中涉及的平台和工具一律用代称我会把每个代称的特征描述清楚你按特征去对应市面上任意一款同类产品都成立。1.1 静态博客解决的到底是什么问题先把概念说实在一点。所谓静态博客指的是在构建阶段就把所有页面提前生成成 HTML 文件用户访问时拿到的是一堆已经做好的文件而不是由服务器临时查库、拼装、渲染出来的页面。这个差别看着小影响很大。动态博客每来一个访客服务器都要跑一遍程序逻辑访问量一上来 CPU 就吃紧被人恶意刷请求也扛不住静态博客的每个请求都只是“把文件递出去”天然抗压天然省钱天然没漏洞可挖——因为它压根没有可执行的后端逻辑暴露在公网上。对个人博客这种场景这个特性几乎是量身定做的。个人博客的典型特征是作者一个人更新频率不高内容以长文为主读者多为搜索或分享进来需要的是打开快、能被搜索引擎抓到、链接长期有效。这些需求静态方案全都满足而且满足得比动态方案更干脆。真正的功能短板出现在评论区、全文检索、访问统计这些地方但这些都有成熟的第三方轻量方案可以挂或者干脆用“邮件订阅 外链讨论区”的方式绕过去——我个人更推荐后者一个人维护博客能不引入需要自己照看的服务就不引入。还有一个常被忽略的价值静态博客的内容是可迁移资产。你的文章是一个个纯文本文件加上版本历史跟着代码仓库走。哪天你对某个平台不满意换个托管方几分钟的事链接结构甚至可以完全保持不变。这一点用过动态博客的人都懂从某套系统里把文章导出来图片路径全乱标签全丢那种经历一次就够了。1.2 “零成本”的边界在哪里别自己骗自己说零成本得说清楚哪部分零成本、哪部分不零。我把这套方案的支出结构拆成四块来看费用项是否真的零成本说明内容存储源码仓库是公开仓库的容量和协作额度通常远大于个人需求几千篇文章的纯文本加图片也就几百兆构建与发布流水线基本是免费额度按构建时长计算纯静态站点单次构建通常在几十秒到两分钟个人更新频率很难跑满访问分发静态托管 分发网络基本是按流量计费的免费额度对个人博客绰绰有余月度访问量在几万 PV 量级基本碰不到线域名不是平台自带的免费二级域名可零成本使用自定义域名需要按年付费所以准确的说法是技术上零成本品牌上不零成本。用平台分配的免费二级域名你会得到一个形如“项目名.平台域名”的地址能用、能分享、能被搜索收录但不好记、不够体面将来换平台还会断链。我的建议很明确——先用免费二级域名把整条链路跑通确认这套东西你确实会用下去再去买域名。顺序反了的话非常容易变成“域名买了一年站点还是空白页”。注意自定义域名通常涉及额外的解析配置和登记流程不同环境要求差异很大这部分不在本文范围里先用平台提供的默认地址验证功能即可。另外要提醒一句免费额度的“隐性成本”。多数平台的免费额度都有并发构建数、单次构建时长、月度构建总时长的限制。如果你在模板里塞了自动压缩全站大图、自动做多语言编译这类重活一次构建可能跑到十几分钟那就容易撞线。解决办法不是升级套餐而是把这些重活挪到本地做一次把处理结果提交进仓库——我在第 4 章会具体讲这个取舍。2. 架构拆解三层结构怎么搭才不容易塌这套系统的骨架其实就三层理解了三层任何一款具体工具的文档你都能快速看懂因为它们换汤不换药。我把它画成一句话内容层放源文件生成层把源文件编译成网页托管层把网页分发给读者。三层之间只有单向的数据流动从内容到生成到托管绝不反向这个约束是整个方案能长期稳定的根本原因。2.1 内容层Markdown 是唯一的真相内容层就是一堆 Markdown 文件每个文件对应一篇文章开头用一段结构化的元信息俗称 front matter描述标题、日期、标签、摘要、是否草稿。这段元信息是 YAML 格式用三条短横线包起来形如--- title: 我的第一篇正式文章 date: 2025-03-14 21:30:00 tags: [随笔, 工具] draft: false summary: 一句话说明这篇文章讲什么用于列表页和搜索结果摘要 --- 正文从这里开始正常写 Markdown 就行。为什么坚持用 Markdown 而不是所见即所得的富文本三个理由。第一它是纯文本任何编辑器都能开二十年后依然能读不存在“格式过时打不开”的问题。第二它是版本友好的用 Git 管理时每次改动都是一行行的差异而不是“整个文件二进制全变”出问题能精确定位。第三它逼你把注意力放在内容结构上——标题层级、列表、引用、代码块这些结构一旦规范后面做样式和做索引都会省很多事。这里有个细节坑第一次搭的人十有八九会踩元信息里的日期格式和时区。不同生成器对日期的解析规则不一致有的要求YYYY-MM-DD有的要求带时间有的默认按本地时区处理、有的按 UTC。如果你发现文章列表的排序莫名其妙或者某篇文章“消失了”八成是日期写错格式导致它被解析成一个未来时间或者无效值。我的做法是统一写成YYYY-MM-DD HH:mm:ss并在配置里显式指定时区偏移然后在本地预览时检查列表页顺序一次定死后面照抄。2.2 生成层模板加内容编译成静态文件生成层的工作可以被拆成四步理解这四步你排查问题时就不会瞎猜扫描遍历内容目录收集所有 Markdown 文件及其元信息转换把 Markdown 正文转成 HTML 片段同时对代码块做语法高亮套版拿模板布局文件把片段包起来生成完整页面同时生成列表页、标签页、归档页、分页页输出把结果写进一个专门的产物目录。关键点在于产物目录是构建输出不是源码。我第一次搭的时候犯过一个典型错误把产物目录也提交进了仓库结果每次构建都产生几千个文件的变更提交历史脏得没法看还出现过源码和产物不同步、线上和本地不一致的诡异现象。正确做法是把产物目录写进忽略清单只让流水线在构建时生成它。想验证也很简单源码仓库里应该只有配置、模板、内容、静态资源这四类东西除此之外的都值得怀疑。生成速度是选型时最容易被夸大的一项指标。我实测下来几百篇文章的规模主流生成器差别也就是几秒到十几秒对个人站点毫无意义。真正值得关心的是增量构建和模板调试的体验改一行样式本地预览能不能在一秒内热更新改一个布局构建报错信息够不够具体这些才是你天天要打交道的地方。2.3 托管层代码托管与静态分发的分工很多人把这两件事混在一起其实职责很清楚。代码托管平台负责存源码、管版本、跑流水线静态分发服务负责把产物目录变成一个可访问的网站处理 HTTPS 证书、缓存策略、路径重写。有些平台把两件事合在一处有些分开但逻辑等价。三层之间靠一条流水线串起来触发条件是“向主分支推送”。完整链路是这样你在本地写完文章git addgit commitgit push平台检测到推送启动一个干净的环境拉取源码、安装依赖、执行构建命令、拿到产物目录然后把产物同步到分发服务分发服务再把它推送到边缘节点。整个过程通常在一到三分钟内完成期间线上仍是旧版本切换是原子的——这点很重要意味着读者永远不会看到“构建到一半”的半成品页面。2.4 生成器怎么选三个维度的对照市面上主流的静态站点生成器可以粗分成三类我用代称描述特征你按特征对号入座即可。类型典型特征上手难度构建速度适合谁A 类老牌模板型生态最成熟主题和插件数量庞大配置以一份主配置文件为核心低中等文章多了会变慢想尽快上线、不想折腾设计的人B 类单文件快速型单个可执行文件无需安装运行环境构建极快模板语法自成体系中快有几百篇以上存量文章、追求构建效率的人C 类组件框架型基于现代前端组件体系可深度定制交互能做局部动态渲染中高中等偏慢有前端基础、想把博客做成半个产品的人我自己的判断标准很务实如果你现在只是想写文章选 A 类如果你已经攒了几百篇、构建时间开始难受迁到 B 类如果你明确知道自己要做非标准交互比如站内小工具、可视化文章选 C 类。别一开始就奔着“最强”去那不是选型那是给自己找活干。我见过太多人卡在“挑哪个框架”上纠结一周最后一篇文章没写——这才是最大的成本。3. 十分钟落地从空目录到公网可访问这一段是整篇的核心我会按真实操作顺序走一遍每一步都说明“为什么这么做”。前提假设一台装了命令行工具的电脑能用编辑器能看懂 YAML 缩进。为保持通用命令里的路径和项目名用占位符。3.1 环境准备只装两样东西真正必需的只有两样版本控制工具和运行时环境用来跑生成器。装完验证一下git --version node --version npm --version三条都有输出就说明环境齐了。如果第二条报“命令未找到”说明运行时没装或者没进环境变量——这是最常见的第一个卡点。装完记得重开一个终端窗口很多人就是因为旧窗口没刷新环境变量白白以为自己装失败了。再补一句经验如果你的系统上有多个运行时版本建议用版本管理器统一管否则不同项目依赖不同版本时会出现“本地能构建、流水线构建失败”的经典问题。判断依据很简单——本地node --version的输出必须和你流水线配置里指定的版本完全一致。这一条能省掉后面一大半莫名其妙的报错。3.2 目录结构与初始化现在开始两条命令拿到一个可用的骨架# 用生成器自带的脚手架初始化到 blog 目录 npx generator-cli init blog cd blog初始化完成后先别急着改配置花三十秒把目录看一遍。典型的目录长这样blog/ ├── config.yml # 主配置文件站点标题、地址、主题、菜单 ├── content/ # 内容目录文章和页面都在这里 │ ├── posts/ # 文章 │ └── about.md # 独立页面 ├── themes/ # 主题目录 ├── static/ # 静态资源图片、favicon、附件 ├── package.json # 依赖与脚本定义 └── .gitignore # 忽略清单务必包含产物目录先把忽略清单处理干净这是我建议新手做的第一件事。确认.gitignore里包含产物目录、依赖目录、系统临时文件。省掉后面一次“提交历史被污染”的返工成本极低。3.3 配置文件逐项拆解配置文件是骨架里最容易出错的地方我把几个必须改的项拆开讲配置项填什么填错的后果站点基础地址最终访问用的完整地址含协议资源路径、站点地图、分享卡片全部错乱站点标题与副标题你的博客名和一句话介绍只影响展示随便改文章路径规则建议用“年/月/标题”或“分类/标题”上线后再改会导致旧链接全部失效主题先用自带的默认主题换主题会覆盖自定义模板别一开始就硬改时区与你写作习惯一致的偏移量文章排序错乱、发布时间显示不一致其中站点基础地址这一项最要命也最容易被忽略。它的作用是拼接所有绝对路径。如果你先填了本地地址http://localhost:4000就去构建那发布到线上之后所有图片和样式表都会去请求本机地址页面直接白给你看。我第一次犯这个错排查了半小时才想起来是这一行没改。所以正确的顺序是先在配置里把正式地址填对本地预览用命令行参数临时覆盖而不是把它改成localhost再改回来。3.4 写第一篇内容与本地预览新建一个 Markdown 文件放在文章目录下元信息照 2.1 的模板写正文随便写两百字然后启动本地预览npm run dev如果脚本名不一样去package.json的scripts里看一眼就知道不必照抄命令。启动后浏览器打开提示的地址你会看到一个能点、能翻页的站点。这一步能跑通说明内容层和生成层都没问题剩下的只是托管。这里补充一个实操心得本地预览的端口经常被占用如果启动报端口冲突不要慌生成器一般支持指定端口或者先把占用进程关掉。另外预览环境的地址和正式环境的地址不同所以涉及绝对路径的资源比如分享卡片图、站点地图在本地看起来可能是坏的这属于正常现象别在这里浪费时间。3.5 推送到远端与自动化流水线先在代码托管平台上建一个空仓库拿它的地址关联到本地然后推上去git init git add . git commit -m 初始化博客 git remote add origin 你的仓库地址 git branch -M main git push -u origin main接着配置流水线。不同平台的配置文件路径和字段名不一样但结构高度一致我用中文步骤名写一份结构示意你按所用平台的文档把字段名替换掉即可# 流水线配置示意字段名以所用平台文档为准 name: build-and-deploy 触发条件: 推送到 main 分支时执行 任务: - 步骤: 检出源码 - 步骤: 安装运行时版本必须与本地一致 - 步骤: 安装依赖用锁文件安装保证可复现 - 步骤: 执行构建命令 - 步骤: 将产物目录发布到静态分发服务几个关键点值得单独强调。安装依赖一定要用锁文件模式也就是npm ci这类强制按锁文件装的方式而不是随意的npm install前者能保证流水线装到的依赖版本和你本地一模一样后者在依赖有小版本更新时可能给你装出不同的东西造成“本地好好的、线上编译报错”。运行时版本要显式指定不要依赖环境中预装的版本。产物目录要单独指定成发布目标别让它把整个仓库都发上去——这会导致源码被公开下载虽然本来也是公开的但会多出几百个无意义的可访问路径。3.6 上线校验六项逐条过发布成功不等于能用我每次上线都会把这六项过一遍首页能打开样式正常没有大片白屏进一篇文章详情页确认图片能显示、代码块有高亮点一次翻页确认分页链接指向正确访问一个不存在的地址确认返回的是自定义的提示页而不是平台默认的广告页看源码确认页面里没有残留localhost之类的本地地址在手机上看一次确认布局在窄屏下没有横向滚动条。这六项里第 4 项最容易被忽略。默认情况下访问不存在的路径会落到平台自己的 404 页面那上面往往带着平台品牌信息观感很差。多数分发服务支持配置自定义提示页把产物目录里生成的页面路径填进去就行一行配置的事。4. 让它跑得快、跑得久优化与维护的关键细节能访问只是起点。真正决定这套东西好不好用的是三件事首屏速度、内容能不能被找到、以及三年后你还敢不敢动它。这一章全是我在实际运维中觉得最值钱的部分。4.1 图片是首屏速度最大的敌人静态站点本身没有什么服务端开销所以性能瓶颈几乎总是出现在图片上。给你算一笔账一张手机拍的原始照片宽度 4000 像素左右文件大小常在 3 到 4 MB。如果你的首页列表页每篇都放一张封面图一屏显示五篇那就是 15 MB 起步。按常见的移动网络条件估算光是把这些图下载完就要十几秒而访问者的耐心通常只有两三秒。处理方法很简单三步走# 思路示意尺寸压到目标宽度再转成现代格式 # 工具不限命令行或图形界面都行 压缩工具 --resize 1600x --quality 82 封面.jpg限制宽度正文配图宽度压到 1600 像素内足够封面图压到 1200 像素内头像和缩略图压到 400 像素内。多数场景下这个宽度在视网膜屏上依然清晰。换成现代格式同等观感下现代图片格式的体积通常只有传统格式的六成甚至更低一张 4 MB 的图压完常在 200 KB 上下。加上尺寸声明在模板里给图片标签写明宽高避免页面加载过程中布局反复跳动这个跳动会显著拉低体验评分。我自己的习惯是原始大图不进仓库只在仓库里放压缩后的版本原图另外存一份离线备份。这么做有两个好处仓库体积小、拉取快流水线构建也不会因为要处理大图而超时。压缩这一步完全在本地手动做不做成流水线的自动任务——自动压缩看着聪明实际上是构建时长和不可预测性的双重来源。4.2 站点结构与索引基础想让文章被搜到不需要多高深的手段把基础项做对就超过了大多数个人博客。四件事第一每篇文章的标题和摘要要写清楚。列表页和搜索结果里展示的就是这两个字段很多人偷懒让系统自动截取正文前几个字结果摘要是半句话点击率直接掉一半。第二生成站点地图并提交。绝大多数生成器都支持自动生成一份包含所有文章地址的索引文件你只需要在配置里确认开关打开把它放在站点根目录下再去搜索引擎的站长工具里提交一次。这件事做一次长期收益很大。第三保证链接结构稳定。为什么我在 3.3 里强调文章路径规则要提前定死因为一旦上线任何路径变动都会让已被收录的链接变成死链。如果确实要改务必做一次跳转映射把旧地址指向新地址别让积累起来的访问量白白流失。第四加上基础的分享卡片信息。在模板的头部区域补上标题、描述、封面图这几项元信息分享到社交平台时才会显示成一张卡片而不是一条干巴巴的链接。这是纯配置工作十几分钟能做完但观感提升明显。4.3 备份、迁移与内容资产归属这一节是我最想说的因为它不疼不痒但一旦出事就是大事。备份策略源码在远端仓库一份、本地一份这已经有两份了。但仓库本身是有可能被误操作甚至被删除的所以我会额外做一层保险——每周把仓库完整克隆到一个本地目录按日期命名存放。这件事用一个脚本加一个定时任务就能自动化写起来不超过二十行。别用“我以后会注意”来安慰自己我见过不止一个人因为一次误操作丢掉半年内容。迁移路径因为内容全是纯文本加标准 Markdown迁移成本极低。换生成器只需要处理模板和少量元信息字段差异换托管方改一下发布目标地址就行。真正需要注意的是链接结构迁移前导出一份现有全部地址的清单迁移后逐条比对把差异项补成跳转规则。这个动作花半小时能保住几年积累的收录。内容资产归属这一条容易被忽略——确认你用的主题和插件的许可条款允许你的使用方式尤其是商业性质的内容站。多数开源主题非常宽松但少数会要求保留署名删掉署名既不礼貌也可能违反条款。上线前花两分钟看一眼主题目录下的许可文件是个好习惯。5. 常见问题与排查实录那些文档里不会写的东西这一章全部来自实际踩过的坑。我按“现象 → 原因 → 处理”的方式整理你可以当速查表用。5.1 流水线显示成功但访问是 404这是最高频的问题。构建日志一片绿色网站打开却是什么都没有。原因基本逃不出三类现象最可能的原因处理方式首页 404其他路径也全 404发布目标目录配错了指向了一个空目录检查发布配置里的产物目录名和本地实际生成的目录名核对首页能开文章页全 404文章路径规则和产物实际结构不一致对比产物目录里的实际文件夹层级修正路径规则只有部分页面 404那些文件被忽略清单误伤了检查忽略规则确认没有把产物目录下的子目录排除掉排查这类问题有个非常有效的手段在流水线里加一步“列目录”把产物目录的结构打印到日志里。看一眼就知道文件到底生成在哪、叫什么名字比对着文档猜快十倍。5.2 页面能开但样式全丢或者图片全是裂的这个表现非常典型——页面是一片没有样式的纯文本。原因九成是路径问题。要么是站点基础地址填错了前面 3.3 讲过要么是部署到了子路径下而配置里没体现。判断方法很直接浏览器打开开发者工具看那些加载失败请求的完整地址。如果它指向localhost就是基础地址没改如果它少了一段前缀就是子路径配置缺失如果它多了一段重复的前缀那是地址末尾多写了斜杠。这三种情况我全遇到过对症下药一分钟能定位。5.3 流水线构建失败速查报错特征根因解决找不到命令运行时版本不匹配或依赖没装显式指定运行时版本用锁文件安装依赖依赖安装超时依赖源不稳定或依赖树过大换用镜像源配置精简不必要的依赖内存溢出被杀构建过程处理了大量图片或做了全量压缩把重活挪到本地产物提交进仓库某文件解析失败Markdown 元信息里含特殊字符未转义给元信息值加引号避免冒号和引号裸奔构建成功但发布失败发布凭据过期或权限不足重新授权检查目标服务的访问权限其中“元信息里含特殊字符”这条特别隐蔽。比如你的文章标题里有个冒号而你没加引号YAML 解析器就会认为这是键值对的分隔符直接报错。我现在的习惯是元信息里的所有值一律加双引号虽然啰嗦但从不出错。这个习惯帮我省掉了大量排查时间。5.4 几条踩过坑才懂的经验第一条别在主题目录里直接改模板。主题升级时会覆盖你的改动一夜回到解放前。正确做法是把主题当作依赖自定义的部分放在独立的覆盖目录或配置里。我吃过这个亏一次主题更新把首页改了三个小时的布局全冲掉了。第二条草稿机制要用起来。写到一半的文章把元信息里的草稿标记设成真构建时就会被跳过不会出现在列表和索引里。这比“先不发、写在本地备忘录”安全得多也不会出现“忘了改成发布状态”或者“不该发的时候发出去了”的尴尬。第三条提交信息写清楚。更新修改这种提交信息三个月后你自己都看不懂改了什么。我的格式是“类型: 具体内容”比如“文章: 新增静态博客搭建笔记”“修正: 修复归档页日期排序”。这样回头查历史时用关键字一搜就能定位到某次改动。第四条别追求一次配置完美。我见过太多人卡在主题美化、字体选择、动效调优上博客首页做得像产品官网文章列表里躺着两条内容。这套方案的全部价值在于让你尽快开始写剩下的都可以边写边改。先让它上线再让它变好看最后才考虑让它变聪明——这个顺序别颠倒。最后分享一个小习惯。我在仓库根目录放了一个清单文件每次想给站点加功能就先写进清单里标上“想要”和“需要”。一个月后回头看那些标“想要”的十有八九我自己都不想要了。这个做法帮我避免了很多无效折腾也让我把时间真正花在了写东西上——毕竟博客的核心从来不是那套技术栈而是里面有没有值得读的内容。
