「我这儿能跑」在协作里等价于「我不知道它为什么能跑」。这句话的代价不在当次，而在下一次：换机器、换成员、换 CI runner，同一份代码给出三种结果，排障从环境开始而不是从代码开始。
隔离要解决的问题只有一个：让「能跑」成为可复现的事实，而不是某台机器的状态。手段从版本文件到容器不等，选择依据是差异来源在哪一层。
1. 环境差异的四个来源
新成员第一次跑测试失败，报错指向业务代码，根因通常在下面四处。用错手段就是「装了 Docker 还是不一致」。
| 来源 | 典型症状 | 复现方式 | 版本文件能管吗 |
|---|---|---|---|
| 运行时版本 | 语法报错、API 不存在、行为差异 | 切版本重跑 | 能，这是它的本职 |
| 系统库 | 链接失败、GLIBC_2.xx not found |
查 ldd、换基础镜像 |
不能 |
| 环境变量 | 连错库、读到别人的配置 | printenv 输出逐项对比 |
不能 |
| 本地服务 | 端口占用、版本不匹配、数据脏 | 清库重来能否复现 | 不能 |
判断顺序：先在干净目录重跑，再对比 env，最后才怀疑代码。能在干净环境复现的才是代码问题。
2. 版本管理工具覆盖到哪一层
| 工具 | 管什么 | 盲区 |
|---|---|---|
nvm |
单个 Node 二进制 | 不管包管理器版本、不管全局包 |
pyenv |
多个 Python 构建 | 不管系统头文件、不管虚拟环境内容 |
asdf / mise |
多语言统一入口，按目录切换 | 不管系统库；插件本身要版本 |
volta |
Node 与全局 CLI 的固定 | 只覆盖 JS 生态 |
# .tool-versions：版本声明进仓库，本地与 CI 读同一个事实
nodejs 20.11.1
java temurin-17.0.10+7
python 3.11.7
$ mise install # 按文件装齐
$ mise current # 核对实际生效版本
$ mise exec -- mvn -v # 用项目版本执行，不污染全局
工具解决的是二进制可切换，解决不了系统库差异。它也管不住 IDE 与语言服务器：IntelliJ 默认用自带 JBR 而非 PATH 里的 JDK，注解处理器各自持有编译器实例，版本对不上就是「命令行能编、IDE 报红」。
一条纪律能让这一层自证：环境定义只在仓库里改。临时装到宿主机的依赖，要以提交补回版本文件或镜像，否则下次接入时它就成了只能口述的隐性依赖。
3. 系统库：版本文件触不到的一层
原生依赖（libssl、libvips、Chromium、libmagic）的版本由发行版决定。同一份 Python wheel 在 glibc 与 musl 上装不上，不是包的问题，是 ABI 的问题。
| 手段 | 一致性 | 代价 |
|---|---|---|
| 宿主机统一发行版 | 中 | 依赖运维纪律，升级牵连全体 |
| 静态编译 / 自带二进制 | 高 | 构建复杂，体积与漏洞修复成本上升 |
| 容器固定基础镜像 | 高 | 引入下节全部代价 |
多数团队的实际答案是「基础镜像固定到具体 tag，并按月核对补丁更新」，而不是在宿主机上追平版本。
4. 本地依赖服务：本机安装还是 compose
| 维度 | 本机安装 | compose |
|---|---|---|
| 首次启动 | 快，包管理器一条命令 | 中，要拉镜像 |
| 版本固定 | 弱，随系统升级漂移 | 强，镜像 tag 即版本 |
| 端口冲突 | 高发，全员默认 3306 | 可映射，仍要约定 |
| 数据清理 | 手动，容易残留 | down -v 一次清空 |
| 团队一致 | 靠文档 | 靠文件 |
| 长期成本 | 卸载残留、隐式依赖 | 卷管理、镜像体积 |
# compose.yaml：只起依赖，不起应用
services:
mysql:
image: mysql:8.0.36 # 锁小版本，不用 latest
ports: ["3307:3306"] # 避开本机已有的 3306
environment:
MYSQL_ROOT_PASSWORD: local_only
volumes: ["mysql-data:/var/lib/mysql"]
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1"]
interval: 5s
retries: 20
volumes:
mysql-data:
healthcheck 不是装饰：应用容器 depends_on 只等进程起来，不等服务可用，没有健康检查就会出现「启动即连不上、重启就好」的假故障。
5. 容器化的收益与代价
| 收益 | 代价 |
|---|---|
| 系统库与运行时一次固定 | 构建缓存失效一次就要全量重来 |
| 新成员从 clone 到能跑只依赖一个命令 | 文件系统性能下降，尤其 macOS |
| 环境缺陷从「人」转移到「镜像」 | GUI、调试器、断点需要额外通道 |
| 与 CI 共用同一份定义 | 镜像仓库成为新的单点 |
# 绑定挂载与卷的差别在 IO 路径上
$ docker run -v "$PWD":/app ... # 源码直通宿主，改文件即生效，IO 慢
$ docker run -v app-src:/app ... # 卷内复制，快，但改文件要同步
# macOS 上确认虚拟化文件系统，旧版 osxfs 下大仓库的构建会明显变慢
$ docker info | grep -i "filesystem\|virtiofs"
调试体验是容器化最容易被低估的代价：JVM 远程调试要额外开放端口并绑定 0.0.0.0；Node 的 inspector 要单独映射；IDE 的索引在挂载卷上会重建。如果团队每天有一半时间在断点里，容器化的收益会被这部分成本吃掉。
6. 开发容器与生产镜像该不该是同一个
| 策略 | 一致性 | 风险 | 适用 |
|---|---|---|---|
| 完全同一个镜像 | 最高 | 编译器和 shell 进生产，攻击面与体积都涨 | 小团队、单服务 |
| 同 Dockerfile 多 target | 高 | 需要维护 target 边界 | 多数服务端项目 |
| 开发用容器、生产另建 | 低 | 差异在发布时才暴露 | 有独立构建流水线 |
FROM eclipse-temurin:17-jdk AS build
COPY . /src
RUN ./mvnw -q -DskipTests package
FROM eclipse-temurin:17-jdk AS dev
RUN apt-get update && apt-get install -y curl vim # 调试工具只在 dev
COPY --from=build /src/target/app.jar /app.jar
FROM eclipse-temurin:17-jre AS prod
COPY --from=build /src/target/app.jar /app.jar
USER 10001
ENTRYPOINT ["java", "-jar", "/app.jar"]
判据不是「像不像」，而是差异项是否可控：同一个基础镜像、同一份依赖锁、同一个启动命令，只有工具与用户不同，差异就是可解释的；基础镜像都不同，所谓「本地验证过」就没有信息量。
7. 配置分层：默认值、本地覆盖、密钥
| 层 | 位置 | 能否进仓库 | 失效表现 |
|---|---|---|---|
| 默认值 | 代码内或 application.yml |
能 | 缺省值悄悄连上测试库 |
| 本地覆盖 | application-local.yml、.env |
样例能，实物不能 | 覆盖文件被提交，密钥泄漏 |
| 环境注入 | 容器 env、启动参数 | 不能 | 变量名拼错，静默走默认值 |
| 密钥 | keyring、密管服务 | 不能 | 复制粘贴到聊天记录 |
# 优先级从低到高：默认 < profile 文件 < 环境变量 < 命令行
$ SPRING_PROFILES_ACTIVE=local ./mvnw spring-boot:run
$ ./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081
# 样例文件只写键，不写值
$ cat .env.example
DB_URL=
DB_PASSWORD=
「变量名拼错自动走默认值」是最隐蔽的一类环境故障：服务起得来，连的是错库。缓解办法是启动时打印生效配置的键与来源（不打印值），或在启动校验里对关键键做存在性断言。
8. 数据可重建
| 手段 | 可重复 | 体积 | 适用 |
|---|---|---|---|
| seed 脚本 | 高，幂等即可反复跑 | 小 | 开发与测试基线 |
| 结构迁移 + 少量样例 | 高 | 小 | 需要演进的 schema |
| 生产 dump 脱敏 | 中，脱敏规则会腐化 | 大 | 复现真实分布 |
| 卷快照 | 高，但不透明 | 大 | 临时保存现场 |
-- seed 必须幂等：重复执行不产生重复行
INSERT INTO tenant (id, name) VALUES (1, 'demo')
ON DUPLICATE KEY UPDATE name = VALUES(name);
原则：数据是环境的派生物，不是环境的一部分。新成员从同事那里拷贝 dump，等于把别人的脏数据和对旧 schema 的隐式依赖一起继承。
9. 隔离粒度与上手时间
| 粒度 | 隔离对象 | 成本 | 适用 |
|---|---|---|---|
| 按项目 | 依赖与版本文件 | 低 | 默认选择 |
| 按版本 | 同一项目并行维护多个版本 | 中 | 需要同时回归 |
| 按团队 | 共享基础镜像与脚本 | 高 | 多服务、多人 |
可度量的指标只有一个：time-to-first-green，从 clone 到第一次测试全绿的时间。它把「环境好不好」从感受变成数字。
# bootstrap 脚本顺带记录耗时，作为环境健康度的基线
$ /usr/bin/time -f "bootstrap %e s" ./scripts/bootstrap.sh
$ ./scripts/bootstrap.sh --check # 只校验不安装，CI 与新成员共用
这个数值连续上升，说明隔离手段在腐化，而不是「新人不够熟练」。
10. 排错：五种「明明一样却不一样」
| 现象 | 原因 | 处理 |
|---|---|---|
| 本地绿、CI 红 | 版本文件没被 CI 读取 | 在 CI 里显式 mise install 或固定镜像 |
| 容器里连不上宿主服务 | localhost 在容器内指向容器自己 |
用 host.docker.internal 或服务名 |
| 改了代码没生效 | 绑定挂载路径错、构建产物被缓存 | 确认挂载点与热加载配置 |
| 端口冲突 | 多项目共用默认端口 | 项目级端口偏移，写进 .env |
| 测试偶发失败 | 依赖服务未就绪、共享数据 | 加健康检查，测试用独立 schema |
11. 边界：什么情况不必隔离
| 场景 | 结论 | 理由 |
|---|---|---|
| 单人项目，依赖极少 | 版本文件 + README 即可 | 复现成本低于容器维护成本 |
| 一次性脚本仓库 | 不隔离 | 生命周期短于隔离成本 |
| 性能敏感的本地调试 | 宿主直跑 | 容器文件系统与网络栈会污染测量 |
| 已在 CI 全量验证 | 本地可放宽 | 一致性由流水线兜底 |
| 依赖 GUI 与硬件 | 谨慎容器化 | 设备直通与图形栈成本高 |
隔离的强度应该与协作人数 × 换机频率成正比。两个人、一个月换一次环境，上容器是过度设计；十个人、每周有新成员，不上容器就是在给每个人发一份排障作业。
12. 自测
- 版本文件能管住环境差异的哪几层？剩下的层各自靠什么兜底？
- 容器里
localhost:3306连不上，第一件事查什么？ - 开发容器与生产镜像用同一个，收益与代价分别落在谁身上？
- 为什么说「新成员拷一份数据库 dump」是隐式依赖？
- time-to-first-green 变长，说明环境在哪一环腐化？
- 什么信号出现时，说明当前的隔离粒度已经不够用了？