“在我机器上是好的”：环境差异的完整分类学

每个程序员都说过这句话，也都被这句话噎过。

周一早上，同事在群里 @你：”拉了最新代码，构建挂了，你看看？”你在自己机器上拉了一遍，干净，全绿。你回了一句：”在我机器上是好的。”对话框安静了几秒，那种安静你能品出味道来。

这句话在行业里很是常见。它被做成过徽章，”Works on My Machine”，下面还煞有介事地标着”Certified”，仿佛一张官方认证。它常年占据”程序员最讨厌听到的话”榜单前列，和”这个需求很简单，改改就行”并列。久而久之，说这句话约等于摊手：我这边没问题，剩下的你们自己看着办。

但这篇文章想认真地为它辩护一句：这句话不是推诿，是证词。

说的人没有撒谎。程序在他的机器上，确实是好的。而这句话里藏着一个容易忽略的事实：这个 bug 依赖环境。它的触发条件不在代码逻辑里，或者说不全在，触发方程里有一个变量，正好藏在两台机器的差异之中。

但要把它从推诿变成证词，你得先有一张地图：环境差异到底分哪几类、每一类怎么作案、留下什么指纹。这篇文章就画这张图。

---

一、机制：环境是一份没人写下来的契约

要理解”为什么换个机器，行为就变”，得先拆掉一个潜移默化的错觉：源码即程序。仿佛只要代码一样，跑起来的就该是同一个东西。

把”程序是怎么跑起来的”这条链拉直，错觉就撑不住了：你的源码要先经过编译器（或解释器、运行时）加工成可执行的形态；执行时要向操作系统申请内存、读写文件、取时间、收发包；底下踩着 CPU 的指令集和浮点行为；对外还要连数据库、连第三方、连网络。源码只是这条链上最靠前的一环。

写成公式：

程序行为 = f(源码, 输入, 环境)

源码只是三个自变量之一。而”环境”这个变量最阴险的地方在于：它从来没有被声明过。函数有签名，接口有文档，但没有任何一门语言提供一行语法，让你写”本程序假设运行环境满足以下条件”。可每个程序都在默默做着成百上千条这样的假设：

• 假设依赖装的就是你测过的那个版本；
• 假设文件系统对大小写的态度和自己一致；
• 假设系统默认编码、时区、小数点符号”全世界都一样”；
• 假设 CPU 认识我用到的每条指令；
• 假设网络可达、服务在线、接口返回的还是旧格式。

这份没人写下来的清单，我称它为隐式环境契约。所谓环境类 bug，本质上全是这份契约被违约–只是合同文本谁都没见过：一方浑然不觉地违约，另一方浑然不觉地受害。

这个视角能统一很多”玄学”现象。Debug 与 Release 差异那篇论证过：同一份源码，debug 和 release 是两个程序。那其实是本文话题的一个特例–同一台机器上的两个环境。把视野放大：任何两台机器、任何两个环境，都是两个物理系统，各自满足着契约的不同子集。程序从 A 环境搬到 B 环境，等于拿着一份只在 A 地验证过的合同，去 B 地兑付。

于是，”在我机器上是好的”这句话的完整翻译是：我的环境恰好满足那份没人写下来的契约，而你的环境违约了其中某一条。至于是哪一条–这就是下一节分类学要回答的问题。

---

二、分类学：差异的五层谱系

环境差异五花八门，但如果按”离你的代码有多远”排个序，会收敛成清晰的五层，像五圈同心圆：代码在圆心，一圈圈往外，每一圈都有自己的漂移方式：

层	一句话	为什么会漂
1 依赖	你的代码引用的东西	版本会漂移；你引用的东西还引用别的东西
2 工具链	把源码变成程序的东西	每台机器装的编译器、运行时不一样
3 系统接口	程序运行时对话的操作系统	同一个问题，不同系统给出不同回答
4 硬件	程序脚下踩着的机器	指令集、精度、架构存在代差
5 外部世界	机器边界之外的网络与数据	你连的东西，不受你控制

