AI 生成的代码只在我机器上能跑：按版本、路径、编码、依赖锁四步定位

数据截至 2026-07，各产品的额度与报错口径以官方最新说明为准。

大多数人把「AI 写的代码在我机器上能跑，到别人那儿就崩」归因为模型写得烂，这个归因九成是错的。 真正的原因通常是：模型只能看到你贴给它的那段上下文，它写出来的代码默认跑在一个你没有明确描述过的隐含环境里——某个 Python 小版本、某个 Node 大版本、某种路径分隔符、某个默认编码、某份没被锁定的依赖树。你本机恰好满足这些隐含假设，所以它能跑；同事的机器、CI 容器、生产镜像不满足，所以它崩。代码本身可能一行都没错。

这件事的排查有一个很实用的性质：四类环境差异的失败指纹几乎不重叠。版本差异表现为「函数/属性不存在」或语法层面直接报错；路径差异表现为「文件找不到」但你明明看得见那个文件；编码差异表现为乱码或解码异常，且往往只在特定数据上触发；依赖锁差异表现为「昨天还好的今天崩了，谁都没改代码」。只要你先看指纹再动手，绝大多数情况十分钟内能定位。反过来，如果你上手就重装环境、就让模型「再改一版」，你会陷入随机漫步。

顺带说清本篇和站内两篇相邻文章的分工：AI 代码能不能上生产谈的是准入门槛与评审标准，AI 项目的技术债谈的是长期积累出来的结构性负担，而这篇只干一件很窄的事——把「同一份代码换个环境就跑不起来」的差异按顺序挖出来，属于事前预防加事中定位的操作手册。

一、先分因：四类差异各自的判别方法

排查的第一步不是修，是判型。给自己三分钟，只做一件事：确认这次属于哪一类。

版本差异。最典型的指纹是 AttributeError、ImportError、TypeError: unexpected keyword argument，或者 Node 侧的 SyntaxError 出现在你完全没改过的库文件里。判别方法很直接：在两台机器上分别打印运行时版本，把结果放在一起看。

python -V && python -c "import sys;print(sys.executable)"
node -v && npm -v

注意第二条命令里的 sys.executable——版本对不上只是一半，另一半是你以为在用的解释器根本不是实际在用的那个。虚拟环境没激活、系统里装了多个 Python、IDE 里选的 interpreter 和终端里的不是同一个，这几种情况加起来出现的频率比真正的版本不兼容还高。

路径差异。指纹是 FileNotFoundError、ENOENT，但你在文件管理器里能看到那个文件。三个子类要分开：一是硬编码的绝对路径（模型很容易照抄你贴给它的那一行日志里的路径）；二是分隔符与大小写（Windows 上的文件访问默认不区分大小写——NTFS 本身支持区分，但默认不开启；Linux 的 ext4/overlayfs 区分，于是 Utils.py 和 utils.py 在你这儿是同一个文件、在容器里是两个）；三是工作目录假设（代码里写了相对路径，但脚本被从另一个目录调起）。判别方法：把出错处的路径原样打出来，别猜。

python -c "import os;print(os.getcwd());print(os.path.abspath('config/app.yaml'))"

编码差异。指纹分两种：一种是启动就崩，报 UnicodeDecodeError；一种更阴——跑得通，但中文字段变成问号或乱码，直到某条特定数据才炸。Python 的 open() 在没显式给 encoding 时使用当前 locale 推导出的编码，这个值在不同系统、不同区域设置下不一样；Windows 终端的活动代码页还会另外影响输出的显示效果。判别方法是同时确认三处：文件本身的编码、代码里读它时声明的编码、进程实际用来解码文件的编码。

python -c "import locale,sys;print(locale.getpreferredencoding(False), sys.getdefaultencoding(), sys.flags.utf8_mode)"

