使用 claude code 编写 bash 脚本时的跨平台兼容问题

上周五晚上十一点，我坐在家里那台 MacBook Pro 前，用 Claude Code 五分钟“写”完了一个自动化部署脚本。把本地代码 push 到 GitLab，GitLab Runner 瞬间拉取脚本并在 WSL2 上的 Ubuntu 环境里执行，结果报了一行我从未见过的错误：/bin/sh^M: bad interpreter: No such file or directory。那一瞬间我才反应过来，这不是脚本逻辑的问题，而是那个看不见的换行符在跨系统时反咬了我一口。

这不是我第一次被 Claude Code 输出的 Bash 脚本“坑”，但这回它让我彻底决定把这件事情系统地拆解清楚。因为如果不追根溯源，你会发现用 Claude Code 写脚本的效率有多高，它的跨平台隐患就有多大，你可能会在一个孤立的系统上反复测试一切正常，然后交到同事手上、扔到 CI/CD 管道里、丢到生产环境时就崩得一塌糊涂。这篇文章，就是我用三个多月时间，在 macOS、Linux（Ubuntu/Debian/CentOS）、Windows（WSL2、Cygwin、MSYS2、Git Bash）四个环境、几十个实际脚本上反复踩坑后，整理出的一整套关于使用 Claude Code 编写 Bash 脚本时如何系统性地解决跨平台兼容问题的判断逻辑、操作方法和检查框架。

一、核心结论：Claude Code 写脚本的跨平台问题，本质是“AI 没有环境常识”

很多人以为 Claude Code 生成的脚本跨平台问题是因为 AI “不够聪明”或者“有 bug”。但在我大量使用之后，我认为根本不是。真正的原因是：Claude Code 是一个极度依赖上下文进行推理的对话式 Agent，如果我们在 Prompt 里不给它明确的操作系统边界，它就只会基于训练数据中最高频的环境去生成代码，而训练数据里 Bash 脚本最常见的使用场景就是原生 Linux 和 macOS，对 Windows 下的各种 Bash 兼容层，模型既没有足够权重的参数记忆，也没有主动追问的意识。

换句话说，Claude Code 写出来的 Bash 脚本，默认是 “为当前对话发生的那个系统定制的”。你在 macOS 的终端里和 Claude Code 对话，它就会假设这个脚本将来运行在与 /bin/bash、/usr/bin/env、$HOME 等环境完全一致的地方。而当你把同一个脚本拖到另一台电脑上时，只要这些前提假设崩塌一个，那脚本就会崩。

因此我对这个问题的核心判断是：跨平台兼容不是一个能被 AI 自动解决的问题，而是必须由人在 Prompt 设计、代码审查和自动化验证三个环节共同注入约束才能处理好的工程问题。 如果你希望一份脚本在 macOS、Linux、Windows 下的不同 Bash 实现中都能跑通，那你就不能只当 AI 的“使用者”，你得去当 AI 的“技术负责人”。

二、背景与真实场景：我们到底用 Claude Code 写什么 Bash 脚本？

在展开所有技术细节之前，必须先把使用场景界定清楚，因为并不是所有脚本都值得去追求跨平台兼容。我过去半年高频使用 Claude Code 来生成 Bash 脚本，主要集中在以下四类任务：

1. 开发者环境初始化脚本：比如在全新的电脑上安装 Homebrew、配置 Git、拉取 dotfiles、安装特定版本的 Node.js 等。这种脚本会在 macOS 和 Linux（以及 WSL）之间反复拷贝修改。
2. CI/CD 中的前置处理脚本：例如在 Docker 容器构建前检查文件完整性、动态修改配置文件等。这些脚本跑在 GitLab Runner、GitHub Actions 等不同操作系统镜像里。
3. 服务运维故障自愈脚本：用来监听端口、自动重启进程、清理日志等，需要在生产服务器（通常是 Ubuntu 或 CentOS）上直接跑，但有时候也会被运维人员在 Windows 的 Git Bash 里测试。
4. 本地工作流自动化：比如批量重命名文件、处理 CSV 数据提取等，这种脚本我常常在 macOS 写完，然后分享给团队成员，而团队里有人用 Windows 就用 WSL 跑一下。

在这四类场景里，我的一个最深体会是：最容易翻车的不是复杂的业务逻辑，而恰恰是那些看起来“人畜无害”的环境操作，比如定位一个 home 目录、查找某个命令的路径、或者判断操作系统类型。而恰恰是这些部分，Claude Code 生成得最快、也最容易让开发者忽略审查。

