技术文章发布前，按这个清单检查代码块、版本和复现步骤

技术社区里的文章不需要写成广告稿。读者要找的是环境、现象、尝试过的做法和验证结果。这份清单适合发 Node、C++、数据库、部署排障这类工程笔记。

1. 标题直接写问题和对象

不推荐：

一次踩坑记录

推荐：

Express Session 本地登录成功后又跳回 /login 的排查
SQLite 开 WAL 后备份不能只复制 db 文件
Windows 用 VS Code 配 MSYS2 C++ 调试环境

标题里至少带一个技术对象和一个动作。读者搜索时才知道是不是同一个问题。

2. 开头先给现场，不要铺垫

可以这样写：

环境是 Windows 11、VS Code、MSYS2 UCRT64 GCC。现象是 Ctrl+Shift+B 能编译，但 F5 调试时报 gdb not found。

不要写：

开发环境很重要，本文介绍一下我的经验。

这类句子没有排障价值，删掉文章更清楚。

3. 版本信息单独列出来

示例：

环境：
- Windows 11 23H2
- VS Code 1.x
- MSYS2 UCRT64
- g++ 15.x

如果你不确定具体版本，就写验证命令，让读者自己查：

code --version
g++ --version
node -v
npm -v
sqlite3 --version

不要编一个看起来很新的版本号。版本不确定就明确说“不确定”。

4. 每个关键步骤都配验证命令

安装类文章不要只写“安装完成即可”。要写怎么确认完成。

C++ 编译器：

where.exe g++
g++ --version

Node 服务：

node --check server.js
curl -fsS http://127.0.0.1:3000/health

SQLite 备份：

sqlite3 data/blog.db 'pragma integrity_check;'

Nginx：

sudo nginx -t
curl -I https://example.com/health

验证命令比“应该没问题”可靠得多。

5. 代码块要能复制运行

差的写法：

app.listen(port)

读者不知道 app、port 从哪来。

更好的写法：

const express = require('express');

const app = express();
const port = Number(process.env.PORT || 3000);

app.get('/health', (req, res) => {
  res.json({ ok: true });
});

app.listen(port, () => {
  console.log(`listening on http://127.0.0.1:${port}`);
});

短代码块可以省略细节，但必须说明省略了什么。别让读者猜。

6. 把坑写在步骤旁边

读者最需要的不是成功路径，而是哪里容易错。

示例：

把 C:\msys64\ucrt64\bin 加进 PATH 后，要完全重启 VS Code。只重开终端有时不够，因为 VS Code 主进程仍然拿着旧环境变量。

这比单独写一段“常见问题”更有用，因为读者刚做完这一步，马上就能检查。

7. 错误信息尽量原样保留

不要只写“报错了”。至少保留第一行和关键行：

Error: Cannot find module 'better-sqlite3'
Require stack:
- /app/src/db.js
- /app/src/server.js

然后写判断：

这不是 SQLite 文件损坏，是 Node 依赖没装或部署目录不对。运行 `npm ci`，确认启动目录。

错误信息能被搜索，也能让读者判断是不是同类问题。

8. 涉及密钥时写检查方法，不贴真实值

不要在文章里贴：

GITHUB_CLIENT_SECRET=真实密钥
SESSION_SECRET=真实密钥

可以写：

node -e "require('dotenv').config(); console.log(Boolean(process.env.GITHUB_CLIENT_SECRET))"

输出 true 只能说明变量存在，不泄露内容。

如果必须写 .env，用示例值：

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

9. 最后给一个验收清单

文章结尾不要写空泛感想，给读者一个能照着跑的清单。

示例：

node --check server.js
npm start
curl -fsS http://127.0.0.1:3000/health
tail -n 50 data/logs/error.log

然后写清楚通过标准：

通过标准：语法检查无输出，健康检查返回 200，错误日志没有新增异常。

10. 发布前自查

发出去之前问自己这几件事：

  • 有没有写清楚操作系统、工具链和关键版本。
  • 每个安装或修改步骤有没有验证命令。
  • 错误分支有没有说明怎么判断。
  • 代码块能不能复制运行。
  • 有没有泄露密钥、cookie、token、真实用户数据。
  • 有没有删掉泛泛开头和口号式结尾。

如果这几个问题都能回答，就可以发布。