Разбираемся с флагами --mode и --node-env при запуске Webpack

В командах для запуска Webpack часто используют флаг --mode или другой флаг --node-env. На первый взгляд они похожи: оба могут изменять переменную окружения NODE_ENV, и с их помощью можно создавать условия внутри конфигурации Webpack.

Несмотря на схожесть, между ними есть важные различия. Давайте разберёмся, в чём именно. Но сначала начнем с того что это за переменная NODE_ENV и зачем она нужна.

---

Что такое NODE_ENV и зачем она нужна

NODE_ENV — это переменная окружения, которая определяет среду выполнения приложения.
На практике она чаще всего принимает значения:

• development — режим разработки (отладка, отсутствие минификации, подробные сообщения об ошибках)

• production — режим продакшена (оптимизации, минификация, удаление неиспользуемого кода)

• любое другое значение (например, test, staging) для кастомных сценариев

Эта переменная позволяет менять поведение приложения в зависимости от среды — например, подключать разные плагины или изменять логику сборки.

---

Как работает --mode

Если нужно, чтобы сборка вела себя по-разному в зависимости от режима, используется флаг --mode со значениями:

• development
• production
• none

Этот флаг автоматически устанавливает process.env.NODE_ENV в соответствующее значение и включает готовый набор оптимизаций для выбранного режима.

module.exports = (env, argv) => {   
	const isProduction = argv.mode === 'production';    
	return {     
		entry: './src/index.js',     
		plugins: [ isProduction && new CleanWebpackPlugin()]   
	}; 
};

В этом примере переменная isProduction определяется через argv.mode, который Webpack передаёт в конфиг в зависимости от значения указанного в флаге -mode.

Как работает --node-env

Флаг --node-env напрямую устанавливает переменную окружения process.env.NODE_ENV в указанное значение.
В отличие от --mode, он не ограничен только development и production. Можно указать, например, test или staging.

Пример команды запуска:

webpack --node-env=test

N.B. Можно назначить значение переменной окружения NODE_ENV без использования флага --node-env, как в примере ниже:

NODE_ENV=test webpack

Но это не будет кросс-платформенным решением, так как в Windows нужно использовать set NODE_ENV=test && webpack, а в Unix-подобных системах — NODE_ENV=test webpack. Поэтому лучше использовать флаг --node-env для кросс-платформенности. “

 
Однако `--node-env` **не включает оптимизации автоматически** — их нужно прописывать вручную.
 
```js
 
const isTest = process.env.NODE_ENV === 'test';  
module.exports = {   
plugins: [ isTest && new SomeTestPlugin()] 
};

В этом случае переменная isTest доступна в любом месте конфигурации, так как process.env.NODE_ENV глобальна.

N.B. Если мы используем --node-env , но все же хотим что бы сработала при сборке автоматическая оптимизация для продакшена как если бы мы использовали флаг --mode cо значением production, то нам нужно явно прописать в конфигурации ключ mode и установить его значение в production:

const isProd = process.env.NODE_ENV === 'production';  
module.exports = {  
    mode: isProd ? "production" : "development",
    ...
}

---

Сравнительная таблица

Критерий	--mode	--node-env
Доступные значения	development, production, none	Любое (development, production, test, staging и др.)
Устанавливает process.env.NODE_ENV	Да	Да
Включает оптимизации	Да, для production (минификация, tree-shaking, удаление неиспользуемого кода)	Нет, нужно настраивать вручную
Как получить значение в конфиге	Через argv.mode внутри функции module.exports	Через process.env.NODE_ENV в любом месте файла
Основное применение	Быстро переключать сборку между режимами разработки и продакшена с готовыми оптимизациями	Гибкая настройка среды (тесты, staging, кастомные сценарии)
Пример команды	webpack --mode production	webpack --node-env=test

---

Резюмирую

• Используйте --mode, если вам нужно быстро переключаться между разработкой и продакшеном с автоматическими оптимизациями.
• Используйте --node-env, если вы хотите задать кастомное значение среды (например, test или staging) и настроить поведение сборки вручную.