三、常见误区：五个最典型的错误假设

我在帮团队里十几位同事排查类似问题时，归纳出了一个很有意思的现象：大家不是不知道该考虑跨平台问题，而是都错误地高估了 Claude Code 的“环境感知能力”。 最常见的误区有这五个：

误区一：以为“Claude Code 生成的是标准 Bash，所以一定跨平台”

Bash 语言本身是标准的，但 Bash 运行时所依赖的外部命令（grep、sed、sort、xargs 等）在不同系统上的默认版本、参数行为可能完全不同。更不要说文件系统路径、权限模型这些“语言之外”的部分。语法跨平台≠行为跨平台。

误区二：以为“在 Windows 下用 WSL 就没问题”

WSL 是当前 Windows 下最接近原生 Linux 的 Bash 环境，但它仍然是“寄居”在 NTFS 文件系统之上的。如果你在 WSL 里操作 /mnt/c/ 下面的文件，换行符、权限位、/mnt 路径格式都会随时跳出来制造麻烦。而 Claude Code 完全不知道这些微妙差异。

误区三：以为“只要加个 #!/usr/bin/env bash 就万事大吉”

这确实是一个好习惯，但它只解决了 Find Shell 的问题，完全解决不了命令差异、路径格式、文件权限等其余四个维度的问题。

误区四：以为“用 CI 跑一次没报错，就是跨平台兼容的”

只有一种环境下跑过，不代表在另一种环境下一样的结果。跨平台兼容的真正验证必须至少在两个以上操作系统 + 两个以上 Shell 实现中跑过。

误区五：对 Claude Code 的“Agent 能力”有过高期待

很多人以为 Claude Code 可以像人一样，按需安装缺失的工具、自动适配路径。但现实是，除非你在 Prompt 里清晰写好约束，否则它只会在当前对话的环境里给你看似正确的输出。而这种输出在跨平台时往往会“安静地失败”，不是报错，而是行为不符合预期，比如备份脚本备到了不同的目录。

为了让大家更直观地理解这些误区的分布和影响，我根据我们在团队内部的排查统计，整理了一个常见误区与发生频率的对比。

四、专业判断逻辑：五个维度的跨平台风险评估模型

在排查了超过一百份 Claude Code 生成的 Bash 脚本之后，我提炼出了一个非常实用的风险评估方法，我把它叫作“Bash 跨平台五维风险模型”。每次拿到一个 AI 生成的脚本，我都会沿着下面这五个维度快速扫描，几乎可以拦截 95% 以上的跨平台故障。

维度一：换行符（Line Endings）

风险点：Windows 下文本编辑器或某些 Git 配置会把换行符转换成 CRLF（\r\n），而 Linux/macOS 只认 LF（\n）。当脚本从 Windows 端转移到 Linux 执行时，sh 解释器会把行末的 \r 当成命令的一部分，导致 #!/bin/bash^M 之类的错误。

判断标准：只要脚本曾经在 Windows 文件系统上编辑或传输过，就必须假设存在 CRLF 风险。

维度二：路径格式与分隔符

风险点：不同系统用户主目录路径不同（/home/username vs. /Users/username vs. 通过环境变量 $HOME），Windows 原生路径使用反斜杠且带盘符（C:\Users\...）。如果脚本硬编码了 /home/ubuntu/，在 macOS 或 WSL 下就会找不到目标位置。

判断标准：脚本中如果出现任何正斜杠开头但不使用 $HOME 或 ~ 的绝对路径，都视为高风险。

维度三：外部命令的行为差异

风险点：同样的命令名，在 macOS 上通常是 BSD 变体（如 sed、grep、xargs），在大多数 Linux 发行版上是 GNU 变体。非 POSIX 标准的选项在不同系统上可能完全不可用，或语义相反（例如 sed -i 参数）。

判断标准：凡是使用了 awk、sed、grep、sort、date 的非基本选项，都需要检查 POSIX 兼容性。

维度四：Shell 与工具链可用性

风险点：#!/bin/bash 在 FreeBSD 或某些精简容器镜像中可能不存在，command -v 命令在部分古老 Shell 中也不可用。Windows 的 Git Bash 自带的工具集会少很多常用命令。

判断标准：脚本如果大量依赖 apt-get、brew 等包管理器，或依赖特定 shell 版本的内建命令，就必须谨慎评估。

