TW●汤伟的数字生活NOTES ON A DIGITAL LIFE
个人数字生活文库始于 2026 · 持续修订总目录 ↗
全部文章

写作与知识管理 / 专题指南

引用一篇教程之前,先检查它在回答什么。

官方资料、社区经验与个人验证应该各归其位。

阅读设置字号仅保存在当前浏览器

让引用紧跟结论

末尾放一长串链接,不代表每个结论都有依据。引用前先问:资料是否支持正在写的那一句?介绍功能的页面,不一定证明所有机型和版本都可用;一次社区成功经验,也不保证你的网络条件相同。

操作事实优先查一手资料

功能限制、参数含义和升级要求,优先核对官方文档或维护者说明。社区讨论提供排查方向,但仍需验证。对变化快的内容记录日期与版本,不把多年以前的截图当作当前菜单的可靠说明。

写出理解,而不是堆砌摘录

用自己的问题和结构解释,比大段复制更有帮助。必要引用保持简短并给来源,不能确认的部分写成待验证。AI 能帮助组织内容,不能制造不存在的测试结果、链接或亲身经历。

让文章能够承认变化

修改过时内容时,保留有用的变更说明,告诉读者结论如何调整。没有必要伪造更新频率或长期历史;刚建立但边界清楚、持续修订的指南同样实用。文库厚度来自可靠积累,不来自回填日期。

先把要引用的结论拆小

本篇任务是为一篇技术说明核对来源,让读者能判断参数含义、适用条件和未验证边界。准备待发布正文、每个关键结论和候选官方文档。不要先收集一长串链接再回填文章,先选一句可核对的陈述,例如“某配置只作用于开发服务”。一句同时谈版本、性能与安全时,拆成分别需要证据的几句,防止一个来源被迫承担它没有证明的内容。

为每句记录证据类型:规范定义、产品支持说明、命令手册,或作者自己的实验。本文只依据浏览核对的官方资料,不把社区经验当成产品承诺。个人实验也只能支持实际测过的条件,不能外推到全部系统。模板中的“已核对”只有打开对应页面并确认相关段落后才能填写;日期记录真实核对日,未进行实验就保留未实机验证,不能用文档存在代替实验完成。

逐结论引用矩阵markdown · 普通 Markdown 编辑器;macOS / GNU/Linux / DSM 浏览器客户端
会修改状态
| 结论 | 官方页面 | 支持范围 | 已打开 | 支持原句 |
| --- | --- | --- | --- | --- |
| server.proxy用于开发服务代理 | https://vite.dev/config/server-options#server-proxy | 开发配置 | 待核对 | 待核对 |
| 生产路由已可用 | <实际部署依据> | 自己的环境 | 未核对 | 未实测 |
| 字符串false须显式解释 | https://vite.dev/guide/env-and-mode.html | Vite自定义客户端变量 | 待核对 | 待核对 |
核对日期:<真实日期>
项目版本:<待填>
未实机验证的命令:<列出>

完整可填模板,示意且未实机验证;保存会写文件。请用自己的观察替换待填项,不把示意结果当实测。

打开具体页面确认它在回答同一个问题

先核对页面属于哪个产品、版本和功能,再找与原句直接相关的段落。教程讲如何启动开发服务,未必说明生产托管行为;平台介绍支持身份保护,也未必保证你现有路径规则覆盖所有入口。把引用指向具体说明页或章节比指向产品首页更容易复查。链接能打开只是第一关,内容支持原句才是通过。

注意文档中的条件词与范围限定。默认、通常、特定模式和某版本起都不应在转述时消失。若资料只说“可以”,不要写成“自动”;只说“支持”,不要写成“始终可用”。参数名称可以准确保留,但说明尽量用自己的语言和任务结构表达,避免大段搬运。截图只能补充界面位置,不能替代可查的文本来源,尤其版本快速变化时更需要保留页面和核对日期。

完整案例:纠正一个过宽的工具结论

假设草稿写“开发时配好了代理,发布之后接口也会正常”。核对 Vite server.proxy 文档后,应把结论收窄为开发服务上的代理配置;生产是否存在对应路由,要由部署平台或后端配置另行证明。引用表分别列开发行为和生产待核实项,而不是给原句挂一个 Vite 链接就通过。此处是文稿核对示例,没有真实网站运行结果。

修改后的文章可以写:浏览器开发请求先到 Vite,再由配置转发;构建产物部署之后,需独立提供生产路由并检查。接着给读者一个同源健康请求验收表,要求在正式入口检查最终 URL、状态和内容类型。这样来源负责说明工具边界,模板负责引导环境验证,两者关系清楚。若不能访问生产环境,就在文章保留未验证声明,不编造部署成功的截图或耗时。

