把本地开发环境收成一份可复现的说明

新同事把仓库拉下来之后，第一天往往不是在写功能，而是在问「这个服务到底怎么跑起来」。文档里写着「先装依赖」，但没写 Node 版本、数据库要不要初始化、环境变量有哪几个是必填的。等人问到第三遍，我就把启动过程收成了一份可以照着做的说明。

版本先钉死

语言运行时和包管理器不要只写「安装 Node」。我现在会在仓库根目录放一份 .node-version，README 开头写明当前使用的主版本。依赖锁文件必须进仓库。有人用 npm install 装出一套，有人用 npm update 装出另一套，后面排出来的问题经常不是代码问题。

容器只负责不好在本机安装的依赖，比如数据库和缓存。应用本身还是在宿主机上跑，改一行代码不用重新构建镜像。

启动命令只留一条主路径

我给仓库补了一个很短的 Makefile，目标只保留三个：

dev:
	npm run dev

test:
	npm test

lint:
	npm run lint

README 里对应写成三行：准备环境变量、启动依赖、执行 make dev。分支说明放到后面，不要在第一屏就出现「如果你用的是 Colima 请看这里」。第一屏的任务是让人把服务跑起来。

环境变量要有样例，也要有校验

.env.example 里只放键名和没有敏感信息的示例值。真正会让进程起不来的变量，在启动时检查，缺了就退出，并打印缺的是哪一个。不要等到第一个请求进来才抛一个含糊的连接错误。

我踩过的坑是：示例文件里有 REDIS_URL，代码里读的是 CACHE_URL。样例和代码对不上，比没有样例更耽误时间。改名的时候两处一起改。

数据怎么来

空库能启动，不代表能演示。我留了一个 make seed，写入少量固定的测试数据：一个管理员、两个普通用户、几条业务记录。种子数据要可重复执行，跑第二次不应该因为主键冲突失败。

不把生产数据的脱敏副本放进仓库。体积大、更新频繁，也容易把不该出现的字段带进来。

说明本身也要能过期

这份说明我放在 docs/dev.md，并在季度整理依赖时顺手走一遍。走不通就改文档，而不是在群里补一句「哦对，现在还要先执行这个脚本」。口头补充活不过一周。