Как Проверить Версию Webpack: Терминал, package.json и Конфиг

Пять мажорных версий webpack не являются взаимозаменяемыми. Каждый мажорный релиз вносил критические изменения в синтаксис конфигурации, совместимость лоадеров и API плагинов. Конфиг webpack 4 не будет работать с webpack 5 без модификаций, а лоадеры, выпущенные для webpack 3, могут молча давать сбой или выдавать неверный результат в webpack 4+.

Помимо совместимости конфигурации, версия webpack влияет на производительность. Webpack 5 представил персистентное кэширование, Module Federation и улучшенное tree-shaking, которые могут значительно сократить время сборки и размеры бандлов по сравнению с webpack 4. Если вы отлаживаете медленную сборку или расследуете регрессию размера бандла, подтверждение версии — первый диагностический шаг.

Когда конфликты версий вызывают ошибки

• Несовместимость лоадеров - `babel-loader` v8 нацелен на webpack 4; использование его с webpack 5 без обновления приводит к молчаливой неправильной настройке.
• Несовпадения API плагинов - плагины, встраивающиеся в компилятор webpack, используют API, изменившееся между v4 и v5. Плагин, собранный под v4, упадёт на объекте компилятора v5.
• Конфликты peer-зависимостей - инструменты вроде `webpack-dev-server`, `html-webpack-plugin` и `mini-css-extract-plugin` публикуют версии, привязанные к конкретным мажорным версиям webpack.
• Ошибки схемы css-loader - css-loader v5 и v6 имеют строгую валидацию схемы; несовпадение версии с webpack порождает ошибку «ValidationError: Invalid options object».

Терминал — самый быстрый и надёжный способ проверить вашу версию webpack. Есть три команды, которые стоит знать, каждая подходит для чуть иной ситуации.

Webpack устанавливается локально в ваш проект как devDependency. Глобально установленная версия, если она есть, почти никогда не является той, которую сборка использует на самом деле.

Локальная версия проекта (самая надёжная)

Ваш проект почти наверняка устанавливает webpack как локальную devDependency, а не глобальный пакет. Чтобы проверить версию, которую ваши скрипты сборки используют на самом деле, выполните `npx` или `./node_modules/.bin/webpack` прямо из корня проекта. Эти команды обходят любую глобальную установку webpack и сообщают локально установленную версию.

# Самый надёжный способ - использует локальную установку node_modules
npx webpack --version

# Альтернативный вызов по пути
./node_modules/.bin/webpack --version

# С yarn
yarn webpack --version

# Pnpm
pnpm exec webpack --version

Команда npm list

`npm list webpack` запрашивает ваши локальные `node_modules` и выводит установленную версию вместе с её положением в дереве зависимостей. Это полезно, когда вы хотите увидеть не только версию, но и какой пакет требовал webpack как peer-зависимость — частый источник конфликтов версий, когда инструмент сборки зависит от конкретного диапазона webpack.

# Показать версию webpack в локальных node_modules
npm list webpack

# Показать все пакеты в дереве, зависящие от webpack
npm list webpack --all

# Эквивалент в yarn
yarn list --pattern webpack

# Эквивалент в pnpm
pnpm list webpack

Глобально установленная версия

Если вы установили webpack глобально через `npm install -g webpack webpack-cli`, вы можете проверить эту версию отдельно. Имейте в виду: глобальная версия редко бывает той, что используют сборки вашего проекта — большинство скриптов сборки вызывают webpack через скрипты `package.json`, которые всегда разрешаются в локальную установку.

# Проверка глобальной установки
webpack --version

# Или явно из глобального пути
npm list -g webpack

Файл `package.json` вашего проекта перечисляет диапазон версий webpack, который проект объявил как зависимость. Это не то же самое, что установленная версия — это диапазон, указанный при добавлении webpack, и фактически установленная версия может быть любой версией внутри этого диапазона.

{
  "devDependencies": {
    "webpack": "^5.88.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^4.15.1"
  }
}

# В package-lock.json (npm)
grep '"webpack"' package-lock.json | head -5

# В yarn.lock
grep 'webpack@' yarn.lock | head -5

# В pnpm-lock.yaml
grep 'webpack' pnpm-lock.yaml | head -10

Иногда нужно знать версию webpack во время сборки — например, чтобы применить другую ветку конфигурации в зависимости от мажорной версии или логировать диагностическую информацию в CI-пайплайне. Webpack exposes версию как свойство объекта компилятора, а сам пакет webpack экспортирует строку `version`.

Чтение версии в webpack.config.js

const webpack = require('webpack');

// Строка версии доступна напрямую
console.log('Webpack version:', webpack.version);

// Используйте её для условного применения конфигурации
const isWebpack5 = parseInt(webpack.version, 10) >= 5;

module.exports = {
  // ...
  plugins: [
    isWebpack5
      ? new webpack.ids.DeterministicModuleIdsPlugin()
      : new webpack.HashedModuleIdsPlugin(),
  ],
};

Чтение версии в собственном плагине или лоадере

Внутри плагина webpack объект компилятора несёт версию webpack через `compiler.webpack.version`. Это самая безопасная программная проверка, потому что она читает версию того экземпляра webpack, который вызвал плагин, — а не той, что случайно оказалась в `node_modules`.

