同一条 stat 命令放进 macOS 和 Linux 脚本，最容易露馅的地方是格式参数。macOS 自带版本能处理 -f，GNU 版本常见的是 -c；把后者原样交给 macOS，解析阶段就会报选项错误，文件是否存在还没机会影响结果。选项只差一个字母，含义却不能靠猜。
临时文件上的两次调用
验证脚本用 Python 的 TemporaryDirectory 建一个独立目录，写入 18 字节，再把该文件路径作为参数传给系统 /usr/bin/stat。临时目录退出时会自动清除，不碰仓库里的文件，也不改系统状态。测试环境是 macOS 26.2，内核报告 Darwin 25.2.0，架构 arm64。
BSD 这一侧的格式写法是 -f，格式字符串里的 %N 输出路径，%z 是字节数，%m 是修改时间的 Unix 时间戳。结果中的文件名来自本次临时目录，因此路径每次运行都会不同；18 与测试文件内容长度相符。
$ /usr/bin/stat -f %N %z %m /var/folders/vz/zf2_sm250pgd4qb_p847p1240000gn/T/stat-format-check-hkosa_gr/sample.txt
exit: 0
stdout: /var/folders/vz/zf2_sm250pgd4qb_p847p1240000gn/T/stat-format-check-hkosa_gr/sample.txt 18 1792801892
这台机器上的调用成功，说明此处的 -f 是 BSD stat 的格式串入口。它不能简单改成 GNU 写法再期待行为相同。
GNU 风格为什么失败
GNU coreutils 的 stat 用 -c 或 --format 指定格式串，常见占位符是 %n 文件名、%s 字节数和 %Y 修改时间戳。macOS 的 /usr/bin/stat 对 -c 返回 illegal option -- c；长选项 --format 也被拒绝。实测输出附在 tools/verify-stat-format-macos.log，原样记录了退出码和标准错误。
$ /usr/bin/stat -c %n %s %Y /var/folders/vz/zf2_sm250pgd4qb_p847p1240000gn/T/stat-format-check-hkosa_gr/sample.txt
exit: 1
stderr: /usr/bin/stat: illegal option -- c
usage: stat [-FLnq] [-f format | -l | -r | -s | -x] [-t timefmt] [file ...]
名字叫 stat 不代表接口统一。macOS 随系统提供的是 BSD 系实现，Linux 上经常调用的是 GNU coreutils 实现。它们都能查询文件元数据，命令行接口却没有统一标准，选项和占位符不能按字面互换。BSD 的 %z 与 GNU 的 %s 都能表达字节大小，也不能因此假设整个格式串兼容。
GNU 侧的 -f 更容易让人误判。GNU stat 把它用于文件系统状态信息，并非普通文件状态的格式串入口。BSD 的 -f 则正好是格式参数。跨平台脚本若只按参数名做替换，容易把命令语义一起换错。
脚本按平台分支
只需读取大小时，可以避开格式字符串，先明确调用对象在各平台上的选项差异，再为各自写分支。若脚本还读取时间戳、路径或权限位，就应逐个核对占位符和单位。格式字符串相同并不保证语义相同，时间格式尤其容易混淆时间单位与显示方式。
我会把平台差异放进一个小函数，而不是在多个脚本里复制一条「看起来通用」的命令。入口越集中，遇到 BSD、GNU 或 BusyBox 的差别越容易处理。另一种办法是依赖 Python、Ruby 等跨平台接口读取文件元数据，适合原本就用这些运行时的脚本；单为 stat 引入运行时则未必划算。
还应留意调用到的是哪一个可执行文件。机器上可能另装了 GNU coreutils，并通过 PATH 把它放在系统工具之前。此时仅凭操作系统名称推断 stat 行为会失准，查看解析到的路径比猜测可靠。部署脚本若要求特定实现，可以明确选择工具路径，或在启动时做一次能力检查，再决定使用哪个参数格式。
测试样例最好覆盖路径中含空格的情况，因为格式串中的文件名输出也会进入后续解析环节。若命令结果要交给另一段脚本处理，不能默认以空格切分就安全。对元数据结果做断言时，把目标文件长度或固定时间戳提前设定，结果会更稳定，也更容易发现占位符误用。
脚本验证的是当前 macOS 自带的 /usr/bin/stat，并未在本机运行 GNU coreutils，因此 GNU 格式说明描述的是 GNU 接口，不是假称在这台机器上测过。需要兼容多种 Unix 环境时，测试矩阵应分别覆盖 macOS 的 BSD 实现与目标 Linux 发行版上的 GNU 实现。临时文件探测可以确认选项能否解析，但不能代替对不同占位符含义和输出单位的逐项验证。
