2026: сборка фронтенда на удалённом Mac —
нативные модули esbuild и SWC, optionalDependencies и матрица решений для CI

Нативный слой не проявляется в TypeScript-ошибках: он ломается при первом вызове трансформера или бандлера. Используйте таблицу как быстрый триаж перед долгим дебагом сети или кода приложения.

Паритет — это не «одинаковый package.json», а совпадение набора: бинарная архитектура Node, политика Rosetta, версия macOS для загрузчиком и набор нативных зависимостей, выбранных через optionalDependencies.

Зафиксируйте в README эталон окружения и короткий assert в preinstall — агент падает сразу с диагностикой, а не на 15-й минуте сборки.

Выполняйте на том же раннере, где падает пайплайн. Не копируйте node_modules между хостами с разной ОС.

1. Диагностика среды:

node -p "process.version + ' ' + process.arch + ' ' + process.platform"
which node
xcodebuild -version 2>/dev/null | head -n 1

2. Полная переустановка зависимостей (npm):

rm -rf node_modules
npm cache verify
npm ci

3. Точечная пересборка нативных модулей без полного rm (если менялся только toolchain):

npm rebuild esbuild
npm rebuild @swc/core --verbose

4. pnpm (монорепо):

pnpm store prune
rm -rf node_modules **/node_modules
pnpm install --frozen-lockfile

5. Проверка, какой бинарник реально грузится:

node -e "console.log(require('esbuild').execPath)"
find node_modules -name '*.node' -path '*esbuild*' | head

Кэш CI должен включать всё, что влияет на выбор optional-пакета: версия Node, архитектура, хэш lock-файла, идентификатор образа macOS. Иначе вы восстановите «чужой» node_modules и получите дрейф, который локально невоспроизводим.

• GitHub Actions пример ключа: node-${{ hashFiles('**/pnpm-lock.yaml') }}-${{ runner.os }}-${{ runner.arch }}
• Turbo remote cache: отдельный префикс для веток с экспериментальным Node 22 vs LTS 20, чтобы не смешивать артефакты.
• Очистка: при смене пула раннеров инвалидируйте кэш установки целиком один раз; дальше держите тёплый кэш по стабильному ключу.
• Антипаттерн: таскать tarball node_modules с ноутбука на сервер через rsync — ломает optional-маршрутизацию.

Для монорепозиториев согласуйте политику с гайдом по pnpm и зеркалу: одна точка правды для store снижает число «призрачных» платформенных пакетов.

1. Один тип раннера на workflow: не смешивайте в одном job-кэше arm и x64 даже при одинаковой версии Node.
2. Лимит параллелизма установки: при восьми одновременных npm ci на общем диске включите очередь или разнесите по volume, чтобы postinstall не умирал по таймауту.
3. После restore кэша: node -e "require('esbuild')" и импорт @swc/core в одном шаге job.
4. Метрики: фиксируйте медиану времени install и cold build; всплеск на 40%+ после смены образа — сигнал проверить нативный слой, а не только прикладной diff.
5. Документация: приложите к runbook ссылку на эту матрицу и эталонную команду диагностики — сокращает эскалации на DevOps.