个人项目的长期主义：用检查、构建和部署守住可复现

个人项目刚开始时，最重要的是“先跑起来”。过一段时间以后，真正让人头疼的却变成了另一组问题：当初为什么这样配置？哪条命令才是标准入口？改完以后怎么确认没有影响线上？如果电脑换了、依赖升级了，能不能在半小时内重新得到同样的结果？

我理解的长期主义，不是把项目做得很重，而是把下一次维护的成本降下来。对一个静态博客来说，几条固定命令、几份清楚的文档和一套不容易误触的边界，已经能解决大部分焦虑。

把“能运行”变成固定入口

个人项目最怕依赖记忆。今天在终端里敲了一串临时命令，过几周再回来，往往只记得“应该差不多是这样”。所以我会把常用操作收进仓库脚本，让入口拥有明确的名字：

pwsh ./ops/check.ps1
pwsh ./ops/build.ps1
pwsh ./ops/deploy.ps1 -DryRun
pwsh ./ops/deploy.ps1

这些命令不一定适合所有项目，但它们表达了一个顺序：先确认结构和内容，再生成静态文件，先演练同步范围，最后才接触线上环境。入口固定下来，维护者就不必从目录里猜“哪一个脚本才是真的”。

检查脚本不需要很聪明，能抓住高频错误就足够了。这个博客的检查会确认关键目录和配置文件存在，也会逐篇检查文章是否包含标题、日期、标签、分类和描述。

它不评价文章观点，也不能替代人工审稿，但它能把“忘记写 description”这类错误挡在构建之前。检查越早，修复越便宜；把它放进发布流程，比靠个人习惯更稳定。

我还会把检查命令放进交接文档，让接手的人知道第一步应该运行什么。好的文档不是把所有细节写满，而是让下一步行动没有歧义。

Node、主题和渲染器都有版本关系。直接依赖某台电脑已经安装好的环境，短期看很快，长期却容易出现“我的机器能生成，你的机器报错”。因此仓库优先使用 Docker 构建，把 Node 版本和依赖安装收进可重复的脚本。

如果 Docker 暂时不可用，也可以使用 npm 兜底，但要记录运行环境和结果。兜底不是放弃可复现，而是在现实约束下保留一条明确的备用路径。

构建完成后，我不会只看命令的最后一行。我会确认 public/ 存在，也会检查新文章对应的日期和 slug 页面是否真的生成。生成物是静态站点的中间证据，值得被认真查看。

部署通常意味着远端文件会被同步，甚至会删除本地已经不存在的旧文件。因此 dry-run 不是可有可无的“试试看”，而是一张发布清单：目标主机、目标目录和待同步文件都要在它里面被看见。

正式发布之后，至少留下三类记录：使用的提交哈希、构建方式和命令结果。遇到问题时，这些记录能回答“这次发布到底包含什么”，也能帮助下一次回到上一份已验证的状态。

我不追求每次都写长篇发布报告，但会让记录足以支撑复盘。几行清楚的文字，通常比一段没有上下文的终端截图更有用。

出错时最危险的动作，是为了清理现场而直接覆盖工作树。先保留错误输出，确认是内容问题、依赖问题、网络问题还是远端权限问题，再决定修复方式。能只改一行就不要重写整个配置，能先本地构建就不要反复触碰线上。

如果需要回滚，使用上一份已验证提交重新构建，并重复 dry-run。回滚的目标是恢复一个已知状态，不是把所有最近的工作一并抹掉。只要每次发布都有清晰的提交边界，回滚就不会变成一次猜谜。

长期维护不只是写给自己看的笔记。仓库中的 docs/15-博客内容发布交接文档.md 会记录目录职责、文章规范、环境变量含义、发布命令和故障处理方式。它不保存私钥内容，也不假设接手者知道我的习惯。

我希望下一位维护者只看仓库就能回答四个问题：文章放在哪里，怎样检查，怎样构建，怎样安全地发布。能回答这四个问题，项目就已经拥有了一条比“问原作者”更可靠的生命线。

个人项目的长期主义，最终不是增加更多工具，而是减少不必要的猜测。固定入口让动作可重复，检查脚本让错误提前暴露，容器让构建环境更稳定，dry-run 和提交记录让发布可解释，交接文档让知识不只停留在某个人的记忆里。

如果你想从文章生产这一侧开始，可以先读把 AI 工具变成稳定工作流；如果你正在搭建 Hexo 站点，低风险发布流程会提供更具体的命令顺序。