Конфигурация Vite

При запуске vite из командной строки Vite автоматически попытается найти файл конфигурации с именем vite.config.js в корне проекта (также поддерживаются другие расширения JS и TS).

Самый простой файл конфигурации выглядит так:

vite.config.js

export default {
  // параметры конфигурации
}

Обратите внимание, что для использования синтаксиса ES-модулей файл конфигурации должен иметь формат, который Node.js распознаёт как ESM. Например, это может быть файл с расширением .mjs или .js, если в ближайшем package.json указано "type": "module".

Вы также можете явно указать файл конфигурации для использования с помощью опции CLI --config (разрешается относительно cwd):

vite --config my-config.js

Посмотреть интерактивный урок на Scrimba

ЗАГРУЗКА КОНФИГУРАЦИИ

По умолчанию Vite использует Rolldown для сборки файла конфигурации во временный файл и его последующей загрузки. Если вы работаете в среде с поддержкой TypeScript (например, Node 22.18+) или используете только обычный JavaScript, можно указать --configLoader native, чтобы загружать файл конфигурации с помощью встроенного механизма среды выполнения. Планируется, что в одной из будущих мажорных версий значение configLoader: 'native' станет используемым по умолчанию.

Настройка Intellisense

Поскольку Vite поставляется с типами TypeScript, вы можете использовать интеллектуальные подсказки вашей IDE с помощью типовых подсказок jsdoc:

/** @type {import('vite').UserConfig} */
export default {
  // ...
}

В качестве альтернативы вы можете использовать вспомогательную функцию defineConfig, которая должна обеспечивать интеллектуальные подсказки без необходимости в аннотациях jsdoc:

import { defineConfig } from 'vite'

export default defineConfig({
  // ...
})

Vite также поддерживает файлы конфигурации TypeScript. Вы можете использовать vite.config.ts с вышеупомянутой вспомогательной функцией defineConfig или с оператором satisfies:

import type { UserConfig } from 'vite'

export default {
  // ...
} satisfies UserConfig

Конфигурация по условию

Если конфигурация должна условно определять параметры в зависимости от команды (serve или build), используемого режима, опции isSsrBuild (сборка SSR) или опции isPreview (превью сборки), она может экспортировать функцию:

export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // конфигурация, специфичная для разработки
    }
  } else {
    // command === 'build'
    return {
      // конфигурация, специфичная для сборки
    }
  }
})

Важно отметить, что в API Vite значение command равно serve во время разработки (в консоли vite, vite dev и vite serve являются псевдонимами), и build при сборке для продакшена (vite build).

isSsrBuild и isPreview — это дополнительные необязательные флаги для различения типов команд build и serve соответственно. Некоторые инструменты, которые загружают конфигурацию Vite, могут не поддерживать эти флаги и будут передавать undefined вместо этого. Поэтому рекомендуется использовать явное сравнение с true и false.

Асинхронная конфигурация

Если конфигурация должна вызывать асинхронные функции, она может экспортировать асинхронную функцию вместо этого. И эта асинхронная функция также может быть передана через defineConfig для улучшенной поддержки интеллектуальных подсказок:

export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()
  return {
    // конфигурация vite
  }
})

Использование переменных окружения в конфигурации

Переменные окружения, доступные во время обработки конфигурации, — это только те, которые уже существуют в текущем окружении процесса (process.env). Vite намеренно откладывает загрузку любых файлов .env* до момента после разрешения пользовательской конфигурации, поскольку набор загружаемых файлов зависит от таких параметров конфигурации, как root и envDir, а также от окончательного значения mode.

Это означает, что переменные, определённые в файлах .env, .env.local, .env.[mode] или .env.[mode].local, не автоматически добавляются в process.env во время выполнения vite.config.*. Они автоматически загружаются позже и становятся доступны для кода приложения через import.meta.env (с фильтром по префиксу VITE_ по умолчанию), как описано в главе Переменные окружения и режимы. Таким образом, если вам нужно только передать значения из файлов .env* в приложение, вызывать что-либо в конфигурации не требуется.

Однако, если значения из файлов .env* должны влиять на саму конфигурацию (например, для установки server.port, включения плагинов по условию или вычисления замен в define), вы можете загрузить их вручную с помощью экспортируемой вспомогательной функции loadEnv.

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // Загрузите файл окружения на основе `mode` в текущем рабочем каталоге.
  // Установите третий параметр в '' для загрузки всех переменных окружения
  // независимо от префикса `VITE_`.
  const env = loadEnv(mode, process.cwd(), '')
  return {
    define: {
      // Указание явной константы уровня приложения, полученной из переменной окружения
      __APP_ENV__: JSON.stringify(env.APP_ENV)
    },
    // Пример: использование переменной окружения для установки порта dev-сервера по условию.
    server: {
      port: env.APP_PORT ? Number(env.APP_PORT) : 5173,
    },
  }
})

Отладка конфигурационного файла в VS Code

При использовании поведения по умолчанию --configLoader bundle, Vite записывает сгенерированный временный конфигурационный файл в папку node_modules/.vite-temp, и при установке точек останова для отладки в конфигурационном файле Vite возникнет ошибка «file not found» («файл не найден»). Чтобы исправить эту проблему, добавьте следующую конфигурацию в .vscode/settings.json:

{
  "debug.javascript.terminalOptions": {
    "resolveSourceMapLocations": [
      "${workspaceFolder}/**",
      "!**/node_modules/**",
      "**/node_modules/.vite-temp/**"
    ]
  }
}