做一个"能养"的内容站：长期维护结构

本篇是《手写一个内容型技术博客站》系列的收官篇。

前面九篇讲的是"把站建起来、跑起来"。最后一篇讲更难的事：让这个站三年后还能改。技术站最怕的不是建不起来，而是建成一座"谁都不敢碰的积木塔"。

一、版本号三处同步

内容站的版本管理有个特殊问题：版本号散落在三个地方，改一处漏两处特别常见。

# 1. package.json
"version": "3.31.0"

# 2. README.md 版本历史
### v3.31.0
- ...

# 3. git commit message
chore: v3.31.0

铁律：改了功能，三处一起动。 曾经发生过：代码已经 commit（v3.23.0），但 package.json 还是 3.22.0、README 版本历史缺条目——版本号就乱了。

收尾核对：git log --oneline 看最近 commit 版本号 vs README/package.json，补记缺失条目再升新版本。

语义化版本：feature 变更升 minor（1.8.0→1.9.0），纯 bug/样式微调升 patch。这样回看 git log 就能判断"这次改动大不大"。

二、内容与代码分离后的维护边界

本系列第 2 篇讲了配置与内容分离。长期维护的收益在运营阶段才真正体现：

src/config/*.yaml          ← 元数据（排序/SEO/别名）—— 偶尔改，改动即全局
src/content/**/*.md        ← 正文 —— 经常改，只影响单篇
src/lib/ + src/components/ ← 代码 —— 架构变更才动

维护者心智负担大幅降低：

• 写文章：丢一个 md 到分类目录，跑 preflight 校验通过即可，不碰任何配置
• 调站点（改名/排序/SEO）：改对应 yaml，auto_rebuild 自动触发重建
• 改功能：代码层，配合三线验证 + 回归

边界清晰 = 每个人（包括三个月后的自己）都知道该碰哪里、不该碰哪里。

三、写作与发布工作流

本地写作流

1. 在 src/content/categories/<分类>/<子分类>/ 下写 .md
2. 本地 npm run build 通过（或跑 preflight 校验）
3. git commit（含版本号，若涉及功能）
4. 同步到生产（scp/rsync code，npm ci）
5. 生产跑 deploy.sh（预检→构建→重启→冒烟）

内容与代码的发布节奏不同

• 内容：改 md，auto_rebuild 自动构建，快（尤其教程类动态页，刷新即见）
• 代码：改源码，手动走完整 deploy 流程

注意区分：新增文章（SSG 详情页）需要完整 rebuild；教程章节（动态页）丢文件刷新即可。搞混了就会出现"列表能点进去、详情 404"。

每轮交付附"修改文件清单"

这是非常值得养成的习惯：每次改动结束，列清楚——

为什么必要：代码是你手动同步生产的（rsync/scp），没有清单就不知道"哪些文件该传"。新增文件尤其容易漏（修改过的文件 scp 时天然会覆盖，新增的容易漏传）。

四、防"积木塔"的工程习惯

1. 没收尾四连不改版

每次优化后固定做四件事再升版本：

1. 全项目代码 review（tsc/eslint/build + 回归 + 无死代码/未用 import）
2. 排查硬编码（站名/URL 是否散落各处 → 应统一走 config 单源）
3. 分析重复开发（相似组件抽共享、跨页逻辑抽 lib/）
4. 字体/颜色/大小是否收敛（合理的不动，不强行统一）

2. 配置单源，兜底不飘

src/config/*.yaml 是配置真源，代码里的 DEFAULT_XXX 只是兜底。改站点名必须三类源同步（config + DEFAULT + 内容中的站名），漏一个就 title/OG/footer 混用新旧名。

3. preflight 是守门员

本系列第 7 篇的 preflight-check.mjs，是"编辑自由"和"数据正确"之间的平衡杆。它允许编辑随便改内容，但在 build 前把所有"静默错误"拦下来。越自由的编辑系统，越需要强校验兜底。

4. 能自动化绝不手动

• 内容变更 → auto_rebuild 自动构建
• 发布 → deploy.sh 一键
• 配置校验 → preflight
• 日志 → logrotate 自动轮转

手动的每个环节，都是将来出错的概率源。

五、这份"能养"的代价与回报

代价：前期多写了一些"基础设施"（preflight、auto_rebuild、deploy.sh、三线验证约定），每篇改动都要守纪律。

回报：

• 三个月后还能安全地加新功能
• 内容编辑不依赖开发能力
• 站点本身成为可展示的"作品"而非"历史遗留物"

技术博客站最矛盾的地方在于：它既是产品，也是开发过程本身的作品。维护好它，等于同时给你"内容"和"工程实践"两个资产。

六、系列回顾

这个系列从选型讲到长期维护：

1. 技术选型与实践
2. 内容与配置分离（v3.25.0 重构）
3. 构建缓存的幽灵错误
4. 自研 Markdown 渲染器
5. 文件级评论系统
6. Tailwind v4 语义色系统
7. 内容发布与 preflight 校验
8. 阿里云 ECS 部署
9. 中文技术站 SEO
10. 长期维护结构（本篇）

每一篇背后都是真实项目里踩过的坑和做出的决定。希望这套"从零到一个能养三年的技术站"的路径，能给你自己的站一些参考。

给普通人的一句话：好东西不是"建"出来的，是"养"出来的——代码如此，内容站如此，很多事都是如此。

参考

• 语义化版本规范：https://semver.org