这行有个容易搞混的地方值得点明：决定 open() 行为的是第一项（locale 编码），不是第二项。sys.getdefaultencoding() 在 Python 3 里的返回值是固定的 utf-8，它描述的是 str 与 bytes 之间隐式转换的编码，跟文件读写没关系——很多人拿它去「证明」自己的环境是 UTF-8，然后继续困惑为什么读文件还是报错。第三项是 UTF-8 模式是否开启（受 PYTHONUTF8 与 -X utf8 影响），开启后文本 IO 的默认编码会被强制成 UTF-8，这是最省事的兜底开关。不同 Python 小版本对这块默认值的演进不完全一致，具体以官方最新说明为准，但排查时的动作是同一个：把上面三项在两台机器上都打一遍再比。

还有一类容易被漏掉的编码差异是行尾。Git 的换行转换配置不一致时，同一份 shell 脚本在一台机器上是 LF、在另一台变成 CRLF，然后你会看到一个非常费解的现象：脚本第一行的 shebang 明明写对了，执行却报解释器不存在。用 git ls-files --eol 看仓库里每个文件实际的行尾状态，比肉眼看编辑器状态栏可靠。

依赖锁差异。指纹是时间性的：代码没动、机器没动，昨天绿今天红；或者两个人拉同一个 commit，一个能跑一个不能。根因是依赖没被真正锁死——只写了范围约束没提交锁文件，或者提交了锁文件但安装时用的命令绕过了它。判别方法是对比两边实际装上的东西，而不是对比声明文件。

pip freeze > /tmp/env-a.txt
npm ls --all > /tmp/tree-a.txt

在两台机器上各跑一次，然后 diff。差异行往往只有两三条，指向哪个包就查哪个包的变更。

二、判别表：从现象直接查到动作

现象	大概率成因	怎么验证	处置动作
属性/方法不存在，或库内部报语法错	运行时版本或库大版本不一致	两边打印 python -V / node -v 加解释器实际路径	用 .python-version / .nvmrc / engines 把版本写进仓库，本机重建虚拟环境
明明装了包却 ImportError	装到了另一个解释器下	打印 sys.executable 与 sys.path 前几项	显式用 python -m pip install，别直接用裸 pip
文件看得见但读不到	绝对路径硬编码 / 工作目录假设	打印 os.getcwd() 与解析后的绝对路径	路径一律基于项目根或配置项拼接，禁止字面量绝对路径
本机正常、容器里 ENOENT	大小写敏感性差异	在 Linux 侧 ls 精确文件名，与 import 语句逐字对比	统一命名规范并在 CI 用区分大小写的文件系统跑一遍
启动即 UnicodeDecodeError	读文件未显式指定编码	打印 locale.getpreferredencoding(False)，再确认文件真实编码	所有文本 IO 显式 encoding='utf-8'，进程侧设 PYTHONUTF8=1
中文变问号但不报错	输出侧编码或终端代码页不一致	换成写文件再看内容，隔离终端因素	落盘统一 UTF-8，日志编码显式声明
shebang 正确却报解释器不存在	行尾被转成 CRLF	git ls-files --eol 看该文件实际行尾	加 .gitattributes 把脚本钉成 LF
代码没改，构建从绿变红	依赖未锁或安装绕过锁文件	两边 pip freeze / npm ls 后 diff	提交锁文件，安装改用 npm ci 或带哈希校验的锁定安装
只有 HTTPS 请求失败，证书链校验不过	企业代理的自签证书未被信任	同一 URL 用 curl -v 看握手阶段报错	把内部 CA 装进系统信任库，别关校验
间歇 ETIMEDOUT / ECONNRESET	网络出口或代理差异，非代码问题	换网络环境复现一次	归到网络工单，代码侧只补重试与超时

表里最后两行值得单独说一句：很多被当成「AI 代码有问题」的故障，其实卡在网络与证书上。判断方法是把代码从等式里拿掉——直接用 curl -v 打同一个地址。如果 curl 也不通，就别再让模型改代码了。

curl -v -o /dev/null -w "http=%{http_code} dns=%{time_namelookup} tls=%{time_appconnect}\n" https://example.com/health

如果返回的是 401 或 403，那是凭证或权限；429 是限流，各家规则不同且会调整，以官方最新说明为准；500 是对端的事；而握手阶段就断，几乎总是证书或代理。