维度五：权限模型

风险点：Windows 文件系统（NTFS）不原生支持 Unix 的可执行权限位，WSL 虽然在 /home 下可以正确保留权限，但在 /mnt/c 下所有文件会被视为 777 并不可直接 chmod +x。如果脚本依赖 chmod 或检查权限，就可能失效。

判断标准：凡是脚本中自包含 chmod +x 或者依赖文件可执行位的检查，都需要在 WSL 与 Linux 双环境验证。

这五个维度的风险不是孤立的，它们经常两两交织。在我的排查记录中，综合多重风险交叉触发的问题占比最高。

专业判断小结： 以后每次用 Claude Code 生成脚本，我都会先在心理上做一个五维打分，如果每个维度都是“低风险”，那我基本可以放心拿去做部署；如果有任何一个维度是“高风险”，我就必须手动修改或在 Prompt 里加入针对性的约束指令。

五、深度案例拆解：五大脚本杀手与 Claude Code 生成实例分析

下面我会用五个最常遇到的实战问题，展示 Claude Code 出警的真实例子（都是我在不同时期实际遇到并记录下来的），同时给出根治的 Prompt 补丁和事后修复脚本。

1. 换行符陷阱：^M 幽灵错误

场景还原： 我在 macOS 的 iTerm2 里对 Claude Code 说：“帮我写一个检查 Docker 服务状态并重启的脚本。” 它输出了一个标准的、可运行的 healthcheck.sh。我用 SCP 把它传到了 Windows 下的 WSL 目录里，运行后立刻报错：

-bash: ./healthcheck.sh: /bin/bash^M: bad interpreter: No such file or directory
根因： 文件传输过程中经过了一个 Windows GUI 工具（我猜是 WinSCP 的默认文本模式传输），换行符被转成了 CRLF，而 WSL 下的 Bash 完全不接受。

解决方案分两步：

预防（在 Claude Code 的提示语中直接要求）：

请在生成脚本时确保所有代码行使用 Unix 换行符（LF），并在文件末尾增加一个空白行以避免尾部反斜杠续行丢失。

事后修复（用 sed 原地处理，无需额外安装工具）：

sed -i 's/\r$//' healthcheck.sh

教训： 如果你是在 macOS 或者 Linux 下使用 Claude Code，但脚本的最终宿命是经过任何 Windows 渠道分发，必须在 Prompt 里加入换行符的强制约束。

路径分裂症：硬编码 /home/user 的致命诱惑
Claude Code 常见不良生成示例：

log_dir="/home/deploy/logs"

log_file="${log_dir}/app_$(date +%Y%m%d).log"

mkdir -p "$log_dir"

这段脚本在 Ubuntu 上完美运行，但换到 macOS 后，/home/deploy 压根不存在（macOS 的用户目录在 /Users/），脚本不会创建任何日志，然后后续步骤静默失败。

分析： Claude Code 的训练语料里 Linux 服务器场景占比极高，所以当它看到 “deploy 用户”这样的上下文，自然就会推导出 /home/deploy。这是 AI 统计性推理的必然结果，而不是 bug。

修复 Prompt 约束：

请使用 $HOME 环境变量来定位用户家目录，所有目录创建前请检查环境变量，避免直接使用 /home/ 或 /Users/ 路径。
修改后脚本：

log_dir="${HOME}/logs"

log_file="${log_dir}/app_$(date +%Y%m%d).log"

mkdir -p "$log_dir"

额外验证命令：

# 快速扫描脚本中的硬编码路径
grep -nE '^[[:space:]]*(/home/|/Users/|/root/)' script.sh

3. grep / sed 的 GNU 与 BSD 之争

问题现象： 我在 macOS 上让 Claude Code 生成一个提取特定字段的脚本，它用了 grep -P（Perl 正则）。该脚本在 Ubuntu 上运行正常，但换到 macOS 自带的 BSD grep 时，直接报错 invalid option -- P。

另一个更隐蔽的细节： sed -i 的语义差异。

• GNU sed：sed -i 直接原地修改。
• BSD sed（macOS）：sed -i '' 才能原地修改，-i 后面必须带一个扩展名用于备份，如果用 sed -i 不加引号会崩溃。

Claude Code 为什么会犯这种错？ 因为它在处理正则表达式替换时，默认选择最强大最方便的 GNU 选项，根本没有提醒你这可能在 macOS 下不兼容。

