npm v12: критические изменения
и подготовка к миграции

Три ключевых изменения

9 июня 2026 года GitHub Changelog подтвердил финальный набор изменений, которые войдут в npm v12. Они доступны с предупреждениями начиная с npm 11.10.0, но v12 включит их по умолчанию:

Все три изменения можно протестировать прямо сейчас в npm 11.10.0+. Предупреждения покажут, какие пакеты затронуты в вашем проекте.

Почему эти изменения именно сейчас?

Install-скрипты стали основным вектором атак на цепочку поставок npm. Червь Mini Shai-Hulud (май 2026) скомпрометировал более 170 пакетов, внедряя вредоносный код через preinstall-хуки. Другие менеджеры пакетов — pnpm, Yarn, Bun, Deno — либо блокируют install-скрипты по умолчанию, либо требуют явного разрешения. npm оставался единственным, кто этого не делал.

Изменения allow-remote и allow-git закрывают дополнительные векторы. Уязвимость Git-зависимостей была особенно опасна: скомпрометированный .npmrc Git-зависимости давал атакующему контроль над процессом установки даже при отключённых скриптах.

Подробнее об атаках, которые привели к этим изменениям, читайте в моих статьях: анализ RFC по install-скриптам и разбор атаки Mini Shai-Hulud.

Пошаговая миграция

Шаг 1: Обновите npm

Обновитесь до npm 11.16.0+, чтобы включить все предупреждения:

# Обновление до последней версии npm 11
npm install -g npm@11

# Проверка версии
npm --version
# Должно быть 11.16.0 или выше

# Установка с предупреждениями
npm install --install-strategy=manual

Шаг 2: Найдите все пакеты с install-скриптами

Выполните запрос для поиска зависимостей с install-скриптами:

# Список всех пакетов со скриптами
npm query .scripts

# Сокращённый список только имён пакетов
npm query .scripts | jq '.[].name'

# Проверка с предупреждениями (npm 11.16+)
npm install --install-strategy=manual
# Предупреждения покажут:
# "package X has 1 script(s) that will not run in v12"

Типичные пакеты, которые вызывают предупреждения:

• node-gyp и нативные аддоны (node-sass, sharp, bcrypt) — компилируют код во время установки
• esbuild — загружает платформо-зависимые бинарники
• SWC / @swc/core — загружает нативные бинарники
• Puppeteer / Playwright — загружает бинарники браузеров
• TypeScript — иногда использует postinstall для патчей типов

Шаг 3: Проверьте и одобрите доверенные пакеты

npm 11.16+ вводит две новые команды для управления allowlist'ом скриптов:

# Одобрить скрипты конкретного пакета
npx npm-approve-scripts --allow esbuild

# Одобрить несколько пакетов
npx npm-approve-scripts --allow esbuild,sharp,@swc/core

# Заблокировать пакет
npx npm-approve-scripts --deny untrusted-package

# Просмотр текущих разрешений
npx npm-approve-scripts list

# Одобрить все установленные пакеты (не рекомендуется)
npx npm-approve-scripts --allow-all

Шаг 4: Сохраните allowlist в репозиторий

Список одобренных скриптов сохраняется в package.json через новое поле, что делает его воспроизводимым:

{
  "name": "my-project",
  "approvedScripts": {
    "approve": [
      "[email protected].*",
      "[email protected].*",
      "@swc/core@1.*"
    ],
    "deny": []
  }
}

Версионные диапазоны следуют semver. Указывайте конкретные диапазоны — [email protected].* безопаснее, чем esbuild@*.

Шаг 5: Протестируйте с поведением npm v12

До выхода v12 проверьте ваш пайплайн с будущими настройками по умолчанию:

# Симуляция поведения v12 на npm 11
npm install --install-strategy=manual --allow-remote=none --allow-git=none

# Если всё работает — вы готовы к v12
# Если ошибки — проверьте и одобрите затронутые пакеты

Полный чеклист по безопасной оценке npm-пакетов — в статье Как оценить npm-пакет: практический чеклист.

Миграция CI/CD пайплайнов

CI-окружения требуют особого внимания, так как они часто выполняют чистую установку и полагаются на postinstall-хуки:

# GitHub Actions — готовимся к npm v12
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: |
          npm ci
      
      - name: Build
        run: npm run build

Ключевые моменты для CI:

• Сохраните поле approvedScripts в репозитории — CI читает его автоматически
• Для монорепозиториев каждому workspace может понадобиться свой allowlist
• Протестируйте CI с --install-strategy=manual --allow-remote=none --allow-git=none до выхода v12
• Сборка нативных аддонов (node-gyp) не будет работать без одобрения — переходите на prebuild где возможно

Авторам пакетов: что делать

Если вы поддерживаете npm-пакет с install-скриптами, вот как подготовиться:

Вариант 1: Переход на lifecycle-хуки

Перенесите логику установки в скрипты, которые не запускаются при npm install:

{
  "scripts": {
    "postinstall": "node ./setup.mjs",       // Не запустится в v12
    "prepare": "node ./build.mjs",             // Запускается при 'npm publish'
    "prepublishOnly": "npm run build",         // Запускается перед публикацией
    "rebuild": "node-gyp rebuild"              // Явный, не автоматический
  }
}

Вариант 2: Предварительно собранные бинарники

Вместо компиляции кода во время установки поставляйте готовые бинарники для основных платформ. Хорошие примеры: esbuild (бинарники под GOOS/GOARCH) и sharp (через prebuild-install).

Монорепозитории

Монорепозитории с npm workspaces сталкиваются с дополнительной сложностью — каждый workspace может иметь свои требования к скриптам:

# Корневой package.json
{
  "workspaces": ["packages/*"],
  "approvedScripts": {
    "approve": [
      "[email protected].*",
      "typescript@5.*"
    ]
  }
}

# approvedScripts из workspace'ов мерджится с корневыми.
# Для проверки всех скриптов:
npm query .scripts --workspaces

Флаги allow-remote и allow-git

Помимо install-скриптов, важно понимать изменения allow-remote и allow-git:

# Разрешить все удалённые тарболы (возврат к текущему поведению)
npm install --allow-remote=all

# Разрешить все Git-зависимости (возврат к текущему поведению)
npm install --allow-git=all

# Эквиваленты в .npmrc
echo 'allow-remote=all' >> .npmrc
echo 'allow-git=all' >> .npmrc

Эти флаги принимают all (разрешить всё) или none (блокировать всё). Будущие версии могут поддерживать детальные allowlist'ы. Пока что протестируйте проект с обоими флагами в none и посмотрите, что сломается.

FAQ

Что дальше

Время на подготовку к npm v12 ограничено. Каждый проект, использующий npm, будет затронут. Хорошая новость: вы можете подготовиться уже сегодня — обновитесь до npm 11.16.0+, выполните команды аудита выше и настройте allowlist до официального релиза.

Начните с npm query .scripts — это занимает пять секунд и показывает объём предстоящей работы. Для большинства проектов миграция занимает 15-30 минут. Альтернатива — сломанный CI в июле.

Создаёте новый Node.js проект? Я помогаю командам настраивать безопасную JavaScript-архитектуру. Свяжитесь со мной для консультации.