三、动作顺序：把四类假设从代码里赶到配置里

判型完成后，修的顺序有讲究。必须先修版本，再修路径和编码，最后处理依赖锁，因为前面没定住，后面的对比结果全是噪声。

第一步，把版本写进仓库。 目标不是「大家都用最新版」，而是「同一个 commit 在任何机器上解析出同一个运行时」。Python 侧写 .python-version 或在 pyproject.toml 里声明 requires-python，Node 侧写 .nvmrc 加 engines。这一步做完，你才有资格说两台机器「环境一样」。

第二步，路径和编码一次性收口。 路径的规则很简单：项目内所有文件访问从一个统一的根变量出发，根变量由入口处解析一次。编码的规则同样简单：所有文本读写显式声明 UTF-8，一处不漏。这两条不需要设计，只需要执行——而执行的正确方式不是靠人记，是靠仓库里的约定文件把它变成模型和人共同的默认值。这也是怎么写 CLAUDE.md那类项目约定文件真正的价值所在：你把「本项目所有文本 IO 必须显式 UTF-8」「禁止绝对路径字面量」写进去，后面生成的代码从第一版就带着这些约束，而不是你在评审时逐个抓。

第三步，依赖锁从「有」升级到「生效」。 提交锁文件只是及格线，关键是安装路径必须走锁文件。Node 侧 CI 里用 npm ci 而不是 npm install——后者在某些情况下会更新锁文件，这正是「本地和 CI 装出不同树」的常见来源。Python 侧至少要有一份完整的固定版本清单，更严格的做法是带哈希校验安装：

pip install --require-hashes -r requirements.lock

哈希校验的意义在于，它把「包名加版本号一致」升级成「字节一致」。用它有个硬前提：清单里每一项都必须用 == 钉死版本并带上对应的 --hash 值，漏一个就整体失败——这个「要么全有要么报错」的性质本身就是特性，它逼你不留缺口。

第四步，把检查自动化。 前三步做的是一次性收口，第四步保证它不退化。最省事的位置是提交前和 CI 两道口子：提交前跑格式和编码检查，CI 里跑一次全新环境的干净安装加测试。如果你用的工具支持在特定动作时触发脚本，把编码和行尾的检查挂上去比写在文档里有用得多——钩子机制怎么用这一篇讲的就是这类自动挂载的做法。

四、什么情况下别再折腾：止损点和回滚点

排查环境问题最大的成本不是修不好，是修的方向错了却不肯停。给自己定几条硬线。

止损点一：同一类现象改到第三版还没变化，停手。 让模型再生成一版代码去绕开一个环境问题，本质是在用代码补丁掩盖配置缺失。第三版还不行，说明你判型错了，回到第一节重新看指纹。

止损点二：你开始动系统级设置了，停手。 改系统默认编码、卸载系统自带解释器、全局关掉证书校验——这三个动作一旦做出来，你就制造了一台「只有你能跑」的新机器，问题从「一处不一致」变成「两处不一致」，而且下一个人无从查证。真正的边界是：能写进仓库的配置放仓库，必须动机器的操作走标准化镜像。

止损点三：超过半小时还没定位，换路子——用干净环境做二分。 别再在这台被你改花了的机器上折腾。起一个全新的容器或全新的虚拟环境，从空白开始按仓库里的说明装一遍，看是第几步失败。这个动作往往三五分钟就给出答案，比继续在污染过的环境里推理快得多。

回滚点的定义要提前做，不是出事时才想。 两个具体做法：一是在动手排查前先把当前状态存下来，别让「排查过程」变成不可逆的破坏；二是明确「回到哪个 commit 算安全」。

git stash push -u -m "before-env-debug"
git log --oneline -10

如果排查过程中被卷进了合并冲突，看到 <<<<<<<、=======、>>>>>>> 这些标记，先分清这是内容冲突还是行尾差异导致的整文件冲突——后者的特征是整个文件每一行都显示为冲突，这种情况不要手工合，先把行尾规则统一了再重新合。