class MyPlugin {
  apply(compiler) {
    // compiler.webpack доступен в webpack 5+
    const version = compiler.webpack?.version ?? webpack.version;
    console.log('Running on webpack', version);

    compiler.hooks.done.tap('MyPlugin', (stats) => {
      // Build complete
    });
  }
}

Проверка версии в CI-окружении

В CI-пайплайне самый чистый способ логировать версию webpack — добавить шаг, выполняющий `npx webpack --version` и захватывающий вывод. Это даёт локально установленную версию из тех самых `node_modules`, которые будет использовать сборка, и она появляется в журнале пайплайна при каждом запуске — полезно для отладки сбоев сборки, проявляющихся только на отдельных runner.

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm ci
  - name: Log webpack version
    run: npx webpack --version
  - name: Build
    run: npm run build

Понимание различий между мажорными версиями webpack помогает решить, подходит ли ваша текущая версия проекту и чего ожидать при миграции. Вот краткое сравнение возможностей и ландшафта совместимости всех пяти мажорных релизов.

Webpack 4 против webpack 5 - ключевые отличия

• Персистентный кэш - webpack 5 кэширует результаты компиляции на диск между запусками; тёплый кэш может сделать пересборки в 5-10 раз быстрее, чем webpack 4.
• Module Federation - webpack 5 представил Module Federation для совместного использования кода между независимо развёрнутыми фронтендами в рантайме.
• Asset-модули - webpack 5 заменяет `file-loader`, `url-loader` и `raw-loader` встроенными типами asset-модулей (`asset/resource`, `asset/inline` и т.д.).
• Полифиллы Node.js удалены - webpack 5 больше не добавляет полифиллы для модулей ядра Node.js автоматически. Проекты, зависевшие от полифиллов для `buffer`, `path`, `stream` и т.д., должны добавить их явно.
• Долгосрочное кэширование - webpack 5 по умолчанию использует детерминированные ID чанков, создавая стабильные имена файлов между сборками, что повышает частоту попаданий в кэш браузера.

Конфликты версий между webpack и его экосистемой — самая частая причина запутанных ошибок сборки. Большинство этих ошибок сводится к одной из трёх причин: несколько копий webpack в `node_modules`, лоадер или плагин, собранный под другую мажорную версию, либо несовпадение диапазона peer-зависимости.

Несколько копий webpack в node_modules

Возможно — и, что удивительно, часто встречается, — иметь более одной копии webpack, установленной в вашем проекте. Это происходит, когда зависимость объявляет peer-зависимость от webpack с другим диапазоном мажорной версии, чем использует ваш проект. Результат — два несовместимых экземпляра webpack, из-за чего плагины молча дают сбой или падают, потому что зарегистрированы в одном экземпляре, а вызываются другим.

# Проверить несколько записей webpack в полном дереве зависимостей
npm list webpack --all

# Ищите более одного уникального номера версии в выводе
# например, одновременное появление [email protected] и [email protected]
# - признак конфликтующих peer-зависимостей

Разрешение конфликтов peer-зависимостей

Когда `npm list webpack --all` показывает несколько версий webpack, посмотрите, какой пакет подтягивает старую версию. Обновите этот пакет до версии, поддерживающей вашу мажорную версию webpack, либо используйте поле `resolutions` (Yarn) или `overrides` (npm 8+), чтобы принудительно использовать одну версию webpack всеми пакетами.

{
  "overrides": {
    "webpack": "^5.88.0"
  }
}

{
  "resolutions": {
    "webpack": "^5.88.0"
  }
}

Валидация semver-диапазонов

Диапазоны peer-зависимостей вроде `"webpack": "^4 || ^5"` и `"webpack": ">=4.41.0 <6"` — корректные semver-выражения, но их легко неверно истолковать. Валидатор semver от Aback Tools проверяет любую строку версии или выражение диапазона по спецификации Semver 2.0.0 — полезно, когда вы пишете библиотеку, объявляющую диапазон peer-зависимости webpack, и хотите убедиться, что выражение сформировано правильно.

Знать текущую версию webpack — это только начало. Управлять ею хорошо — чтобы версия оставалась согласованной между окружениями, была видна каждому контрибьютору и обновлялась намеренно, а не случайно, — требует нескольких простых практик.

1. Фиксируйте точные версии в devDependencies - используйте `"webpack": "5.88.2"` вместо `"^5.88.0"` для критичных для сборки инструментов. Плавающие диапазоны позволяют патчам менять установленную версию между запусками `npm install` на разных машинах, делая вывод сборки недетерминированным.
2. Коммитьте lock-файл - `package-lock.json`, `yarn.lock` или `pnpm-lock.yaml` должны быть в системе контроля версий. Без него контрибьюторы и CI-серверы установят разные патч-версии.
3. Логируйте версию в CI - добавьте шаг `npx webpack --version` перед каждой задачей сборки. Версия появляется в каждом CI-логе, что упрощает соотнесение сбоев сборки с изменениями версии.
4. Аудит зависимостей после обновлений - обновив webpack, сразу выполните `npm list webpack --all`, чтобы убедиться, что не затесались вторичные копии, и `npx webpack --version`, чтобы убедиться, что новая версия та, что использует ваша сборка.
5. Читайте руководство по миграции перед обновлением - у каждой мажорной версии webpack есть официальное руководство по миграции на `webpack.js.org`. Читайте его до обновления — а не после того, как сборка сломается.