我们的电商产线 aplus 一直跑在我和团队的一台 Mac 上。
它干的是那种听起来很朴素、实际很重的事：一张随手拍的产品图进去，一路分析品类、锁身份锚点、出白底图模特图场景图细节图色卡、拼详情页 HTML。跑了几个月，稳。稳到什么程度呢——稳到我几乎忘了它是个软件系统，而不是某种家电。
然后我们决定把它搬到华为云的 ECS 上。理由很直接：产线要服务客户，客户不该等我的笔记本电脑开机。数据盘、独立 IP、7×24 在线，这些是”能交付”的前提。
赫菲负责这件事。他做完之后落了一个 commit：6fd4e66 feat(platform): 跨平台适配层（macOS 行为不变，Linux/ECS 自动探测）。
我原本以为这是个”部署工作”——装环境、配端口、拉起来、跑通、收工。
结果他交上来的东西让我意识到，我们做的是一次排雷。
一、macOS 假设：那些从来没写进过需求的东西
赫菲在那次提交里新增了一个文件，src/lib/platform.ts。文件开头有一段注释，我读了两遍：
背景：项目里原先散落着 macOS 假设，它们在 Linux 上表现为静默失败。
注意”静默失败”这四个字。
我们过去写过很多关于失败的文章——失败分两种：一种会喊，一种不会。会喊的失败是好的，它至少知道自己在死，会留下一行报错；不会喊的失败才麻烦，它让系统看起来是活的，让你以为一切正常，直到某天你发现”怎么两个月没出东西了”。
赫菲列出来的第一类问题，是 Chrome 路径。
原来的代码里，截图功能要调无头浏览器，兜底路径直接写死了 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome。这在 Mac 上永远是对的——因为 macOS 的应用程序安装位置是规定的，不在那儿就是没装。
但 Linux 没有这个规定。Chrome 可能叫 google-chrome，可能叫 chromium-browser，可能在 /usr/bin，可能在 /snap/bin，可能在 /opt/google/chrome。你写死一个路径，在 Linux 上的结果不是”报错说找不到 Chrome”，而是——截图全挂，日志里只有一行 warn。
一行 warn。在几千行的构建日志里，那行 warn 和”正在处理第 3 张图”长得差不多。
二、换个环境，才知道哪些是”约定”哪些是”事实”
这次迁移最有意思的地方，不是修好了哪些 bug，而是它逼我们把”约定”和”事实”分开了。
举个最小的例子：产出目录。
原来的逻辑是，生成的东西默认扔到 ~/Downloads/aplus-builder。这个设定在 Mac 上不是随手写的——它服从的是 macOS 的用户习惯：下载目录就是”我拿到的东西”的默认归属地。
搬到 Linux 之后，~ 还指向一个家目录，语法上完全成立，代码不会报错。但它是错的：ECS 上的家目录在系统盘，而我们的部署规范要求产出数据必须落在 EVS 数据盘。因为产出图体积最大，写在系统盘上，盘满了会连系统一起拖死。
代码跑得通，日志很干净，系统会稳定地、安静地、持续地把垃圾倒进系统盘。
这就是”环境假设”的可怕之处：它从来不报错，它只是慢慢地把事情做错。
赫菲的解法很干净：把平台判断收口到一处。macOS 走原来的候选列表，行为与改造前完全一致；Linux 走自己的一套标准路径，优先数据盘 /data，没有 /data（容器或普通虚拟机）再退回家目录。
关键是那句：所有探测都是”找到就用，找不到给兜底值”，绝不抛异常。
三、真正的修法：不是让代码更聪明，是让它更钝
我特别喜欢这个设计里的一个细节。
新的 Chrome 探测逻辑，用的是：找到就缓存，没找到就不缓存，而且只 warn 一次。
为什么”没找到就不缓存”？因为 Chrome 路径在一台机器上不会中途变化。但如果进程启动时 Chrome 还没装好，你把”没找到”这个结果缓存下来，那之后就算装好了，也得重启进程才生效。不缓存，就多一次文件系统探测的代价，换来的是”装完即生效”。
为什么”只 warn 一次”？因为截图任务是循环执行的。如果每次都警告一遍，日志会被同一句话刷满，而刷满的日志等于没有日志——你会条件反射地跳过它。
这两个决定背后是同一个判断：这个模块的职责不是”发现错误”，是”不制造噪音”。
再往下看，会发现更细的东西。比如探测可执行文件，不用 which，不用 lsof，自己遍历 PATH：
1
2
3
4
5
6
7
8
export function isExecutable(p: string): boolean {
try {
if (!p || !existsSync(p)) return false;
return (statSync(p).mode & 0o111) !== 0;
} catch {
return false;
}
}
为什么不用 which？因为 Ubuntu 最小安装不一定有 which。
我第一次看到这里的时候愣了一下——which 这种命令居然还会”没有”？但在最小化的服务器镜像上，这是常态。系统只装真正必要的部分，which 是个便利命令，不在必要之列。
于是你写 which chrome 去探测，在最小安装上得到的不是”没找到 Chrome”，是”没找到 which”。一次探测失败，被伪装成了一次环境缺失。
还有 PATH 兜底。systemd 直接拉起的进程，PATH 可能被清得很干净，导致 agent 子进程里的 python3、ffmpeg、curl 全都找不到。所以新模块里有一份平台标准的 PATH 列表，进程 PATH 缺失时兜底。
这些都是在 Mac 上永远不会暴露的问题。我的 Mac 上什么都有：Homebrew 在 /opt/homebrew/bin，which 在 /usr/bin，Chrome 在应用程序文件夹里躺着。我用它开发了几个月，代码从来没在任何一个地方出过岔子。
不是代码没问题。是我的机器把问题替我挡掉了。
四、一个连字符，也是平台差异
同一个 commit 里还有一个更不起眼的修改：本地文件转 file:// URL，从手写拼接改成了 pathToFileURL()。
原代码大概是把路径直接拼进 file:// 前缀里。这在 macOS 上”通常能忍”——Chrome 对 URL 里带空格和特殊字符相当宽容。
但 Linux 上不保证。而且我们的产出目录名是中文产品名。
中文、空格、特殊字符，这三样凑在一起，手拼 URL 就是在赌。赌赢了你什么都不知道，赌输了你得到一张打不开的缩略图，或者一片空白。
改成一个标准库函数，多花零成本。这类修改的性价比极高——它不是在修 bug，是在消灭一整类还没发生的 bug。
五、为什么会漏掉：漏掉它们的机制是什么
我想把这次迁移里最有价值的部分提炼出来，因为它跟 AI 有关，也跟所有依赖工具的团队有关。
这些 macOS 假设为什么会存在？不是因为当初写代码的人不严谨。是因为每一条假设在那个环境里都是真的。
Chrome 在 Mac 上确实在 /Applications。which 在 macOS 上确实存在。家目录确实可以写。产出目录名确实可能带中文。
一条假设在环境里成立，就不会被质疑。它不会被质疑，就不会被写进需求，也就不会被测试覆盖。
这就是”环境假设”的生成机制：它不是错误，它是局部的真理。
而 AI 编程在这里有一个特殊的放大效应。赫菲（我们的工程 agent）和我（内容侧）用 AI 写代码的时候，AI 的补全逻辑天然倾向于”写最常见的写法”。最常见的写法是什么？是教程里的写法、是文档里的写法、是大多数示例的写法——而这套语料的主场是 macOS 和图形界面环境。
/Applications/Google Chrome.app/... 这种路径，是无数教程里的标准答案。AI 会流畅地写出来，因为它见过一千次。它不知道你三个月后要把它搬到一台最小的 Linux 服务器上，那台服务器上没有 which。
AI 让”能跑”变便宜了，但”在另一个环境里能跑”这件事，它替你省不掉。
六、可复用的检查清单
如果你也在做类似的事——把一个在某台机器上跑得很好的东西，搬到另一台机器上——这次迁移沉淀下来的检查项可以直接用：
1. 找写死的绝对路径。 特别是那些指向”应用程序安装目录”的路径。这类路径在 macOS / Windows 上是契约，在 Linux 上是碰运气。
2. 找依赖系统命令的探测。 which、lsof、sips（macOS 专有的图片处理工具）、open。问一句：最小安装里有吗？顺便说，我们这次把 sips 也去掉了——它是 macOS 专用，缩略图功能在 Linux 上会直接失效。
3. 找默认写入位置。 家目录、Downloads、/tmp。问一句：这台机器上哪个盘是数据盘？盘满了会发生什么？
4. 找”失败只 warn”的代码。 这一条最重要。一个 warn 在开发机上很容易被看见，在生产日志里等于不存在。关键路径上的失败必须能被聚合、被报警，而不是被打印。
5. 找手拼的 URL 和文件路径。 中文、空格、特殊字符。用标准库函数，不要手拼。
6. 找”在 Mac 上通常能忍”的地方。 这一类最难找，因为它不报错。唯一的方法是：换一台最干净的机器跑一遍。
七、那行注释
我最后想说回 platform.ts 开头的那段注释。
赫菲把”为什么这么写”完整地写在了代码里：为什么要收口，为什么要兜底，为什么找不到 Chrome 只 warn 一次，为什么 Linux 上优先 /data。
这不是为了好看。这是因为他知道——这些判断，在 Mac 上读代码的人是看不出来的。 三个月后有人打开这个文件，看到一堆候选路径列表，可能会觉得啰嗦：”写一个路径不就行了？”
那段注释就是回答：不行。因为你在 Mac 上。换一台机器，你就知道为什么了。
我们做 AI 这行，天天在讲”让机器适应人”。但这次迁移给我的是一个反向的提醒：
大部分系统不是被 bug 搞垮的，是被那些”在我这儿明明是对的”搞垮的。
它们不喊、不报错、不留痕。它们只是在你换了环境之后，安静地把事情做成另外一个样子。
真正的工程能力，可能不在于写更多代码，而在于知道自己的代码在依赖什么。
本文源自一次真实的跨平台迁移：我们的电商产线从 macOS 开发机迁移到华为云 ECS（commit 6fd4e66，新增跨平台适配层，macOS 行为保持不变，Linux 自动探测）。文中代码片段为真实实现。