每一层讲三件事：机制（为什么”不同”会出事）、案例（真实世界里它怎么作案）、指纹（什么症状应该先怀疑这一层）。指纹是排查时的分流台，比机制更值得背下来。

第一层：依赖，你引入的东西在漂移

机制。现代程序没有从零写的。你的代码站在几百个包上，这些包又站在它们自己的依赖上。你以为的依赖是棵树，实际上是张网。问题在于，你声明的版本往往不是一个点，而是一个区间：^1.2.3 的意思是”1.2.3 到 2.0 之间随便”。今天装是 1.2.3，半年后装可能是 1.9.0。声明相同，内容物不同。锁文件（lock file）没进版本库，或者有人手滑用了”装最新”的命令，两台机器拿到的就不是同一张网。

案例。这一层有一座行业纪念碑：left-pad。2016 年 3 月，一位开发者因为商标纠纷，把自己在 npm 上的全部包一键 unpublish，其中一个叫 left-pad，功能是给字符串左侧补空格，11 行代码。它不在你的 package.json 里？不要紧，它在你依赖的依赖的依赖里。当天，Babel、React 等一批明星项目的构建在世界各地集体阵亡。11 行代码，标出了”我以为我依赖的东西是稳定的”这句话的市场价。

日常版本低调得多：新同事入职，clone 仓库，npm install 一把梭，起服务就崩；而你两年前装好的 node_modules 稳如泰山。你俩的代码一模一样，不一样的是 node_modules 里那几百个包的版本组合。npm 后来专门加了 npm ci，严格按锁文件安装，装不出第二种结果。一个专门的命令被发明出来，就是官方对这一层问题的认罪书。

指纹：重新 clone、新机器装完依赖才复现；一切老机器一概正常。看到这个模式，先 diff 两边的依赖树，别碰代码。

第二层：工具链，把源码变成程序的东西不同

机制。同一份源码，交给不同版本的编译器，产出的就是不折不扣的两个程序。工具链的差异不止”版本号”三个字：新编译器会修 bug、改优化策略、换标准库实现；语言运行时的每个版本都在增删 API。C/C++ 还有一本暗账——未定义行为（UB）。这意味着不同版本的编译器，对同一处 UB 可以做出完全不同的判决：gcc 12 判它”恰好正确”，gcc 14 判它死刑。代码一个字没改，编译器换了一代，程序换了命运。

案例。这一层最著名的报错，碰过 Linux 部署的人都见过：

