新人照着 README 跑依然报错？聊聊前端项目文档防腐与环境一致性实践

聊一个做前端项目绕不开的痛点：新人第一天入职，严格照着 README 一步步敲，结果第 3 步就红了一大片。

我写了几年项目文档，发现新手文档「腐烂」往往不是因为步骤写错了，而是漏掉了环境隐性假设。比如默认装了全局依赖、默认用了内部 npm 源、或者没有提供最新的 .env.example。

为了让 README 真正做到「开箱即用」，目前我们团队主要做了 3 件事：

1. 版本锁死在配置里，而不是写在文字里：在 package.json 声明 engines 和 packageManager，配合 Corepack 强制统一 Node 和 pnpm 版本，版本不对直接阻断执行。
2. 提供一个 pnpm bootstrap 脚本：把检查 Node 版本、复制环境变量模板、配置依赖源、安装依赖合并成一条命令，减少人为漏步。
3. 把 Onboarding 纳入 CI 验证：写一个简单的 Workflow，每周在干净的 Docker 容器里模拟「新人视角」克隆并启动一次项目，挂了就给维护者提 Issue。

大家平时是怎么保证 README 的「保鲜期」的？是靠新人踩坑后提 PR 修文档，还是有什么自动化或者工程化的手段？欢迎支招。