在云端 Mac 上验收 Node.js 原生模块的 Apple Silicon 构建

一个 Node.js 原生模块在开发机上能加载，不等于它能在 Apple Silicon 的云端 Mac 上稳定交付。缓存中的预编译文件、未进入发布包的构建产物、错误的动态库路径，都可能让 npm install 看似成功，却在干净机器上首次 require() 时失败。更可靠的做法，是把源码重建、二进制检查、打包检查和隔离安装连成一条验收链。

先固定验收基线

开始前先记录运行环境，不要直接清缓存重装。Node.js 原生模块可能使用 N-API，也可能依赖特定模块 ABI；两者的兼容边界不同。项目应通过 .nvmrc、.node-version 或 CI 参数固定 Node.js 主版本，并把 npm 版本一并写入日志。

uname -m
sw_vers
node --version
npm --version
node -p "process.versions.napi || 'no-napi'"
node -p "process.versions.modules"
xcode-select -p
clang --version

uname -m 在 Apple Silicon 环境应返回 arm64。如果终端进程本身运行在其他架构下，后续构建结果就不能代表目标环境。还要检查 xcode-select -p 指向预期工具链，避免命令行工具在系统更新后悄悄切换。

验收的对象不是“当前目录能不能运行”，而是“从仓库源码能否生成符合目标架构、可被最终发布包加载的产物”。

在干净工作区强制源码重建

不要在长期使用的工作目录里做发布验收。先检出确定的提交，再清除依赖目录和模块自己的构建目录。若项目依赖安装脚本生成 .node 文件，必须保留完整安装日志。

git status --short
git rev-parse HEAD
rm -rf node_modules build
npm cache verify
npm ci
npm rebuild --build-from-source

npm cache verify 只检查缓存结构，不会证明构建没有使用缓存，因此关键动作仍是 --build-from-source。项目若有明确的构建脚本，应再执行 npm run build，而不是假设 npm rebuild 覆盖所有生成步骤。

失败时先保留完整输出，再核对 Python、编译器、SDK 路径和头文件。不要一遇到错误就删除所有缓存；无差别清理会破坏现场，也无法判断问题来自工具链、源码还是安装脚本。

区分 N-API 与模块 ABI

使用 N-API 的模块应记录声明的最低 N-API 版本，并在目标 Node.js 版本上执行加载测试。直接依赖模块 ABI 的扩展通常需要针对不同 Node.js 主版本分别构建，不能把某个版本生成的二进制复制到另一版本继续使用。

检查 Mach-O 架构与动态依赖

构建结束后，先找出所有原生二进制，不要只检查约定路径中的第一份文件。

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  xargs -0 file

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  while IFS= read -r -d '' binary; do
    echo "== $binary"
    lipo -info "$binary"
    otool -L "$binary"
  done

目标为 Apple Silicon 时，每个交付用 .node 文件都应包含 arm64。只有发布范围明确覆盖两种架构时，才需要生成通用二进制；不要为了形式合并两个未经同等测试的切片。

otool -L 的重点是发现开发机绝对路径、临时目录和未随包交付的自定义动态库。系统框架路径通常可以保留，但指向个人目录或构建工作区的引用必须在发布前修正。若模块附带 .dylib，还要确认它确实进入打包清单，并使用可迁移的加载路径。

验收真正要发布的 npm 包

直接在源码目录运行测试，会让未声明文件、相对路径和残留产物参与加载。发布前应先生成 tarball，再到空目录安装它。

rm -rf .package-check
mkdir .package-check

npm pack --json > .package-check/pack.json
PACKAGE_FILE="$(node -e "
const fs=require('fs');
const data=JSON.parse(fs.readFileSync('.package-check/pack.json','utf8'));
process.stdout.write(data[0].filename);
")"

tar -tzf "$PACKAGE_FILE"
cd .package-check
npm init -y >/dev/null
npm install "../$PACKAGE_FILE"
node -e "const addon=require('your-module'); console.log(typeof addon)"

把 your-module 换成实际包名，并将最后一行扩展为最小业务调用。冒烟测试至少要触发一次原生函数，而不是只验证 JavaScript 入口文件存在。若模块提供同步与异步接口，应各运行一次，并检查进程退出码。

同时审查 tar -tzf 的输出：许可证、类型声明、JavaScript 入口、目标 .node 文件和必要动态库应存在；源码缓存、测试凭据、临时日志及本地配置不应进入包内。

把常见故障变成发布门禁

建议把验收拆成互相独立的失败条件，避免一个宽泛的“构建失败”掩盖根因：

1. 环境门禁：机器架构、Node.js、npm、N-API 或 ABI 与声明不一致时停止。
2. 重建门禁：删除现有产物后，源码构建必须成功且生成新的 .node 文件。
3. 架构门禁：每个交付二进制必须含目标 arm64 切片。
4. 依赖门禁：不得引用工作区、个人目录或未打包动态库。
5. 包内容门禁：以 npm pack 结果为准，不以源码目录为准。
6. 运行门禁：在隔离目录安装 tarball，并执行至少一个原生 API 调用。

在 DPLYMAC 上执行这套流程时，可把每次任务的环境清单、提交哈希、tarball 校验值和冒烟测试输出作为同一份构建证据保存。这样即使后续升级 Node.js 或编译工具，也能判断差异发生在环境、编译阶段、封装阶段还是运行阶段。

最终交付标准应当很简单：干净检出可以重建，二进制架构正确，动态依赖可迁移，发布包内容完整，并且该发布包能在隔离环境中完成真实调用。满足这五点，才算原生模块通过 Apple Silicon 验收。

常见问题