如何把编程问题沉淀成可复现的 Hexo 技术文章

**解决一个编程问题之后，最容易被忽略的工作，是把“我当时怎么试出来的”整理成下一次可以复用的知识。**如果文章只有最终代码，读者看不到排查路径；如果文章只有流水账，又很难快速定位根因。

本文以一个 Hexo 博客的实际维护场景为例，整理一套从问题记录到 Git 发布的工作流：先保留事实，再抽取根因，最后用构建和版本控制保证文章真的能发布。

一、先定义“值得写”的问题

并不是每条报错都需要写成文章。适合沉淀的工程问题通常满足至少一个条件：

• 解决过程包含容易重复踩到的误区；
• 根因和表面现象之间有距离，值得解释；
• 解决方案可以迁移到其他项目或版本；
• 后续维护者需要知道验证方式和边界。

这次整理的是博客内容发布流程本身：如何把一次编程问题转化为 Markdown 文章，如何遵循现有 Hexo 文章约定，以及如何在不混入其他改动的前提下推送 Git。它不是某个特定框架的报错，而是一个会反复出现的工程协作问题。

二、问题现象：文章能写出来，却不一定能发布

在一个已有内容的博客项目里，文章发布至少涉及四类约束：

1. 文件约定：文章目录、文件名、front matter 字段和永久链接必须符合仓库习惯；
2. 内容质量：标题、摘要、代码和结论需要能够被陌生读者复现；
3. 构建完整性：Markdown 和 YAML 有语法错误时，文章可能无法生成；
4. 版本控制：不能把缓存、生成目录或其他人的未完成改动一起提交。

只完成“写 Markdown”这一步，无法证明页面能被 Hexo 正确生成，更无法证明远端已经收到这次变更。

三、排查与设计：先读仓库，再决定写法

1. 从配置确认博客规则

Hexo 项目的 _config.yml 是最可靠的入口。需要重点确认：

1
2
3
4

source_dir: source
new_post_name: :title.md
theme: kratos-rebirth
timezone: "Asia/Shanghai"

这些配置告诉我们文章在 source/_posts 下，日期应按上海时区处理，主题和渲染器也可能影响 Markdown 的可用语法。

2. 从现有文章确认实际约定

配置文件只说明默认行为，现有文章才能说明项目真正采用的写法。当前仓库的文章同时存在标题文件名和数字文件名，因此新增文章应先读取目录并选择未占用的编号，而不是凭感觉覆盖一个文件。

Front matter 也应以邻近文章为准。例如技术文章通常使用：

1
2
3
4
5
6
7

categories:
  - Programming
tags:
  - Hexo
  - Git
comments: true
toc: true

分类和标签不是装饰，它们决定文章能否被归档页和标签页找到。

3. 把排查过程分成“事实”和“解释”

建议在写作前先做两栏记录：

这样做能避免把“我认为应该如此”误写成“项目就是如此”。技术文章最重要的可信度，来自这种区分。

四、文章结构：让读者能从现象走到结论

一篇可复现的排障文章，可以按下面顺序组织：

问题现象

写清楚环境、触发方式和可见结果。错误信息要保留关键上下文，同时删除 Token、私有地址和个人信息。

排查过程

不要只列出成功命令。说明每一步是为了验证什么假设，以及为什么排除某个方向。例如先看配置，再看现有文章，最后检查 Git 状态，能够让读者理解决策顺序。

根因

用一句话先给结论，再展开数据流或代码路径。直接原因、诱因和长期风险应分开写，避免把“修好了”误认为“理解了”。

解决方案

给出最小修改和完整执行顺序。命令前写明所在目录，代码片段标注语言或文件类型；如果存在替代方案，解释取舍，而不是罗列所有可能做法。

验证与回归

至少记录构建、测试或页面检查中的一种实际结果。没有运行过的检查要明确写成“待验证”，不能用肯定语气代替结果。

五、发布前的最小安全流程

文章写完后，可以用下面的顺序降低发布风险：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 1. 在博客项目根目录
npm run build

# 2. 检查 Markdown 空白和冲突标记
git diff --check

# 3. 只查看本次相关文件
git status --short
git diff -- source/_posts/868.md

# 4. 精确暂存并复核 staged diff
git add source/_posts/868.md
git diff --cached --check
git diff --cached --stat

# 5. 提交并推送当前分支
git commit -m "docs: publish programming problem workflow"
git push

这里有两个容易被忽略的细节：第一，npm run build 只证明当前源码可以生成，不等于线上部署已经完成；第二，git push 成功后才可以说变更已送达远端。若认证、网络或分支保护导致推送失败，应保留本地提交并如实报告。

六、常见误区

误区 1：直接复制错误信息，不写环境

同一条错误在不同 Node、Hexo 或主题版本中可能原因不同。至少补充运行时版本、项目脚本和触发命令。

误区 2：只写最终修复，不写失败尝试

失败尝试能够帮助读者缩小排查范围，但要说明它为什么无效，避免变成没有结论的命令清单。

误区 3：用 git add . 快速发布

博客仓库常常同时存在草稿、生成目录和个人配置。精确暂存能把文章发布和其他工作隔离开。

误区 4：构建通过就宣称“已上线”

构建、提交、推送和部署是四个不同状态。文章中应分别记录，读者也能据此判断问题发生在哪一层。

七、可复用检查清单

• 已确认问题的环境、触发步骤和真实现象；
• 已区分事实、推测和待验证项；
• 已解释根因，而不是只给补丁；
• 文章 front matter 与现有 Hexo 文章一致；
• 新文件名、永久链接和分类没有冲突；
• 已脱敏敏感信息；
• npm run build 或项目等价构建命令通过；
• git diff --check 通过；
• 只暂存本次文章相关文件；
• 已分别确认 commit 和 push 的结果。

结语

技术写作不是把聊天记录变长，而是把一次排查压缩成可验证的路径。保留证据、解释根因、记录边界，再用构建和 Git 检查结果兜底，文章才会从“这次解决了”变成“下次可以照着做”。