一篇有用的技术笔记，应该留下哪五件事？

先保留问题的形状

笔记不必从宏大背景开始。重要的是当时想完成什么、在哪一步遇到障碍，以及成功后应该看到什么。把错误现象写具体，远比“折腾很久终于好了”有助于检索；不敏感的报错片段也比巨大截图容易阅读。

适用条件写在前面

设备、版本和网络条件，会决定同一步骤是否适用。公开笔记无需透露真实主机名和账户，但应说明关键前提，例如是否在同一局域网、是否有管理员权限、是否有可恢复副本。没有条件的步骤很容易被误用。

五个小标题就能成文

结构不必完全固定，可以用问题、条件、过程、验证、回退检查遗漏。过程只保留真正影响结果的步骤；试过但无效的方法简短记录，说明不能从它们推出什么结论。

资料整理与亲自验证分开

官方资料帮助读者判断结论来源，不意味着作者已长期实践。AI 辅助内容保留说明，未验证步骤明确标注。好的笔记不需要显得无所不知，清楚边界反而更可信。后续实测后，再补充真实结果和修订日期。

选一个问题完成一篇笔记

本篇任务是把一次技术问题整理成别人能够照着判断和操作的说明。材料可以是自己保存的报错、配置差异和验证记录，也可以只是官方文档；两种材料对应不同写法。没有亲自运行就写资料整理或待验证示例，不把推演写成“我最后解决了”。先选一个动作，例如“浏览器读取健康接口失败”，不要试图一篇解释整个前端工程。

在第一段写目标、实际症状和读者完成后应看到什么。目标是可检查的结果，症状是发生的现象，猜测则放到后面的待核实栏。比如页面空白是症状，代理没有匹配是尚需证据的原因。把三者分开后，文章就不会从标题开始误导读者。示例日志只保留错误类型和必要上下文，隐私内容使用 example.com、localhost 与占位符替代，模板里也不预填虚构日期和耗时。

# 问题单
任务：让页面读取只读健康接口
实际动作：<页面入口、按钮、请求路径>
实际症状：<错误类型，未运行则写构造案例>
预期：可读的健康JSON
环境：<工具版本、目录、系统、权限>
已有证据：
- 最终URL：<待填>
- HTTP状态/Content-Type：<待填>
- 首个错误：<待填>
猜测：<尚未证实的原因>
不包含：真实Cookie、令牌、个人数据
资料来源：<支持这条判断的官方页面>

把环境写成决定步骤的前提

环境栏不需要列电脑全部规格，只写影响操作的条件：工具主版本、项目入口、目标是否自己管理、命令在哪个目录运行、读者需要准备什么。涉及路径大小写时写文件系统差异，涉及命令选项时写工具版本，涉及 NAS 则说明是客户端查询还是 DSM 上执行。这样每一项环境信息都有作用，而不是为了显得专业堆一页型号。

引用官方文档后，区分文档保证的语义和自己建议的组织方法。例如 curl 可以输出阶段计时是工具能力，而“先记首个错误再改一项设置”是本文工作流程。读者复制步骤前应能判断哪些条件不满足，以及遇到不满足时在哪里停止。macOS/BSD 和 GNU/Linux 的命令不能仅因为名字相同就假定选项完全一致；若笔记只用 Markdown 模板，明确它与系统无关即可，不必硬加 shell。

把过程写成输入、操作和结果

每一步至少说明从什么材料开始、要做什么、为什么这一步能缩小问题范围，以及完成后观察哪里。单写“检查配置”过于抽象，可以改成“比较浏览器最终请求前缀与代理匹配键，若不一致就记录这处差异”。读者这样才能在自己的项目里找到对应位置。代码块旁边写运行前提和影响，文件写入是 write，网络查询也归 read，覆盖或中断则是 danger。

不要把整个排错历史按时间原样贴出。真正影响结论的实验保留完整，已排除的方向用一句证据说明；无效尝试若没有记录条件，就承认不能据此排除原因。成功输出只在实际观察后填，否则写预期。教程可提供完整示例配置与模板，但必须说明它是独立最小例还是现有配置的合并片段，避免读者直接覆盖项目全部设置。过程应让人完成一个任务，而不是收集一组看似相关命令。

