云端 Mac CI 元数据清理与交付门禁实战

云端 Mac 上的构建已经通过，压缩包也能解开，但接收方仍可能看到 ._Config.json、.DS_Store，或在上传环节遇到来源不明的扩展属性。问题通常不在编译器，而在 Finder 操作、跨文件系统复制和归档工具对 macOS 元数据的处理差异。解决方法不是对工作区执行一次粗暴清理，而是把交付过程拆成可审计的暂存、扫描、归档和复验四步。

先定义什么可以进入交付包

macOS 文件除了名称和内容，还可能携带扩展属性、资源分支和 Finder 元数据。它们在本机文件系统里不一定有问题，进入 ZIP、共享盘或对象存储后却可能变成 AppleDouble 旁车文件。

先为产物定义规则，而不是边打包边删除：

清理对象应是独立暂存目录，不是源码工作区。这样即使策略写错，也不会修改缓存、依赖目录或下一次构建需要的输入。

如果交付物包含已签名应用，先对原始产物验签。普通文档、配置和日志可以采用更严格的元数据拒绝策略，两类对象不要共用一条递归删除命令。

建立一次性暂存目录

暂存目录必须由当前任务独占，并在退出时清理。不要复用固定的 /tmp/release，并行任务可能互相覆盖。

#!/bin/bash
set -euo pipefail

SOURCE="${1:?source path required}"
OUTPUT="${2:?output path required}"
STAGE="$(mktemp -d "${TMPDIR:-/tmp}/bamini-artifact.XXXXXX")"
UNPACK="$(mktemp -d "${TMPDIR:-/tmp}/bamini-unpack.XXXXXX")"

cleanup() {
  rm -rf "$STAGE" "$UNPACK"
}
trap cleanup EXIT

/usr/bin/ditto --norsrc "$SOURCE" "$STAGE/payload"
find "$STAGE/payload" -type f -name '.DS_Store' -delete
find "$STAGE/payload" -type f -name '._*' -delete

mktemp 让每次任务获得不同目录，trap 则覆盖成功、失败和中断路径。这里用 ditto --norsrc 复制内容，避免主动携带资源分支，但仍保留后续扫描，因为输入目录可能本来就含有实体化的 ._ 文件。

如果工作流需要交付完整应用包，应先验证复制策略能保留该应用要求的内容。更稳妥的做法是把应用包与普通附件分开暂存，分别执行策略。

扫描扩展属性而不是全部抹掉

xattr -cr 很方便，也过于宽泛。它既删除已知的隔离属性，也删除尚未纳入检查规则的其他属性。流水线因此“变绿”，但根因被隐藏。

可以先输出属性名，再让明确禁止的项目阻断任务：

ATTR_REPORT="$STAGE/xattr.txt"

if /usr/bin/xattr -lr "$STAGE/payload" >"$ATTR_REPORT" 2>&1; then
  if grep -E 'com\.apple\.(quarantine|ResourceFork)' "$ATTR_REPORT"; then
    echo "disallowed macOS metadata found" >&2
    exit 41
  fi
fi

if find "$STAGE/payload" -type f \( -name '.DS_Store' -o -name '._*' \) -print -quit |
  grep -q .; then
  echo "hidden metadata files found" >&2
  exit 42
fi

这条门禁选择“发现即失败”，适合先定位元数据由哪个步骤引入。确认来源后，再在下载、复制或生成环节定向修复。若业务确实允许某个扩展属性，应把文件范围和属性名写进允许列表，而不是放过整个目录。

记录来源步骤

在源码检出后、编译后、暂存后各扫描一次。第一次出现异常的阶段就是排查边界。常见来源包括图形界面浏览目录、从非原生文件系统复制，以及工具先下载再解包。只在最终归档前扫描，虽然能拦住污染，却无法指出责任步骤。

归档后必须重新打开检查

暂存目录干净，不代表归档工具不会重新写入元数据。生成 ZIP 后应检查成员名，再解包到新目录复验。

rm -f "$OUTPUT"
/usr/bin/ditto -c -k --norsrc --keepParent \
  "$STAGE/payload" "$OUTPUT"

/usr/bin/unzip -Z1 "$OUTPUT" >"$STAGE/members.txt"

if grep -E '(^|/)\.DS_Store$|(^|/)\._[^/]+$' "$STAGE/members.txt"; then
  echo "archive contains forbidden metadata files" >&2
  exit 43
fi

/usr/bin/ditto -x -k "$OUTPUT" "$UNPACK"

if find "$UNPACK" -type f \( -name '.DS_Store' -o -name '._*' \) -print -quit |
  grep -q .; then
  echo "extracted artifact failed metadata check" >&2
  exit 44
fi

成员列表检查速度快，适合作为第一道门；解包复验则覆盖路径转换和解压行为。两者都应执行，因为上传系统真正接收的是归档文件，而使用者最终操作的是解包结果。

若包内含已签名应用，找到解包后的 .app，再运行严格验签。不要只验证打包前的副本，否则归档参数造成的改变无法被发现。

把门禁接入可重复交付流程

建议把脚本固定为“输入目录、输出文件”两个参数，并让每次任务生成以下证据：

1. 暂存前的产物路径与类型。
2. 扩展属性扫描结果。
3. ZIP 成员列表。
4. 解包后的隐藏文件检查结果。
5. 应用包存在时的二次验签结果。
6. 最终归档的 SHA-256 摘要。

摘要可用 shasum -a 256 artifact.zip 生成。它不能证明两个 ZIP 的内容语义完全一致，却能确认上传、下载和交接过程中没有发生字节变化。

在 BAMini 的云端 Mac 上运行这类任务时，先在控制台确认当前可选配置，再把脚本放进仓库并由 CI 调用，不要依赖某位成员记得手工清理。门禁失败后保留成员列表和属性报告，删除包含项目内容的临时目录；下一次任务必须创建新暂存目录，避免上次残留影响判断。

最终目标不是让所有扩展属性消失，而是让交付包只包含团队明确批准的内容。暂存隔离负责控制修改范围，分阶段扫描负责定位来源，解包复验负责验证真实交付结果。三者同时存在，隐藏元数据才不会在不同复制路径中反复出现。

常见问题