version `GLIBC_2.34' not found

你在 Ubuntu 22.04 上编译，产物里引用了新版 glibc 的符号；拿到 Ubuntu 20.04 上一跑，动态链接器当场罢工。代码没变，变的是”编译它的那台机器”。更隐蔽的是温柔的破坏：Python 3.12 删掉了 distutils，一堆构建脚本悄无声息地失效；macOS 上敲 gcc，实际执行的是 clang——命令一样，东西不一样；Visual Studio 里装的 MSVC 工具集是 v142 还是 v143，同一份 C++ 代码的产物可以有微妙差异——不崩，只是”算出来的数和以前不太一样”，比崩还折磨人。

指纹：重新构建之后行为变了，而把构建产物原样拷贝过去，行为不变。这条指纹把第二层和其余几层干净地切开。记住它，第三节的两个实验就是围绕它设计的。

第三层：系统接口，同一个问题的不同回答

这一层是重灾区，子类最多。共同机制一句话：程序向操作系统提问，而不同的系统对同一个问题给出不同的答案。程序没写错，问题也没问错，错在它以为答案是唯一的。

路径与文件系统。NTFS 默认不区分大小写，ext4 严格区分，APFS（macOS 默认）又不区分。于是 #include "String.h" 在 Windows 上编译通过，文件系统帮你把 string.h 找出来了；到 Linux 的 CI 上，直接”找不到头文件”。GitHub 上的经典坑同源：仓库里两个只有大小写不同的文件，Mac 上相安无事，到 Linux 上 checkout 直接冲突。Windows 还有几样特产：路径长度默认上限 260（MAX_PATH），仓库目录嵌得深一点，构建就神秘失败；路径里的空格（C:\Program Files）坑过每一代脚本；CON、AUX、NUL 这些保留名，你以为随手起的文件名，人家是系统设备。

编码与换行。中文开发者的集体创伤区。Windows 中文系统默认代码页 936（GBK），Linux 世界默认 UTF-8。一份不带 BOM 的 UTF-8 源文件，MSVC 在中文 Windows 上按 GBK 解读，中文注释当场乱码，甚至编译报错。控制台输出同理：程序打印 UTF-8，控制台按 GBK 显示，”锟斤拷”的出场方式。顺便问候一位老朋友：”烫烫烫”。MSVC 的 debug 构建把未初始化栈内存填 0xCC，两个 0xCC 按 GBK 一读正好是”烫”。换行符则是跨平台常客：Windows 上保存的 shell 脚本拿到 Linux 一跑，/bin/bash^M: bad interpreter——^M 就是 CR，一个不可见字符，废掉一个下午。

时间与时区。程序问系统”现在几点”，答案取决于这是本地时间还是 UTC、时区库（tzdata）是什么版本、夏令时规则长什么样。tzdata 是会被更新的”事实数据”：埃及 2023 年恢复夏令时，没更新 tzdata 的机器，4 月之后所有日程偏一小时——没有任何人改过任何代码，是规则本身变了。跨时区部署的系统里，”用本地时间还是 UTC 存储”这个当年随手做的决定，迟早会以 bug 的形式上门收租。

区域设置（locale）。德语环境的小数点是逗号：1,5 才是母语。一个按系统 locale 解析数字的程序，在德语 Windows 上把 “1.5” 读成 15。数据库排序规则同理：utf8mb4generalci 不区分大小写，换一个 collation，同一句 SQL 的比较行为和结果排序都跟着变。

权限与资源限制。管理员账户跑得好好的程序，换普通账户：没带兼容性清单的旧程序写 Program Files，会被 UAC 悄悄重定向到 VirtualStore。程序自以为写成功了，你打开目录一看，文件根本不在那儿。Linux 方言版：Too many open files（ulimit 默认 1024）。同一个故事，两种口音。

指纹：只在特定操作系统、特定语言/区域设置、特定账户下出现。排查方向是把两台机器的系统设置摆在一起对，而不是盯着代码。

第四层：硬件，脚下的地板不同

机制。编译器吐出的指令，最终由 CPU 执行，而 CPU 有代差：你的开发机支持 AVX2，客户机房那台老服务器不支持。浮点行为也随硬件和编译策略漂：x87 内部用 80 位中间精度，SSE 从根上就是 64 位。同一行代码，两代硬件算出的末位小数可以不同。对多数业务无所谓，对数值敏感的算法、对结果断言精确值的测试，这就是 flaky 的温床。

案例。性能调优时顺手写的 -march=native（”按本机 CPU 优化”）是这一层的自埋雷：产物在你机器上飞快，拿到不支持新指令集的机器上不是变慢，是直接 SIGILL（非法指令）当场崩溃。这几年更高频的剧情是架构差异：Apple Silicon 的 Mac 上跑 x86 镜像，要么慢得离谱（QEMU 逐条翻译），要么个别指令直接段错误。同事说”我 Docker 里好好的”时，记得多问一句：你是什么架构的 Docker？

指纹：换物理机、换虚拟机代际才出现；同一台机器上怎么折腾都复现不了。

第五层：外部世界，机器边界之外的东西

机制。前四层好歹都在机箱之内，第五层在边界之外：你的程序连的网络、调的服务、读的数据，没有一样归你管。这一层还爱和”时间”合谋——”环境没变过”往往是错觉，它只是变得慢、变得安静，你没察觉。

案例。头号惯犯是 hosts 文件：三个月前为了联调，你把 api.example.com 指到 127.0.0.1 挂了个 mock，联调完忘了删。此后你机器上一切正常，因为你跑的从来就不是真后端。HTTP_PROXY 环境变量是它的同伙。其次是时延：本地调用 1ms，你在循环里同步调一百次毫无压力；上了生产跨机房一次 300ms，超时雪崩。最后是数据：开发库是干干净净的 100 行测试数据，生产库的 1000 万行里藏着空字符串、超长字段和十年前录入的乱码。你的查询在开发环境优雅自如，在生产慢查询日志里挂号。

指纹：断网、换数据源、换账号之后，行为改变。反过来说也成立：本机 mock 一切正常的”好环境”，恰恰最值得起疑。

---

五层看完，压缩成一张分流表，贴在工位上不过分：

你看到的现象	先怀疑
重新 clone、新装依赖后才复现	第一层：依赖
重新构建才复现；产物原样拷过去没事	第二层：工具链
特定系统/中文环境/特定账户才复现	第三层：系统接口
换物理机或虚拟机代际才复现	第四层：硬件
断网或换数据后行为改变	第五层：外部世界

注意：真实 bug 可以跨层作案（依赖漂移叠加新版编译器，联手把一处潜伏的 UB 送上刑场）。分流表的作用是给出起手式，不是终审判决。

---

三、方法论：对拍与二分

地图有了，现场怎么动手？三个步骤。

第一步：两个实验，砍掉一半嫌疑

排查环境问题的全部纪律只有一条：一次只动一个变量。具体是往两个方向各做一个实验。

实验 A：产物不动，换环境。把构建产物（二进制、包、镜像）原封不动拷到故障机上跑。还崩，说明问题在环境侧（第三/四/五层）或产物与环境的交互上；不崩了，反过来查”跑”的方式：启动参数、工作目录、账户、环境变量。

实验 B：环境不动，重新构建。在故障机上（或一个干净容器里）从源码重新构建再跑。行为变了，第二层（工具链）嫌疑重大；行为没变，工具链洗脱嫌疑。

A、B 一交叉，五层的嫌疑范围立刻砍掉一大半。这一步最常见的翻车是一句”我把代码拉到他机器上重新 build 了一下，还是崩”。一次操作换了两个变量，产物和环境搅在一起，实验等于没做。

第二步：环境指纹，让机器自己交代

范围缩小之后，要回答的问题是：两台机器到底哪里不一样？

这件事靠问是问不出来的。”你装的什么版本的 Node？””应该挺新的。””系统是什么编码？””默认的吧。”人类对自己机器的记忆，不可靠到值得写进心理学教材。正确做法是让机器自己交代：一个采集脚本，两边各跑一遍，输出落成文件，然后 diff 这两个文件。我叫它环境指纹。它不需要完美，只需要把最常惹事的几十项拍下来：

# env-fingerprint.ps1（Windows）
$lines = @()
$lines += "=== OS ==="
$lines += (Get-CimInstance Win32_OperatingSystem |
  Select-Object Caption, Version, BuildNumber | Format-List | Out-String)
$lines += "=== CPU ==="
$lines += (Get-CimInstance Win32_Processor |
  Select-Object Name, AddressWidth | Format-List | Out-String)
$lines += "=== Locale / Codepage / TZ ==="
$lines += "Culture=$((Get-Culture).Name)  TZ=$(tzutil /g)"
$lines += (chcp | Out-String)
$lines += "=== Toolchain ==="
foreach ($t in "git","node","python","dotnet","cmake") {
  $c = Get-Command $t -ErrorAction SilentlyContinue
  if ($c) { $lines += "$t => $($c.Source)"
            $lines += ((& $t --version 2>&1 | Select-Object -First 1) | Out-String) }
  else    { $lines += "$t => (missing)" }
}
$lines += "=== Lockfiles ==="
foreach ($f in "package-lock.json","yarn.lock","Cargo.lock","go.sum") {
  if (Test-Path $f) {
    $lines += "$f => $((Get-FileHash $f -Algorithm SHA256).Hash.Substring(0,16))"
  }
}
$lines += "=== Env Vars ==="
$lines += (Get-ChildItem env: | Sort-Object Name |
  Format-Table Name, Value -AutoSize | Out-String)
$outFile = "fingerprint-$env:COMPUTERNAME.txt"
$lines | Out-File $outFile
Write-Host "done: $outFile"

#!/usr/bin/env bash
# env-fingerprint.sh（Linux / macOS）
out="fingerprint-$(hostname).txt"
{
  echo "=== OS ==="
  uname -a
  sw_vers 2>/dev/null
  echo "=== glibc ==="
  ldd --version 2>/dev/null | head -1
  echo "=== CPU ==="
  grep -m1 "model name" /proc/cpuinfo 2>/dev/null
  grep -o -m1 -E "avx2|avx512f" /proc/cpuinfo 2>/dev/null | sort -u
  echo "=== Locale / TZ ==="
  locale
  date "+%Z %z"
  echo "=== Toolchain ==="
  for t in git gcc clang node python3 cmake; do
    if command -v "$t" >/dev/null 2>&1; then
      echo "$t => $(command -v $t) ($($t --version 2>&1 | head -1))"
    else
      echo "$t => (missing)"
    fi
  done
  echo "=== Lockfiles ==="
  for f in package-lock.json yarn.lock Cargo.lock go.sum; do
    [ -f "$f" ] && echo "$f => $(sha256sum "$f" | cut -c1-16)"
  done
  echo "=== Env Vars ==="
  env | sort
} > "$out"
echo "done: $out"

两边各跑一次，然后：

diff fingerprint-MACHINE-A.txt fingerprint-MACHINE-B.txt

这个做法的哲学就一句话：不问”你觉得装了什么”，只看机器实际交代了什么。版本号、路径、locale、时区、环境变量、锁文件哈希，全是机器自己说的，没有一句经过人类记忆的转述。

（两个脚本照你的技术栈增删：写 Rust 就加 rustc/cargo，写 Java 就加 java -version。重要的不是采了什么，而是”两边跑同一个脚本”这个纪律——diff 的两边，必须是同一把尺子量出来的。）

第三步：把差异清单当嫌疑犯，逐个过堂

diff 出来的每一行差异都是嫌疑犯。还是二分：挑一个差异，在两台机器上把它抹平（版本对齐、locale 改成一致、环境变量同步），跑一次。行为跟着变，凶手到案；行为不变，洗脱释放，审下一个。全部抹完还没破案，回头重新审题：要么差异不在你的采集清单里（脚本没覆盖到的项），要么这根本不是空间差异，而是时间差异。”上周还好好的”不是两台机器不同，是”这周”和”上周”不同：证书过期、token 失效、第三方接口改版。第五层的隐藏款。

最后一个衔接：如果故障机器是客户环境、生产集群这种你够不着的地方，连”跑个脚本”都是奢望，那就别恋战交互式调试了。让现场采集转储文件发回来，事后取证。

---

四、预防：把雪片变成牲口

排查是止血。止血完了，该谈谈怎么少挨刀。

预防的思路一句话：让环境从不可复制的孤品，变成可量产的制品。运维圈有一对经典比喻——雪片（snowflake）与牲口（cattle）：雪片服务器独一无二、手工调教、坏了没法重建只能修；牲口服务器成群结队、完全同质、坏一头再补一头，没人心疼。你的开发环境、构建环境、部署环境，每一个都值得问一句：它是雪片还是牲口？

按层开药方：

• 第一层（依赖）：锁文件进版本库（package-lock.json、Cargo.lock、go.sum），CI 里用严格安装（npm ci），浮动版本号逐出 package.json。让”装依赖”从各装各的，变成按清单发货。
• 第二层（工具链）：工具链版本钉死（.nvmrc、rust-toolchain.toml、CI 里 setup-python 的版本号），或者干脆在容器里构建。更进一步：产物由 CI 统一构建、入库、分发，”一次构建，处处运行”，把”在我机器上构建”这句话从流程里开除。
• 第三层（系统接口）：devcontainer / Dockerfile 把系统配置固化进版本库；代码层面从源头少欠债——统一 UTF-8、统一 UTC 存储、统一用不依赖 locale 的解析 API。
• 第四层（硬件）：-march=native 不许进发布构建；CI 加多架构构建（x86-64 加 arm64），让架构差异在生产之前就暴露。
• 第五层（外部世界）：hosts 劫持要登记、要有过期时间，mock 不进个人配置；对外调用一律显式超时；测试数据里预埋脏数据。

比所有具体措施更值钱的，是两条纪律。

定期焚毁。雪片环境最典型的症状是”不敢重装”，谁也说不清里面还躺着哪些没记下来的配置。检验你的环境是雪片还是牲口，标准只有一条：把它删了，只靠版本库里的东西重建，多久能恢复如初？做得到的，环境是制品；做不到的，环境是文物。个人建议每季度烧一次，烧不丢的配置才是真配置。

CI 是参考机器。本地环境人手一份、各自漂移，唯一不站队的是 CI。它不属于任何人，只认版本库里的东西，因此它是那份隐式环境契约唯一的成文处：在 CI 里跑通，约等于契约被完整履行过一遍。谁的本机跑不动，请先向 CI 看齐，而不是让 CI 迁就你的机器。

但要诚实承认：预防有极限

最后这一小节，可能是全文最重要的话：上面所有手段，都只能固化你意识到的依赖。

锁文件锁得住 package.json 里写过的东西，锁不住”你不知道自己依赖了 glibc 的某个行为”；Docker 钉得住基础镜像的 tag，钉不住宿主机的内核、GPU 驱动，和那台机器独有的运气。容器保证”我这边和你那边一样”的前提，是”一样”的范围由你来圈定，契约里那些你从没意识到的条款，永远在清单之外。

这不是悲观，这是把话说准：环境差异可以被压缩，不能被消灭。工程上的赢法不是消灭它，而是把”差异导致的故障”从日常压成小概率事件，并且在小概率发生时，你手里有五层分流表和指纹脚本，能在几个小时而不是几周之内结案。一句话总结：预防负责让那句话少出现，方法论负责让那句话出现时不可怕。

---

五、结尾：把推诿变成起点

回到那句被做成认证徽章的话。

它名声败坏，不是因为它错了，而是因为它几乎总被用在剧情结束的地方：说完这句，双方耸耸肩，各回各家，bug 留在故障机上继续生活。但按这篇文章的论证，它本来属于剧情开始的地方。

• 它是证词：证明 bug 依赖环境，触发方程里藏着一个环境变量；
• 它是半个实验：好环境和坏环境已经就位，只差把差异清单拉出来对拍；
• 它是邀请函：两台机器的差异，就是嫌疑犯名单。

所以，下次再听到”在我机器上是好的”，与其翻白眼，不如接一句让对面愣住的话：

“太好了，那就把你的环境和我的 diff 一下。”

一个能这样接话的团队，徽章上的嘲讽就失效了。因为当”在我机器上是好的”从一句免责声明变成一个实验设计，环境差异就从玄学，变成了工程。

相关文章

• Visual Studio 中 Debug 模式和 Release 模式有什么区别——”同一份源码是两个程序”的机制特例，本文第一节的总纲
• 你越想看清它，它就越不存在：海森堡 bug 与调试的观察者效应——观察会改变系统；本文补上另一半：不观察，系统也会因环境而不同
• AI 写的 bug，长得很像正确的代码：一场调试认识论的重写——当代码不再由人逐行书写，隐式环境契约的违约只会更多