# /api/health 为什么返回了页面
## 任务与前提
示意、未实机验证。已有受控Vite项目与只读后端 /health。
## 当前配置
浏览器请求 /api/health；代理只匹配 /backend。
## 判断
若响应为HTML且能被脚本读取，先核对代理匹配，不直接判断CORS。
## 操作
统一前端 /api 前缀；代理匹配 /api。
后端没有 /api 时才移除前缀，保留其他项目配置。
## 验收
- /api/health：预期JSON，实际待测
- 空正文成功响应：不强制JSON解析，实际待测
- 错误状态：显示错误，实际待测
- HTML正文：提示类型不符，实际待测
## 恢复
保留原代理片段；撤回本轮补丁，重启自己的开发服务，重测原请求。
## 边界
生产路由需要独立配置；没有生产实测结论。
## 来源
[Vite server.proxy](https://vite.dev/config/server-options#server-proxy)

完整案例：把模糊结论改成故障说明

原始便签假设写着“接口不通，改了代理好了”。整理时先追问材料是否足够：有没有最终 URL、响应状态、内容类型、代理匹配规则和修复差异。如果缺少真实日志，就将其改为构造案例：请求 /api/health，却只有 /backend 代理，预期会落到页面路由。正文明确这是假设复现，不给不存在的运行结果补日期。

完整笔记应先给出两个前缀及后端真实路由，再描述修正匹配与按需重写的理由，最后列正常 JSON、无正文响应、错误状态和非 JSON 四种验收。这样“改了代理”变成了可验证的原因链。若正式环境并没有开发代理，文章还要指出生产路由另行验收。案例的价值来自范围清楚和可检查，而不是渲染折腾多晚或最终多么顺利。下方成稿模板可以直接复制填写，空项会提醒作者还缺证据。

复读时检验读者是否需要猜

把自己当作隔了一段时间才回来看的人，检查每一个“这里”“那个地址”“按之前配置”是否有明确指代。读者不知道之前配置是什么，就应给最小必要内容或指向稳定来源。命令出现目录、文件和版本时，核对正文是否先介绍；示例值出现后，说明哪些可以照用、哪些必须替换。对多个互斥操作，明确二选一，不把继续与放弃流程写成可连续执行的一串命令。

验收部分要覆盖成功和至少一个失败分支。错误是否仍能被解释、旧数据是否残留、配置是否只影响预期范围，比一句“页面正常”更有用。若作者没有执行失败样本，就标为未验证，而不是删掉它使文章看起来完整。读者反馈也先保存可复现条件再改文稿，避免只因有人说不行就添加没有依据的新命令。修改文章应更新真实修订说明，保留原发布日期。

# 文稿复核
原发布日期：<保留>
本次修订日期：<真实日期>
本次改动：<具体结论或步骤>
理由与证据：<待填>
已实测：<没有则写无>
仅官方文档核对：<列结论及URL>
未验证：<系统/版本/接口/恢复>
读者是否还需猜目录、文件或输入：<逐项补全>
回退版本：<原稿位置或提交>
公开前检查：正文、附件、来源、占位值、风险标记

将回退和来源变成维护入口

回退不是每篇都写“备份一下”就结束。具体到本例，应记录改动前的代理规则、哪些文件被修改、重启哪一个自己启动的服务，以及恢复后要重测哪条请求。如果只是填写笔记模板，恢复边界就是保留原稿版本并审查差异；没有必要给写作任务塞进系统清理命令。对无法恢复的部分如已公开数据，明确撤稿不能保证外部副本消失。

来源表按结论逐项关联官方页面，检查链接能打开并支持对应语句。版本敏感的参数记录核对日期，叙述和来源不一致时优先收窄结论。收尾保留一份待验证清单：缺少的平台、未运行的命令、未核对的真实接口。文章可以在这些边界清楚的情况下有用，不必伪装成覆盖全部环境。正文、模板和后续真实记录一起保存，未来更新时才能辨认哪些是原始事实、哪些是教学设计。

填写工作表，把示例变成自己的记录

使用三个模板时，先填问题单，再写成稿骨架，最后完成修订记录。不要反向从一个漂亮标题猜测当时的证据。问题单中证据不足的字段保留待补，成稿里对应结论就用条件句；证据足够时才写确定的原因。完整案例模板给出了从症状到验收的连接，读者可以替换成自己的路由和项目条件，但示意判断不能原封不动变成亲历记录。

复核时尝试只读模板完成操作：如果需要回忆某个被省略的端口、配置文件位置或上一步输出，就说明正文还缺前提。可复制不意味着一键执行，而是材料足够让人做出有根据的选择。技术写作中的 Markdown 模板写入磁盘属于 write；其中记录的查询命令与危险操作应另按实际影响标注。最后把来源链接填到支持它的结论旁边，至少检查一个读者可能误解的边界，让笔记不仅保存结论，也保存结论不适用的条件。