一个部署脚本在作者的机器上跑了两年没出过问题。新同事接手后第一次执行就失败：脚本里用了 gdate（GNU date），而新同事用的是 macOS 自带的 BSD 版本。改了半行之后又碰到第二处：sed -i 的参数格式两边不同。
Shell 脚本的"可移植性"不是学术问题，而是它在多少种环境下被验证过的问题。而脚本恰恰是最容易只在一种环境下被验证的东西——因为它通常由一个人写、一个人用、在同样的机器上反复跑。
1. 三种可移植性的含义
| 类型 | 含义 | 典型代价 |
|---|---|---|
| 跨操作系统 | Linux / macOS / WSL 都能跑 | 需要抽象出兼容层 |
| 跨发行版 | 不同 Linux 发行版的工具版本不同 | 需要限定版本或做检测 |
| 跨时间 | 同一台机器上工具升级后仍能跑 | 需要避免依赖未定义行为 |
三类之间还有个现实差别：前两类出问题时立刻失败（命令不存在、参数不合法），第三类出问题时照常运行但结果错。所以第三类才是真正危险的那一类——它不会打断流水线，只会让流水线产出错误的东西。
第三类最隐蔽：脚本没有改，工具升级了，行为变了。典型的例子是某个工具的默认输出格式在某次升级后调整，而脚本靠位置取字段。
2. 最常出问题的六个位置
| 位置 | Linux 与 macOS 的差异 | 修法 |
|---|---|---|
date 的时间解析 |
GNU 支持 -d，BSD 用 -j -f |
用脚本内统一的时间函数 |
sed -i |
GNU 允许 -i 后无参数，BSD 必须有后缀 |
sed -i.bak 或改用临时文件 |
grep -P |
BSD grep 不支持 | 改用 -E 或 awk |
readlink -f |
BSD 无此选项 | 用 cd $(dirname ...) && pwd |
stat 格式 |
-c 与 -f 完全不同 |
用 find 或脚本自行处理 |
xargs -r |
BSD 无 -r |
用 `find -print0 |
// 具体差异对照：同一个操作，两边写法不同
date -d '1 day ago' +%F # GNU：昨天
date -v-1d +%F # BSD：昨天（GNU 不支持 -v）
sed -i 's/a/b/' f # GNU：就地修改
sed -i '' 's/a/b/' f # BSD：需要显式给空后缀
sed -i.bak 's/a/b/' f # 两边都可用（GNU 也支持带后缀）
第三行的写法是少数"两边都通用"的方案，它的代价是多一个备份文件，需要清理。
第一项最常踩，因为时间处理在脚本里到处都是。可行做法是定义一个包装函数，把"解析日期"这件事收在一处。
#!/usr/bin/env bash
// 跨平台的日期解析：内部判断是 GNU 还是 BSD
date_parse() {
if date -d '2026-01-01' >/dev/null 2>&1; then
date -d "$1" +"$2" # GNU
else
date -j -f "%Y-%m-%d" "$1" +"$2" # BSD
fi
}
// 调用处统一：date_parse 2026-01-01 %s
3. 解释器本身的差异
#!/bin/sh 指向哪个 shell，决定了可用语法。
| 解释器 | 支持 [[ ]] |
支持数组 | 支持 local |
|---|---|---|---|
sh（dash） |
否 | 否 | 部分 |
bash |
是 | 是 | 是 |
zsh |
是 | 是 | 是 |
busybox sh |
否 | 否 | 部分 |
判断当前解释器有个简单方法，不必猜：
// 打印实际解释器与版本，写进脚本日志
printf 'shell=%s\n' "$(readlink -f /proc/$$/exe 2>/dev/null || ps -p $$ -o comm=)"
printf 'bash=%s\n' "${BASH_VERSION:-n/a}"
// BASH_VERSION 为空 → 当前不是 bash，[[ ]] 与数组都不可用
在 Docker 镜像里这一点尤其重要：Alpine 默认是 busybox 的 sh，不支持 [[ ]] 与数组。脚本在开发机上用 bash 跑通，在容器里就会因为语法错误而失败。
// 明确声明需要 bash，而不是赌基础镜像的默认 shell
FROM alpine:3.20
RUN apk add --no-cache bash
SHELL ["/bin/bash", "-c"]
// 或者：脚本本身写成 POSIX 兼容，用 #!/bin/sh 并避免 bash 特性
4. 让脚本"能判断环境"
比"写得兼容"更实用的策略是先检测、再决定。
// 开头的环境自检：不满足就早失败，而不是中途出错
set -euo pipefail
need() { command -v "$1" >/dev/null 2>&1 || { echo "缺少依赖: $1" >&2; exit 1; }; }
need curl; need jq; need openssl
// 版本门槛：某些工具的能力随版本变化
grep -q 'gnu' <(sed --version 2>/dev/null) || echo "警告: 非 GNU sed，-i 需带后缀" >&2
自检之外还有一条成本很低的纪律：脚本开头打印环境指纹（os、shell、关键工具版本）。故障复现时这是唯一能确认"两边环境是否真的相同"的证据，否则只能靠对话猜。
set -euo pipefail 这三项是脚本可靠性的基础，但它们在 sh 下并不总是可用（pipefail 尤甚）。所以第一行必须是 #!/usr/bin/env bash，而不是 #!/bin/sh。
5. 什么时候该放弃可移植性
| 场景 | 建议 |
|---|---|
| 脚本只在 CI 容器里跑 | 放弃跨平台，锁定镜像版本 |
| 团队全是 macOS | 放弃 Linux 差异，但检查 BSD 工具 |
| 脚本要交给用户执行 | 必须兼容，或改用编译语言 |
| 一次性迁移脚本 | 不做兼容，写清运行环境 |
还有一个更实际的判断维度：这个脚本会不会被用户的机器执行。一旦要分发出去（而不是只在自己的服务器上跑），可移植性就从"优化项"变成"正确性要求"——因为失败发生在别人那里，你既看不到也修不及时。
第二项有个反直觉的结论：只支持一种环境不等于不需要可移植性，因为"一种环境"也会升级。锁住版本比兼容多版本更容易，也更可靠。
// 把脚本的运行环境固定下来，比让脚本兼容所有环境便宜
script_runtime:
image: ubuntu:24.04
tools: [bash, curl, jq, coreutils]
// 所有脚本都在这个镜像里执行，本地与 CI 一致
6. 排错：五种"我这儿能跑"
| 现象 | 成因 | 处理方向 |
|---|---|---|
command not found |
依赖未装在目标环境 | 开头自检依赖 |
date: illegal option |
用了 GNU 特有参数 | 统一到兼容函数 |
sed: -i may not be followed by |
BSD sed 语法差异 | 带后缀或改临时文件 |
语法错误指向 [[ |
解释器是 dash/busybox | 改 #!/usr/bin/env bash |
| 输出解析错位 | 工具版本升级改了输出格式 | 改用结构化输出（--format=json） |
这些排错方向可以压成一个检查顺序：
// 脚本"我这儿能跑"的五步排查
1. 解释器是不是 bash（BASH_VERSION 非空？）
2. 依赖是否齐全（command -v 逐个检查）
3. 是否用了 GNU 特有参数（date -d / sed -i / grep -P / readlink -f）
4. 是否按位置解析了工具输出（应改 --format=json）
5. 路径是否依赖工作目录（应用绝对路径或脚本所在目录）
第五项值得展开：用 awk 按位置取字段是最脆弱的一类写法。工具输出加一列，所有下游解析全错，而且不报错、只是取到错的值。改成 --format=json 或 --porcelain 这类稳定接口，虽然多一步解析，但抗升级。
7. 边界：什么情况不必考虑可移植
| 场景 | 为什么 | 做法 |
|---|---|---|
| 只在自己机器上的一次性脚本 | 无分发需求 | 随便写 |
| 已固定在容器镜像里的脚本 | 环境完全可控 | 锁镜像版本即可 |
| 只有几行的胶水命令 | 依赖面小 | 不必抽象 |
| 会被替换成正式工具的临时脚本 | 生命周期短 | 不做投入 |
还有一条与团队协作有关的判断：脚本由谁维护。一个人维护的脚本，兼容性靠他的记忆；多人维护的脚本，必须把兼容性写进代码（自检、包装函数、显式解释器声明），否则每次交接都会重新踩一遍同样的坑。
判断口径一句话：这个脚本会被几个不同环境执行。一个（且可控），不必兼容；超过一个，先自检依赖，再谈兼容。
8. 自测
- 三种可移植性分别是什么？哪一类最隐蔽，为什么？
sed -i在 GNU 与 BSD 上的差异是什么？两种修法各有什么代价？- 为什么在 Alpine 镜像里跑 bash 脚本容易失败？三种应对方式是什么？
set -euo pipefail为什么要求#!/usr/bin/env bash而不是#!/bin/sh？- "只支持一种环境"为什么也需要考虑可移植性？锁定版本与兼容多版本哪个更便宜？
- 用 awk 按位置解析工具输出，为什么是最脆弱的写法？替代方案抗的是什么变化？