Webpack: Module not found: Can't resolve

#Как Webpack ищет модули

Для импорта import x from 'name' Webpack ищет пакет в node_modules (по цепочке каталогов вверх), для относительных путей (./file) — файл с расширениями из resolve.extensions. Сообщение «Can't resolve» означает, что модуль не найден по всем правилам. Частые причины: пакет не установлен или удалён, опечатка в имени или пути, разный регистр (на macOS/Windows работает, на Linux нет), отсутствует расширение в resolve.extensions, неверный alias, пакет в devDependencies не установился при npm ci --omit=dev, модуль Node.js (fs, path) в браузерной сборке Webpack 5 без полифила.

#Типичные причины

#Порядок

1. Прочитайте сообщение: какой модуль и из какого каталогаОткройте терминал в корневой папке проекта (VS Code: «Терминал» → «Создать терминал»). Прочтите полный вывод Webpack: после Can't resolve указано требуемое имя, а строка in ... показывает каталог исходного файла. Запишите оба пути. Импорт ./Header — относительный файл; импорт react — пакет. Их проверяют разными способами, не устанавливайте пакет по имени файла.
2. Проверьте, установлен ли пакет: npm ls имяЕсли в ошибке указан пакет без ./ или ../, в корне проекта выполните npm ls имя_пакета, заменив имя реальным названием из сообщения, например npm ls lodash. Если пакет отображается как (empty) или missing, проверьте раздел dependencies/devDependencies в package.json. Для локального импорта ./Header эту проверку пропустите и переходите к проверке пути.
3. Установите пакет: npm install имяТолько если отсутствует сторонний пакет, в каталоге с package.json выполните npm install имя_пакета, подставив точное имя из ошибки; если он нужен исключительно для сборки, используйте npm install --save-dev имя_пакета. Убедитесь, что команда завершилась без npm ERR! и что пакет появился в зависимостях. Если ошибка вызвана неправильным названием импорта, исправьте строку import, а не устанавливайте случайные пакеты.
4. Проверьте путь и регистр файловДля импорта с ./ или ../ откройте указанный в ошибке исходный файл, найдите строку import/require и сравните её с реальным путём на диске. Проверьте количество ../, расширение и регистр: Header.tsx и header.tsx — разные имена в Linux. Используйте поиск файлов в редакторе или git ls-files; исправьте имя и повторите сборку.
5. Проверьте resolve.extensions и resolve.alias в конфигурацииЕсли файл и пакет существуют, откройте webpack.config.js и найдите секцию resolve. Сверьте alias с действительными каталогами; для относительных каталогов в конфигурации обычно используют path.resolve(__dirname, 'src'). Проверьте, входит ли используемое расширение в resolve.extensions, либо явно напишите расширение в импорте. После правки запустите npm run build или штатный сценарий из package.json.
6. Для Webpack 5 и модулей Node настройте resolve.fallbackЭтот шаг нужен только если Webpack 5 собирает код ДЛЯ БРАУЗЕРА, а сторонняя библиотека импортирует встроенный модуль Node (crypto, stream, path и др.). Webpack 5 больше не подставляет браузерные замены автоматически. Проверьте, предусмотрена ли у библиотеки версия для браузера. Лишь если подходящая замена действительно нужна, установите совместимый пакет и задайте resolve.fallback по его документации; серверный модуль нельзя автоматически считать доступным в браузере.
7. Удалите node_modules и lock-файл при конфликте версий, установите зановоЕсли зависимости установлены, но ошибка появилась после смены ветки или версии Node, сначала сохраните package-lock.json и выполните npm ci из корня проекта — команда устанавливает строго по существующему файлу блокировки и пересоздаёт node_modules. Она удалит текущий node_modules, поэтому сохраните любые вручную созданные в нём файлы. Не удаляйте package-lock.json: это меняет закреплённые версии и затрудняет воспроизведение проблемы.
8. Очистите кэш WebpackОчистку выполняйте только после исправления путей и проверки зависимостей. Для проекта, использующего файловый кэш Webpack, остановите сборку, затем удалите конкретный каталог кэша (например, node_modules/.cache/webpack, если он существует). Не стирайте все скрытые каталоги или системные файлы. Запустите сборку заново; если ошибка не изменилась, причина, вероятно, не в кэше.
9. Проверьте, что сборка запускается из нужного каталогаПроверьте текущую папку командой pwd (Linux/macOS) или cd (Windows), затем убедитесь, что рядом есть package.json. Откройте package.json, найдите scripts и запустите указанный сценарий, обычно npm run build. Если сборка прошла, проверьте выходной каталог и приложение; если нет — сохраните первые строки исходной ошибки, а не только финальное Module not found.
10. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
    Выберите подходящий вариант — это не команды для последовательного выполнения

    Вариант 1Установлен ли пакет и какая версия

    Linux · Терминал (Bash)КомандаКопировать всёВыделить

    Установлен ли пакет и какая версия

    npm ls lodash

    ls node_modules/lodash | head

    Вариант 2Пример установки существующей зависимости; webpack и webpack-cli не нужно переустанавливать ради ошибки пои…

    Linux · Терминал (Bash)КомандаКопировать всёВыделить

    Пример установки существующей зависимости; webpack и webpack-cli не нужно переустанавливать ради ошибки поиска модуля

    # Только при действительно отсутствующем пакете, вместо lodash — имя из ошибки

    npm install lodash

    Вариант 3Использовать при согласованном сбросе зависимостей, не удалять package-lock.json

    Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

    Использовать при согласованном сбросе зависимостей, не удалять package-lock.json

    # Запускать только в корне проекта с package-lock.json.

    # npm ci удаляет и создаёт заново node_modules; lock-файл сохраняется.

    npm ci

    Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

    Вариант 4В примере нет исполняемых команд массового удаления

    Linux · Терминал (Bash)КомандаКопировать всёВыделить

    В примере нет исполняемых команд массового удаления

    # Найдите папку кэша Webpack (пример, если она реально есть)

    ls -ld node_modules/.cache/webpack

    # Остановите сборку; удаляйте только этот кэш через файловый менеджер или редактор

    Вариант 5Пример ТОЛЬКО resolve.alias/extensions; fallback для встроенных модулей Node определяется отдельно по нужда…

    JavaScriptКомандаКопировать всёВыделить

    Пример ТОЛЬКО resolve.alias/extensions; fallback для встроенных модулей Node определяется отдельно по нуждам браузерной библиотеки

    const path = require('node:path');

    module.exports = {

    resolve: {

    extensions: ['.js', '.jsx', '.ts', '.tsx', '.json'],

    alias: { '@': path.resolve(__dirname, 'src') }

    }

    };

    Вариант 6Проверка регистра имён файлов (Linux чувствителен к регистру)

    Linux · Терминал (Bash)КомандаКопировать всёВыделить

    Проверка регистра имён файлов (Linux чувствителен к регистру)

    git ls-files | grep -i "components/header"

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

В монорепозиториях (npm workspaces, pnpm, yarn) зависимости поднимаются в корень. Запускайте установку из корня и проверьте resolve.modules. Для pnpm используйте resolve.symlinks и настройте pnpm install без изоляции только если необходимо. При ошибке «в пакете нет подпути» проверьте поле exports в package.json зависимости.