防御式 Prompt 模板：

生成脚本时请使用 POSIX 兼容的 grep 选项（避免 -P、-o 等 GNU 扩展）；sed 的 -i 操作请使用 'sed -i.bak' 并随后删除备份文件，或直接使用适用于 GNU 和 BSD 的兼容写法：sed -i'' 或 sed -i 's/.../.../'（请注意不同系统的差异，请输出一个在 macOS 和 Linux 都能运行的方案）。
实战中的兼容写法：

替换文件中的文本，兼容两种 sed

sed -i.bak 's/old/new/g' target.conf && rm -f target.conf.bak

或者使用 Perl 单行命令作为替代，Perl 在不同系统上的行为高度一致。

自己设计一个跨平台 grep 兼容包裹函数：

ck_grep() {
if echo | grep -P '' >/dev/null 2>&1; then

grep -P "$@"

else

grep -E "$@"

fi

}

4. #!/bin/bash 的路径假设：当 Bash 不在 /bin 时

这个问题在 FreeBSD、一些极简容器镜像（如 distroless 部分）或者一些古老 Linux 系统上很常见。Claude Code 生成的脚本绝大多数都用 #!/bin/bash，因为它学习到的 Bash 位置就是 /bin/bash。

一个更通用的 Shebang 是：

#!/usr/bin/env bash
这行代码会在 PATH 中找到第一个匹配的 bash 并执行，极大地提高了可移植性。

但注意： 在部分环境中，/usr/bin/env 可能不存在，或者 bash 可能在路径的末尾，但这种情况实在太罕见。99% 的场景下，#!/usr/bin/env bash 都是最佳跨平台实践。所以我在和 Claude Code 对话时，通常会先说明：

生成的所有 Shell 脚本请使用 #!/usr/bin/env bash。

权限与可执行性：chmod +x 在 WSL 混合场景下的痛苦
在 WSL1 早期版本和 WSL2 中，当你在 /mnt/c/ 下操作 NTFS 文件时，chmod +x script.sh 不会真正生效，文件仍然以 777 权限挂载，但执行时依然可能报 Permission denied。这是因为 NTFS 根本不存储 Unix 权限位，WSL 驱动只是模拟了一层。

Claude Code 完全不知道这种底层细节。有一次我的脚本在 /mnt/c/temp 下试着调用 chmod +x 并执行，结果触发了奇怪的权限拒绝，排查了一个多小时才意识到文件系统类型问题。

规避原则：

所有需要运行的脚本，都应该放在 WSL 的 Linux 原生文件系统内（/home/  下），不要放在 /mnt/c/ 下。

在 Prompt 里可以要求 Claude Code 生成一个前置检查：脚本运行前先检测当前文件系统类型，如果是 drvfs 或 9p 则给出警告。

简单检测是否在 WSL 的 Windows 文件系统上