还有一条属于「换条路」的判断：如果失败集中在网络可达性，而你用的是海外工具或模型，那要先接受一个前提——这类服务的官方条款对中国大陆通常有区域限制、不支持直连，市面上确实存在第三方中转，但稳定性、合规性和数据流向都要你自己承担，这里不做推荐也不给渠道。在这种前提下花时间调代码是白费，正确动作是把技术选型这件事重新过一遍，而不是继续排查。

五、避坑清单：为什么会踩，怎么避

坑一：只贴报错给模型，不贴环境。 为什么会踩——报错信息里通常不含运行时版本、操作系统、依赖树，模型只能按最主流的假设补齐，而最主流的假设未必是你的。怎么避——描述问题时固定带上四件事：解释器版本与实际路径、操作系统、相关依赖的确切版本、复现命令。这四行信息能把误诊率砍掉一大半。

坑二：把「本机能跑」当成验证通过。 为什么会踩——本机环境是你长期手工调出来的，携带了大量未记录的状态，它是最不具代表性的一台机器。怎么避——把「在干净环境里从零装一遍并跑通测试」定为唯一的通过标准，本机结果只算自测。

坑三：锁文件提交了但安装命令没换。 为什么会踩——install 类命令的语义是「让环境满足声明」，不是「精确复现锁文件」，它在某些条件下会写回锁文件。怎么避——CI 和部署脚本里只允许出现严格复现的安装命令，并且把锁文件的意外变更当成构建失败处理。

坑四：用 try/except 或 if os.name 把环境差异包住。 为什么会踩——这是最容易被接受的补丁，因为它立刻让程序不崩了，代价是把不一致永久固化进代码，后面每加一个平台就多一个分支。怎么避——分支只允许出现在真正的平台能力差异上（比如文件锁实现），编码和路径这类问题一律靠统一约定解决，不靠分支兜。

坑五：环境变量在你的 shell 里配好了，就以为配好了。 为什么会踩——交互式 shell 的配置文件不会被服务进程、定时任务、CI runner 读取，你的 export 只在你的终端里活着。怎么避——凡是程序运行必需的变量，都要有一份仓库内的示例清单（只写键名不写值），并在启动时做缺失校验，缺了就直接报错退出，而不是取到空值继续跑。

坑六：把数据文件的编码当成代码问题。 为什么会踩——同一份 CSV，有人用表格软件另存过一次，编码就变了，而报错栈指向的是你的解析代码。怎么避——解析入口处先做一次编码探测与显式声明，并且在测试数据里刻意放一条含中文和特殊符号的样本，让这类问题在测试阶段就暴露。

坑七：以为容器就等于一致。 为什么会踩——镜像标签会漂移，构建时拉到的基础镜像和上次不是同一个；构建缓存也会让你误以为改动生效了。怎么避——基础镜像用带摘要的精确引用，关键构建定期做一次无缓存重建来验证可复现性。

六、收束

环境差异这类问题的性质是：它不是模型的能力问题，是你的项目没有把自己的运行前提写下来。模型只是把这个缺失放大了——它生成代码的速度远快于你补齐前提的速度，于是原本一年才暴露一次的隐含假设，现在一周暴露五次。解法也因此很朴素：把版本、路径、编码、依赖锁这四件事从「大家心里知道」变成「仓库里写着、CI 里查着」。这个思路和规格驱动开发里强调的先定约束再产出是同一件事，只不过这里约束的对象是环境而不是需求。

留一份自检清单，新项目开工或者接手别人的项目时按顺序过一遍：

• 仓库里有没有明确声明运行时版本，而不是靠口头约定
• 有没有出现绝对路径字面量，工作目录假设是否显式解析
• 所有文本读写是否显式声明了编码，脚本行尾是否被 .gitattributes 钉住
• 锁文件是否提交，安装命令是否严格复现锁文件
• 必需的环境变量是否有示例清单，缺失时是否直接失败
• 有没有一条命令能在干净环境里从零跑通，并且最近真的跑过一次
• 出事时的回滚目标是否明确，排查前是否会先保存当前状态

这七条都能答「是」，你就基本告别了「在我机器上能跑」。