为什么技术笔记要强调可复现
很多技术笔记的问题不是写得短，而是缺少上下文。比如只写“修改 Nginx 配置后重启即可”，几个月后回看时，很可能忘了系统版本、配置文件路径、服务启动方式、报错原文和验证命令。可复现的笔记要解决三个问题：当时发生了什么、具体做了什么、怎样证明已经解决。
一篇技术笔记的推荐结构
1. 环境信息
环境信息不需要写成流水账，但关键版本必须保留。最低限度应包括操作系统、运行时版本、数据库版本、框架版本、部署方式和相关插件。不要只写“Linux 服务器”，建议写成下面这种格式：
系统：Debian 12
运行时：Node.js 20.x
数据库：PostgreSQL 16
部署：Docker Compose + Nginx 反向代理
问题范围：仅发生在生产环境，开发环境未复现2. 问题现象
现象要写用户能看到的结果，也要写系统侧的信号。用户侧可能是页面 502、接口超时、登录失败；系统侧可能是日志报错、CPU 升高、数据库连接耗尽。写现象时尽量保留原始错误，不要只写“报错了”。
用户现象：访问 /api/login 返回 502
Nginx 日志：upstream timed out while reading response header
应用日志：database connection timeout
触发条件：并发登录请求增加后出现3. 最小复现步骤
复现步骤要删掉无关动作，只保留能稳定触发问题的最短路径。如果问题不能稳定复现，也要写清概率和条件。例如“连续执行 10 次大约出现 3 次超时”，比“偶尔超时”更有价值。
- 准备一个测试账号。
- 清空浏览器缓存或使用无痕窗口。
- 连续请求登录接口 20 次。
- 观察第 10 次之后是否出现响应时间超过 5 秒。
4. 排查过程
排查过程建议按证据顺序记录，不要只写最终答案。比较好的写法是“假设 - 检查 - 结论”。这样以后遇到类似问题，可以复用思路。
- 假设一：Nginx 配置导致超时。检查 access.log 和 error.log，发现超时发生在 upstream 读取阶段。
- 假设二：应用线程阻塞。检查应用日志，未发现长时间同步任务。
- 假设三：数据库连接池耗尽。检查连接数和慢查询，发现登录查询缺少索引。
5. 解决方案和验证
解决方案必须配套验证方法。修改配置、加索引、升级版本之后，都要说明如何确认问题已经消失。
验证命令：连续压测登录接口 3 分钟
通过标准：P95 响应时间低于 300ms，错误率为 0
回滚方式：删除新增索引或恢复上一份配置文件建议长期使用的笔记模板
# 标题：一句话说明问题或主题
## 环境
## 背景
## 现象
## 复现步骤
## 排查过程
## 解决方案
## 验证结果
## 风险和回滚
## 后续优化最后检查清单
- 是否写清了系统、软件和框架版本。
- 是否保留了关键报错原文。
- 是否能按步骤复现或验证。
- 是否说明了风险、回滚方式和适用边界。
技术笔记不是为了显得完整，而是为了降低下一次排查的成本。只要能让未来的自己少走一次弯路，这篇笔记就是有效的。
评论