if [[ "$(pwd)" == /mnt/* ]]; then

echo "警告：当前路径位于 Windows 文件系统，可能存在权限问题，请将脚本移至 Linux 文件系统内运行。" >&2

exit 1

fi

一个我常用的 Claude Code Prompt 补丁：

如果脚本需要修改自身权限或依赖可执行位，请首先检查当前工作目录是否在 /mnt/ 下，并给出显式错误提示。

终极武器：针对 Claude Code 的系统化跨平台 Prompt 工程策略
经过了上面这些血泪教训，我逐渐形成了一套“跨平台提示语模板”。每次我让 Claude Code 写 Bash 脚本，都会根据目标环境选择不同级别的 Prompt。

级别一：通用单平台 Quick 脚本（不需要跨平台）

如果只是自己临时用一下，我不加任何跨平台要求，仅提供任务描述。

帮我写一个循环检查 Git 仓库状态并自动 pull 的脚本。

级别二：跨平台基本要求

要求 Linux 和 macOS 通用，同时避免 Windows 路径问题。

生成一个 Bash 脚本，该脚本需要同时在 macOS 和 Ubuntu 上正常运行，并使用 POSIX 兼容命令；路径请使用 $HOME 或相对路径，避免硬编码 /home 或 /Users；请使用 LF 行尾，并使用 #!/usr/bin/env bash。

级别三：全平台兼容（含 WSL/Git Bash/MSYS2）

生成一个在以下环境中均可运行的 Bash 脚本：

macOS 12+

Ubuntu 20.04+

Windows WSL2 (Ubuntu)

Windows Git Bash

要求：

不依赖 admin 权限；2. 不使用 GNU 特有选项，若必须使用，提供 fallback 方案；3. 所有文件操作使用 Unix 路径风格；4. 对于 GNU vs BSD 的命令差异，提供一个运行时的兼容逻辑；5. 脚本中附带注释标记风险命令。

<p>实际上，我多数时候用的是<strong>级别二</strong>。因为真正需要同时兼容 Git Bash 和 MSYS2 的场景并不多，过度通用反而增加复杂度。</p>

从这个图上可以清楚看到，并不是要求越“严苛”就越保险。如果没有具体的技术约束注入（比如明确要求用子函数做 fallback），Claude Code 可能会生成一些“想当然”的兼容代码，反而引入了新错误。

我目前的最佳实践是：在 Prompt 里直接给出一个我验证过的、可复用的兼容函数模板，让 Claude Code 在脚本内部引用。 例如：

请在你的脚本中定义一个 os_is_macos 函数：
os_is_macos() {

[[ "$(uname -s)" == "Darwin" ]]

}

并在所有需要区分系统的位置使用它，在注释中标注 #PORTABILITY。

这样 Claude Code 生成的代码就有了清晰的、明确的跨平台执行路径，不会产生自创的混乱逻辑。

七、代码审查的自动化与集成：用 AI 验证 AI

光有好 Prompt 还不够，因为 Claude Code 的输出依然可能会有幻觉。我的做法是建立一套自动化的跨平台兼容性静态检查，把它直接集成到代码审查流程里。这套流程不需要复杂的 CI，只要几行命令：

1. 检查换行符

file script.sh | grep -q 'CRLF' && echo "警告：脚本包含 Windows 换行符" && exit 1

扫描硬编码路径
grep -Pn '^(?!#)\s*(/home/|/Users/|/root/)' script.sh && echo "发现硬编码绝对路径，请改用 \$HOME" && exit 1
检查命令的 GNU 特有选项
grep -Pn 'grep\s.*-P|sed.*-i[^.]' script.sh && echo "可能存在非 POSIX 选项，请验证" && exit 1
Shebang 检查
head -1 script.sh | grep -q '^#!/usr/bin/env bash$' || echo "Shebang 未使用 env bash，跨平台性可能降低"

我自己把这些检查写成了一个简单的 check_bash_cross_platform.sh，每次收到 Claude Code 的输出或者在同事提交 MR 时，跑一遍这个脚本，整个交叉风险一目了然。这个脚本本身也是用 Claude Code 生成的，但在我给了极其严格的约束之后。

不同角色的实战指南：你该怎么用这套方法论？
并不是所有使用 Claude Code 编写 Bash 的人都需要同样的跨平台策略。我把典型的用户分成四类，分别给出具体建议。

纯 Linux 服务器运维
现状：生产环境清一色 Ubuntu，脚本永远在 Linux 上跑。

跨平台风险：较低，但要注意不同发行版的工具链差异（比如 netstat vs ss，不同版本的 python 路径）。

行动建议：在 Prompt 中指定发行版和版本，运行环境固定后可以忽略 BSD 兼容问题，但依然要处理换行符（如果有人从 Windows 提交脚本）。

检查重点：shebang、绝对路径、依赖的包是否存在。

macOS 主力开发 + Linux 生产部署
现状：这是我自己的典型情况，在家用 Mac 开发，部署到 Linux 服务器。

风险：处于跨平台的“重灾区”，几乎上述五个维度都可能踩中。

行动建议：

Prompt 使用级别二（基本跨平台要求），

所有脚本在 macOS 上测试后，必须再在 Docker 的 Ubuntu 镜像中跑一次，

强制使用 #!/usr/bin/env bash，

建立一个类似上面的自动化检查清单。

额外技巧：用 Docker 快速验证跨平台，命令：

docker run --rm -v "$PWD":/work -w /work ubuntu:22.04 bash script.sh

Windows + WSL 开发者
风险：除了命令差异，还要面对 NTFS 文件权限和 /mnt/c 路径陷阱。

行动建议：

所有脚本文件放在 /home/ 下，永远不要从 /mnt/c/ 运行敏感脚本。

Prompt 中加入 NTFS 不兼容警告生成。

使用 dos2unix 或 sed 预处理从 Windows 端传输来的脚本。

特殊注意：Git 的 core.autocrlf 配置应设为 input，避免自动 CRLF 转换。

多平台工具链维护者（需要同时支持 Git Bash、Cygwin 等）
风险极大，需要大量条件判断。

建议：

在 Prompt 里提供详细的平台检测模板，避免 Claude Code 自己发明检测逻辑。

使用 uname -s 和 uname -o 联合判断操作系统，而不是仅靠着 OSTYPE 变量。

将功能拆分为独立的小脚本，减少单脚本跨平台的耦合复杂度。

取舍：很多时候我会直接放弃完全兼容 Git Bash，转而推荐用户使用 WSL。因为投入产出比太低。




取舍之道：什么时候不该追求跨平台兼容？
必须有一个明确的观点：不是所有 Bash 脚本都值得做跨平台兼容。 我在早期犯过的一个错误就是过度工程化，为了让脚本在四种系统上都跑通，加了近一倍的兼容代码，结果可读性急剧下降。

以下情况我建议放弃跨平台兼容，仅保留必要的可移植性约束：

脚本生命周期短，只在一个已知环境中运行。 比如临时数据迁移脚本，跑完就扔。

脚本高度依赖系统特定功能。 比如需要 systemctl 或 launchctl 来管理服务的脚本，跨平台几乎是伪命题。

团队成员环境高度统一。 比如全公司统一配发 MacBook，服务器都是 Debian，就没必要为 FreeBSD 操心。

以下情况则必须追求跨平台：

脚本会进入公共仓库或开源项目。

脚本用在 CI/CD 中，需面对多种 Runner 操作系统。

作为公司内部工具集发布给所有员工，员工可能使用不同 OS。

取舍的核心判断标准是受众的操作系统多样性。我建议在脚本的注释头部写清楚支持的平台，这样也方便后续维护者调整。




建一个你自己的跨平台兼容知识库（与 Claude Code 深度融合）
最后这一部分，是我认为能够带来长期复利的行为。我的做法是把所有这些经验固化为一个 Markdown 文档，里面包含了跨平台检查清单、兼容函数模板、常见错误案例。然后我直接在 Claude Code 的对话里引用这个知识库。

例如，我需要写一个新脚本时，会这样开头：

请参考以下跨平台兼容规则，生成一个日志清理脚本：

[粘贴我的规则文档]

请严格遵守。

Claude Code 会认真地遵循这些规则，生成的脚本质量明显提高，而且出错后我也更容易定位是哪条规则忽略了。

这份知识库文档我一直在迭代，包括：

• 5 类常见错误的描述与修复代码；
• 推荐的 shebang 与编码声明；
• 几个可以即插即用的兼容包裹函数（grep wrapper, sed wrapper）；
• Docker 快速验证命令模板。

有了它，我就不用每次在和 Claude Code 对话时反复手打相同的要求，效率提升至少 40%。而且更重要的是，新加入项目的同事也能快速继承这些经验，不用再重复踩我踩过的坑。

结尾：从依赖 AI 到驾驭 AI

使用 Claude Code 编写 Bash 脚本确实爽，尤其是在处理重复性、模式化的代码时，效率甩手写好几条街。但在这篇文章里，我一直想强调的其实就一件事：在跨平台兼容这个领域，现在的 AI 仍然是一个缺乏物理直觉的实习生，它需要你，一个亲身踩过坑的工程师，来给它“装”上对操作系统差异的感知。

你不是在和一个全知全能的神对话，你是在和一个极度聪明的、需要上下文约束的工具协作。跨平台问题教会我的，恰恰是如何更精确地表达自己的意图，以及如何为自己和团队建立自动化的质量门禁。

所以我的最后建议非常简单：下次你再让 Claude Code 写 Bash 脚本时，先不要急着生成，而是花二十秒想一下“这个脚本将来会在哪些系统上跑”。然后，把那个想象的列表写进 Prompt 里。 这二十秒，可能帮你省下未来数小时的 debug 时间。

如果你愿意，可以从现在就做两件事：

1. 复制本文中的任何一个跨平台检查脚本，放在你的项目根目录里，设为 Git Hook；
2. 把你最常见的系统组合（比如 macOS + Ubuntu）对应的 Prompt 模板存成一个文本快捷指令。

当你开始这样做时，你就不仅仅是 Claude Code 的使用者，你已经是它的技术合伙人，而跨平台问题，将不再是一个问题，而是一个被彻底管理的风险。