Проверка сборки нативного модуля Node.js на облачном Mac с Apple Silicon

То, что нативный модуль Node.js загружается на компьютере разработчика, ещё не означает, что его можно стабильно поставлять для облачного Mac с Apple Silicon. Предварительно скомпилированные файлы из кэша, артефакты сборки, не попавшие в пакет, и неверные пути к динамическим библиотекам могут создать видимость успешного выполнения npm install, но привести к ошибке при первом вызове require() на чистой машине. Надёжная проверка должна объединять пересборку из исходного кода, анализ бинарных файлов, проверку содержимого пакета и установку в изолированной среде.

Сначала зафиксируйте базовую конфигурацию проверки

Перед началом запишите параметры среды выполнения, не очищая сразу кэш и не переустанавливая зависимости. Нативный модуль Node.js может использовать N-API или зависеть от конкретного ABI модулей; границы совместимости у этих механизмов различаются. Основную версию Node.js следует зафиксировать с помощью .nvmrc, .node-version или параметров CI, а версию 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

В среде Apple Silicon команда uname -m должна возвращать 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.

Часто задаваемые вопросы