Vite: Исправление ошибки "Failed to resolve import" (псевдонимы путей)

Вы только что настроили псевдонимы путей в своём проекте Vite, заменив громоздкие импорты ../../../components на чистые пути @/components. Но теперь Vite выдаёт раздражающую ошибку: “Failed to resolve import”. Это происходит потому, что Vite и TypeScript по-разному обрабатывают разрешение модулей, и для исправления требуется синхронизация двух отдельных конфигураций.

Это руководство показывает, как именно исправить ошибки псевдонимов путей в Vite, используя два проверенных метода: ручную конфигурацию для полного контроля или автоматизированный плагин vite-tsconfig-paths для простоты.

Ошибка “Failed to resolve import” в Vite

Ошибка Vite Failed to resolve import появляется, когда ваш сборщик не может найти модули, используя пользовательские псевдонимы путей. Вы увидите варианты вроде:

• [vite] Internal server error: Failed to resolve import "@/components/Header"
• Cannot find module '@/utils' or its corresponding type declarations
• Ошибка TypeScript TS2307 в вашей IDE

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

Понимание причин сбоя псевдонимов путей в Vite

Проблема двух конфигураций

Vite использует Rollup для сборки, в то время как TypeScript отдельно обрабатывает проверку типов. Каждому инструменту нужна своя конфигурация:

• Vite требует resolve.alias в vite.config.ts для сборки модулей
• TypeScript требует paths в tsconfig.json для проверки типов и поддержки IDE

Когда эти конфигурации не совпадают, вы получаете ошибки разрешения импортов. Vite может понимать @/components, но TypeScript — нет, или наоборот.

Распространённые причины ошибок импорта

Три проблемы вызывают большинство ошибок resolve alias в Vite:

1. Отсутствие типов Node.js: использование path.resolve() без @types/node
2. Несоответствие синтаксиса: Vite использует объектную нотацию, а TypeScript — паттерны массивов
3. Конфликты формата модулей: использование специфичных для CommonJS переменных вроде __dirname в ESM-проектах

Метод 1: Ручная конфигурация для псевдонимов TypeScript в Vite

Шаг 1: Настройка vite.config.ts

Сначала установите необходимые типы Node.js:

npm install -D @types/node

Затем обновите конфигурацию Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@utils': fileURLToPath(new URL('./src/utils', import.meta.url))
    }
  }
})

Для CommonJS-проектов можно использовать path.resolve() с __dirname:

// vite.config.ts (CommonJS)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils')
    }
  }
})

Шаг 2: Обновление tsconfig.json

Настройте TypeScript для распознавания тех же псевдонимов:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Обратите внимание на разницу в синтаксисе: Vite использует '@components', а TypeScript использует "@components/*" со значениями массива.

Проверка настройки

Протестируйте конфигурацию с помощью импорта:

// Было: import Button from '../../../components/Button'
import Button from '@components/Button'

Ваша IDE должна предоставлять подсказки автодополнения, а npm run dev должен запускаться без ошибок.

Метод 2: Автоматическая настройка с vite-tsconfig-paths

Установка и базовая настройка

Плагин vite-tsconfig-paths автоматически синхронизирует ваши пути TypeScript с Vite:

npm install -D vite-tsconfig-paths

Обновите конфигурацию Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()]
})

Вот и всё. Плагин читает пути из вашего tsconfig.json и автоматически настраивает Vite.

Преимущества перед ручной конфигурацией

• Единый источник истины: обновляйте только tsconfig.json
• Отсутствие ошибок синхронизации: псевдонимы всегда совпадают
• Более чистые конфигурационные файлы: меньше шаблонного кода
• Поддержка монорепозиториев: обрабатывает сложные настройки рабочих пространств

Устранение ошибок resolve alias в Vite

JavaScript-проекты без TypeScript

Для JavaScript-проектов создайте jsconfig.json вместо этого:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Плагин vite-tsconfig-paths также работает с jsconfig.json.

Монорепозитории и продвинутые сценарии

В монорепозиториях убедитесь, что ваши пути относительны корня рабочего пространства:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["packages/app/src/*"],
      "@shared/*": ["packages/shared/src/*"]
    }
  }
}

Для пользователей Windows всегда используйте прямые слэши (/) в конфигурациях путей — и Vite, и TypeScript корректно их нормализуют.

Расхождения между сборкой и разработкой

Если псевдонимы работают в разработке, но не работают при сборке:

1. Проверьте проблемы с чувствительностью к регистру (особенно на Linux/macOS)
2. Убедитесь, что baseUrl установлен правильно
3. Проверьте, что все пути с псевдонимами существуют в выходных данных сборки
4. Проверьте, что ваш инструмент сборки сохраняет конфигурацию псевдонимов

Краткая справка: Ручная конфигурация vs vite-tsconfig-paths

Заключение

Исправление ошибок Vite Failed to resolve import сводится к согласованию разрешения модулей между Vite и TypeScript. Ручной метод даёт вам точный контроль над обеими конфигурациями, в то время как vite-tsconfig-paths полностью устраняет проблемы синхронизации.

Для большинства проектов начните с vite-tsconfig-paths — это проще и предотвращает расхождение конфигураций. Переходите на ручную конфигурацию только когда вам нужны разные стратегии псевдонимов между разработкой и продакшеном, или при работе с необычными настройками сборки, требующими пользовательской логики разрешения.

Часто задаваемые вопросы

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.