一条过宽结论的修订单markdown · 普通 Markdown 编辑器;macOS / GNU/Linux / DSM 浏览器客户端
会修改状态
# 结论修订
原句:开发配置了代理,发布之后接口也会正常。
问题:把开发配置作用范围外推到了生产。
改后:开发代理只处理开发服务的对应请求;生产入口需另验收真实路由。
依据:[Vite server.proxy](https://vite.dev/config/server-options#server-proxy)
本次核对日期:<真实日期>
保留原发布日期:<原值>
实机情况:未验证
新增验收:正式入口的最终URL、HTTP状态、Content-Type与可读正文。
待补证据:生产路由实际配置及测试结果。

完整可填模板,示意且未实机验证;保存会写文件。请用自己的观察替换待填项,不把示意结果当实测。

版本冲突和平台差异要显式处理

当官方当前文档与旧项目行为不同,先确认项目的实际版本,再找对应版本说明。不能仅因最新文档有参数,就指导旧环境直接使用;也不能用旧截图断言当前界面不存在某功能。若对应版本资料无法找到,写明尚未确认并删去可误执行的确定性步骤,保留读者需要核对的项。更新文章时只改受影响结论,不无依据扩大成全篇升级建议。

平台差异同样要求证据。macOS/BSD 与 GNU/Linux 某些同名工具选项不同,DSM 又可能使用精简实现或套件包装。若说明只验证了客户端 curl,不应宣称已验证 NAS 上相同命令。可以把平台列成三栏,分别填写文档依据与实测状态;没有证据的栏标未核对。这比模糊写“适用于所有平台”更有用,也帮助读者决定是否需要在受控副本先试。

把不确定性改成下一步验证

“可能有问题”太宽泛,可以改成具体待核实项:当前版本是否支持选项、错误响应是否也带相应头、备用域名是否受保护。每项配一个最小观察方法与通过条件,让后续作者知道怎样把它从待验证移到已验证。观察请求属于 read,编辑配置或记录属于 write,中断与覆盖属于 danger;引用核对本身不需要运行来源中的所有命令。

当两份官方资料看似冲突时,先比较对象与时间:是否一个说开发、一个说生产,是否一个是旧版本,是否一个只适用于某种部署模式。无法消解时在正文保留范围说明,不选择更符合预期的那一句装作没有冲突。来源列表应去重,但不同结论仍可引用同一来源;去重减少噪声,不等于把结论与来源的对应关系删掉。读者应该能从一个结论回到支持它的那段资料。

版本与平台待验证表markdown · 普通 Markdown 编辑器;macOS / GNU/Linux / DSM 浏览器客户端
会修改状态
| 项目 | 文档依据 | 真实版本 | 实测状态 | 下一步 |
| --- | --- | --- | --- | --- |
| macOS/BSD命令选项 | <对应手册> | 待填 | 未测 | 查看帮助并受控验证 |
| GNU/Linux命令选项 | <对应手册> | 待填 | 未测 | 核对实现与选项 |
| DSM套件限制 | <对应官方页> | 待填 | 未测 | 不照搬桌面步骤 |
| 错误响应行为 | <产品说明> | 待填 | 未测 | 用无业务影响样本验证 |
完成判据:每项结论有来源范围;未验证项没有被写成成功。
失效链接处理:寻找同一官方内容的新位置,再重新核对原句。

完整可填模板,示意且未实机验证;保存会写文件。请用自己的观察替换待填项,不把示意结果当实测。

修订时留下可以解释的变化

修订记录写具体变化及原因,例如“收窄开发代理作用范围,新增生产路由验收”,不要只写“更新优化”。原发布日期保留,更新日期使用实际编辑日;资料核对与实机验证是两件事,分别注明。若某结论撤回,说明读者应停止沿用哪一步以及现在采用什么判断,不需要伪造一段长期实践历史来增加可信度。

发布前逐项核对来源链接、对应结论、版本条件和模板占位。使用自己的语言组织全文,必要短引文保持短且可追溯,不以大量引用替代解释。归档时保存引用索引和未验证清单,后续发现失效链接可先找同一官方内容的新位置,再重新确认结论,而不是机械换成首页。完成标准是一篇可复查、可修订的说明,来源没有支持的地方能被清楚看见,读者不用猜作者究竟亲自做过什么。

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

文中引用矩阵中的结论写成单一可判真假的句子,来源填写具体官方页面,支持范围用自己的话概括。若一页只支持某个版本,把版本条件放在同一行;“已打开”与“支持原句”各留一栏,避免链接健康检查被误当成事实核对。样例中的 Vite 结论仅说明开发代理边界,生产路由一行明确需要独立配置与验收证据。

修订单保存原表述、改后表述、原因和核对日期,适合审阅者比较,而不是用一条“已优化”覆盖所有变化。未验证清单可以交给后续真正有环境权限的人完成,但不能在文稿里预填成功。阅读官方页面属于 read;把核对结果保存进文件属于 write,模板没有真实网络写操作。若后续来源改变,先重新判断原结论,再更新链接和范围,不能自动保留旧结论只替换日期。读者应始终能分清规范保证、产品文档与环境实测。

来源审核还应检查正文中的链接标签是否准确,避免标题指向另一产品或另一版本。

延伸阅读

Vite:开发服务配置 Vite:环境变量与模式 CommonMark 规范
同一专题 · 继续阅读一篇有用的技术笔记,应该留下哪五件事?Markdown 的价值:内容能离开当前编辑器。从本地修改到线上更新,中间发生了什么?查看整个专题 ↗