新人入职第三天还在装环境，代价不在那三天工资，在于没人能判断他是否已经"可用"。要回答这个问题，先得把"跑起来"定义清楚；定义不清，环境工程化就会变成无限投入——每有人抱怨一次就加一段文档、加一个脚本，首次跑起来的耗时却不动。
1. 这个目标在要什么
"能登录所有系统"不是判据，"能改一行代码并看到结果"才是。两者的差距就是真正的工作量。
| 目标表述 | 判据 | 代价结构 |
|---|---|---|
| 能登录所有系统 | 账号全开、VPN 通 | 便宜，卡在审批 |
| 能拉下代码 | clone 成功、依赖装齐 | 中，卡在下载与私服 |
| 能改一行并看到结果 | 改文案 → 构建 → 启动 → 看到变化 | 贵，卡在数据与服务依赖 |
| 能改对 | 改动合规、测试能跑、评审通过 | 知识问题，不是环境问题 |
第三行是建议的验收线：新人能在第一天结束前独立判断，不必问人。第四行属于带教，混进环境目标里会把两边都做不完。
2. 时间花在哪：五段拆解
拆开看，结论常与直觉相反：动手的时间不多，等的时间不少。
| 阶段 | 典型量级 | 时间形态 | 等待占比 |
|---|---|---|---|
| 工具安装 | 20–60 分钟 | 下载 + 版本核对 | 高，镜像慢时占七成以上 |
| 依赖下载 | 20 分钟–数小时 | 私服不全要逐个排查 | 极高 |
| 配置填写 | 10–40 分钟 | 边问边填，找正确值 | 中，强依赖他人 |
| 账号权限 | 半天–两周 | 审批排队，与本人无关 | 全部是等待 |
| 数据初始化 | 10 分钟–一天 | 导库、造数、清洗 | 中 |
这张表的意义在于：只优化"动手"，收益上限很低。脚本能把前两段从两小时压到十五分钟，压不动账号审批——那要走别人的队列。数字要按自己项目记，别拿表里的量级当结论。
3. 可跑起来的最小集
完整环境有七八个服务、三套账号、一堆历史数据，第一天全给等于把新人丢进看不懂的现场里排障。先给一条能证明回路通的路径。
// 最小可跑集：目标是在半天内证明"改动 → 结果"存在
REQUIRED:
runtime // 与 CI 同一版本，从版本文件读，不靠口头传
repo // 只拉主仓，子仓按需
build // 一条命令：make setup && make run
one-service // 只起核心服务，其余 stub 或容器
seed-data // 百行以内样例，能覆盖首页路径
OPTIONAL (第二天起):
full-stack // 全量服务 + 中间件 + 缓存
real-data // 脱敏切片，体积大，后给
extras // 调试工具、本地 APM、性能分析
代价要说清：最小集会让新人早期看到残缺系统，可能形成错误印象。补偿是把"缺哪块、何时给"写进清单。
4. 环境文档为什么必然失效
不是写得不好，是结构性问题：它描述代码之外的状态，代码一变状态就变，而文档没有任何机制被同步修改。
| 失效原因 | 机制 | 表现 |
|---|---|---|
| 版本升级 | 文档里的版本号是快照 | 按文档装完版本不符 |
| 服务拆分 | 新增依赖没写进步骤 | 少起一个服务，连接被拒 |
| 内网地址变更 | 地址写死在示例配置 | 复制后连到已下线机器 |
| 权限模型调整 | 文档说"找某人申请"，人已走 | 审批链断 |
唯一有效的缓解：把能变成可执行检查的部分抽出去。写"运行 make doctor，全绿即合格"，比十步手工步骤有效——doctor 会跟代码一起改。
// make doctor：把文档里最容易腐化的断言变成检查项
$ make doctor
[ok] runtime 20.11.1 (期望 20.11.x)
[warn] private-registry 未配置 → 走公网，慢但不阻塞
[ok] ports 3000 / 5432 空闲
[fail] fixture-db 未导入 → 执行 make seed
5. 环境即代码的三种程度
选错程度的典型后果：上了容器化但没人会维护镜像，半年后镜像积灰，脚本和文档一起烂。
| 程度 | 做法 | 一次投入 | 长期维护 | 消掉哪段等待 |
|---|---|---|---|---|
| 脚本化 | 一个 setup.sh 串命令 |
半天 | 低，但会漂 | 工具安装、部分依赖 |
| 容器化 | docker compose up |
数天 | 中高，要管镜像与卷 | 服务依赖、版本差异 |
| 声明式 | Nix / devcontainer / 云开发机 | 一到数周 | 高，需专人 | 以上全部，含系统层 |
判断依据是团队规模与变更频率：五人以内脚本化往往够；过十人、每月有新成员时容器化开始划算；声明式的成本只有在环境是多人长期共享资产时才回得来。
// devcontainer.json 的关键几行：环境变成仓库里的一个文件
{
"image": "registry.internal/dev/base:1.4",
"postCreateCommand": "make setup && make doctor",
"forwardPorts": [3000, 5432]
}
// 任何方案都要留回退：容器起不来时人还能干活
$ make setup --no-container // 退化为脚本化路径
6. 权限与账号：唯一不能自动化的部分
工具能脚本化、依赖能镜像、数据能造，"谁有权访问哪个系统"不行——它走人的审批队列，审的是身份不是技术。这段要单独排提前量，不能混进技术任务的时间里。
| 依赖项 | 审批链典型环节 | 提前量 | 阻塞什么 |
|---|---|---|---|
| 代码仓库读权限 | 主管 → 平台组 | 入职前 3 天 | 什么都做不了 |
| 内网/VPN | IT → 安全 | 入职前 5 天 | 连不上任何环境 |
| 数据库只读 | DBA → 数据 owner | 入职后 1–2 天 | 看不到数据 |
| 日志平台 | SRE | 入职后 2 天 | 排障靠猜 |
| 第三方沙箱密钥 | 采购 → 财务 | 一周以上 | 联调卡住 |
可执行的做法：这张表在 offer 发出后立即启动，而不是等入职当天。凡"入职当天才发起的审批"，一律按最坏情况排期。
// onboarding.yaml：把权限依赖写进流程，而不是记在谁的脑子里
- item: repo-access
start_by: T-3d // T 为入职日，负数表示提前
owner: 直属主管
blocking: true
- item: vpn-account
start_by: T-5d
owner: IT
blocking: true
- item: log-platform
start_by: T+2d
owner: SRE
blocking: false // 不阻塞首日回路，但阻塞排障
7. 示例数据：能跑但没用
回路通了，但库里只有五行数据、没有历史状态，任何分支都走不到。这是另一种失败：回路在，回路里的东西不足以让人理解系统。
| 数据方案 | 优点 | 缺陷 |
|---|---|---|
| 空库 + 建表 | 干净、可重建 | 页面全空，看不出在做什么 |
| 手工造数 | 贴合场景 | 不可重现，换人就重造 |
| 生产脱敏切片 | 真实分布，能复现疑难 | 流程重，且容易过期 |
| 种子数据进仓库 | 可版本化、可断言 | 要维护，脱敏判断得持续做 |
手工造数的成本不在第一次，而在第 N 个人来的时候没人知道他造过什么。种子数据随迁移脚本一起跑，长期更便宜。
8. 怎么量，以及远程的额外成本
度量只取三个，多了会变成填表。
| 指标 | 定义 | 采集方式 |
|---|---|---|
| 首次跑起来耗时 | 入职到本地见到自己改动生效 | 入职清单打勾时间 |
| 求助次数 | 能独立排环境问题之前的求助条数 | 群里 @ 人次数粗测 |
| 环境相关工单占比 | 环境类占全部支持工单的比例 | 工单分类统计 |
第一条看尾部不看均值：十人平均两小时、其中一个花了两周，说明存在未覆盖的环境分支，而它恰好属于新领域。远程入职丢掉的是非语言渠道——看邻座屏幕三十秒能解决的，变成描述、截图、来回验证。
// 把"我这边什么状态"变成可粘贴的一屏，替代截图
$ make doctor --json | tee env-report.json
$ git rev-parse --short HEAD && node -v && uname -sr
一次十五分钟的 setup 录屏，通常能让后续三五个新人少问二十个问题；它比文档抗腐化，因为能看到报错长什么样。
9. 排错表
| 现象 | 常见根因 | 处理方向 |
|---|---|---|
| 第一天什么都没装成 | 镜像走公网、依赖体积大 | 内网镜像 + 预置缓存 |
| 装完版本不对 | 版本靠口头传 | 版本声明进仓库，doctor 校验 |
make run 起但页面 502 |
少起依赖服务 | 最小集清单显式列出 |
| 访问正常但数据是空 | 未导入种子数据 | make seed 并入 setup |
| 卡在等账号 | 审批未提前启动 | 权限清单前置到 offer 阶段 |
| 每次都要手工修一处 | 环境有隐式状态 | 干净容器复现，把那步写进脚本 |
10. 边界
| 场景 | 为何收益被抵消 | 该做什么 |
|---|---|---|
| 单人项目 | 只有一个环境，隐式知识全在本人脑里 | 留一份 setup 记录，够重启即可 |
| 纯运维岗 | 工作对象是生产环境，本地开发不是主战场 | 投入转向访问通道与只读工具 |
| 环境已统一托管 | 平台已解决版本与依赖 | 只管账号提前量与数据种子 |
| 团队流动极低 | 一年招一个人 | 脚本化边际收益趋近于零 |
一句话："新环境"一年发生不到三五次时，为它建流水线不如为它写一页纸。
还有一层容易被混淆的边界：能跑起来不等于能改对。编译失败、连不上、版本不符属工程效率问题，用脚本和镜像治；"改对了但不知道影响什么"属知识问题，用结对、小任务、评审反馈治。把后者当前者治，结果是文档越写越长而没人看。
11. 自测
- "第一天能跑起来"的判据，为什么不是"能登录所有系统"？
- 五段耗时里，哪一段是脚本化压不动的，为什么？
- 最小集会让新人早期看到残缺系统，这个代价怎么补偿？
- 环境文档失效是写得不好，还是结构性问题？
- 团队五个人、技术栈稳定，环境即代码该做到哪一程度？
- 新人说"环境好了但干不了活"，这句话混了哪两类问题？