浏览 AI使用教程
项目运行文档怎么写：从缺少文档到可实测的启动说明
运行文档不是把几条命令抄进 README。新人需要知道依赖版本、环境变量、启动顺序、预期输出，以及命令失效时去哪里核对。
需要哪一项，就直接查到哪一段
把表格、命令、清单或规则作为工作中的查询工具，不要求从头顺序阅读。
README 写着 npm start，项目里却根本没有这个命令
README 写着运行 `npm start`，实际 package.json 只有 `dev`；数据库步骤引用了已经删除的 `.env.example`。新成员花了一小时才从 CI 文件猜出正确命令。
- 命令与当前package.json对应
- 环境和变量名全篇一致
- 失败与未测试的动作未写成成功
经命令验证的本地运行手册要写清哪些字段
| 要记录的内容 | 怎么填写 | 检查点 |
|---|---|---|
| 环境前提 | 系统、运行时、包管理器、外部服务和版本要求。 | 每项来自配置或实测，不按技术栈猜 |
| 安装与配置 | 依赖命令、环境变量名称、示例值来源和敏感信息处理。 | 不把真实密钥写进文档 |
| 启动路径 | 工作目录、命令、端口、预期日志和健康页面。 | 新终端能按步骤启动 |
| 测试与构建 | 仓库实际存在的命令、预期退出码和输出位置。 | 命令已运行，失败项原样记录 |
| 停止与清理 | 如何停止进程、撤销临时资源和恢复配置。 | 不会留下不明后台服务或数据 |
一份可填写的完整运行手册
Markdown
按本仓库实际脚本替换后再执行
# 本地运行 环境：Node 22、npm；工作目录：仓库根目录。 来源：package.json 的 scripts 和 .env.example.local。 验证状态：本文示例未执行；执行者应补日期、版本与输出路径。 1. npm ci 2. 复制 .env.example.local 为 .env.local，设置非敏感 PUBLIC_API_URL。 3. npm run dev -- --port 4174 4. 浏览器打开终端实际显示的本地 URL；检查业务首页而非只看进程存在。 5. 保持服务窗口，在另一终端运行 npm test 与 npm run build。 6. 返回服务窗口按 Ctrl+C；再次访问同一地址应不再由本进程响应。 失败记录示例（构造）：build 报 Missing PUBLIC_API_URL。 处理：先看项目读取变量的位置和样例，不把名字相似的变量随意互换。 复测：重新运行同一 build，记录实际退出码；本例状态仍是待验证。 未覆盖：数据库依赖、生产配置、Windows与Linux差异；存在时必须补全后交接。
把实际记录与预期分开
| 项 | 预期 | 实际记录应填 |
|---|---|---|
| npm ci | 退出0 | Node/npm版本、锁文件、输出与退出码 |
| npm run dev | 服务可访问 | 实际端口、URL、浏览器结果 |
| npm run build | 产物与退出0 | 产物路径或完整错误，未跑就写未跑 |
这份经命令验证的本地运行手册服务哪项任务
| 需要确认 | 本例内容 |
|---|---|
| 现有材料 | 教学仓库假定 package.json 声明 dev/build/test，Node 22；提供 .env.example.local，开发端口4174。本页演示如何记录，读者应先验证自己的仓库是否存在这些文件。 |
| 不能越过的边界 | 文档里的每条命令实际执行；秘密只写变量名；平台差异和已知失败单列；不能根据文件名猜结果。 |
| 要交付的结果 | 经命令验证的本地运行手册 |
完成后的经命令验证的本地运行手册
预期交付是一份包含前提、工作目录、安装、启动、检查、停止和失败状态的 README；每项只按真实执行情况标已验证/待验证。下面未执行的教学命令不声称已在实际仓库通过。
为什么“照手册能启动，但测试仍无法运行”还不能交付
照手册能启动，但测试仍无法运行
- 原因
- 文档只覆盖主进程，遗漏依赖服务和测试数据
- 怎么改
- 从一个新检出目录重走构建、测试和停止流程，记录所有隐含前置