配置 Vite

当从命令行运行 vite 时，Vite 会自动尝试解析项目根目录中的 vite.config.js 配置文件（也支持其他 JS 和 TS 扩展名）。

最基本的配置文件如下所示：

vite.config.js

export default {
  // config options
}

注意：即使项目没有使用原生的 Node ESM（例如 package.json 中没有 "type": "module"），Vite 也支持在配置文件中使用 ES 模块语法。在这种情况下，配置文件会在加载前自动预处理。

你也可以通过 --config CLI 选项显式指定要使用的配置文件（路径相对于 cwd 解析）：

bash

vite --config my-config.js

观看 Scrimba 上的交互式教程

配置加载

默认情况下，Vite 使用 Rolldown 将配置文件打包成临时文件并加载。这在 Monorepo 中导入 TypeScript 文件时可能会导致问题。如果遇到此类问题，你可以指定 --configLoader runner 来改用模块运行器 (module runner)，它不会创建临时配置，而是会实时转换文件。注意，模块运行器不支持配置文件中的 CJS，但外部 CJS 包应能正常工作。

另外，如果你使用的环境支持 TypeScript（例如 node --experimental-strip-types），或者你只编写纯 JavaScript，你可以指定 --configLoader native 使用环境的原生运行时来加载配置文件。注意，配置文件导入的模块如有更新将不会被检测到，因此不会自动重启 Vite 服务器。

配置智能提示

由于 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）、所使用的模式 (mode)、是否为 SSR 构建 (isSsrBuild) 或是否正在预览构建 (isPreview) 来有条件地确定选项，则可以导出一个函数：

export default defineConfig
(({ command
, mode
, isSsrBuild
, isPreview
 }) => {
  if (command
 === 'serve') {
    return {
      // dev specific config
    }
  } else {
    // command === 'build'
    return {
      // build specific config
    }
  }
})

需要注意的是，在 Vite 的 API 中，command 的值在开发阶段（CLI 命令 vite、vite dev 和 vite serve 均为别名）为 serve；在生产构建时（vite build）则为 build。

isSsrBuild 和 isPreview 是额外的可选标志，用于分别区分 build 和 serve 命令的具体类型。一些加载 Vite 配置的工具可能不支持这些标志，并会传递 undefined。因此，建议明确与 true 或 false 进行比较。

异步配置

如果配置需要调用异步函数，可以导出一个异步函数。此异步函数也可以通过 defineConfig 包装，以获得更好的智能提示支持：

export default defineConfig
(async ({ command
, mode
 }) => {
  const data
 = await asyncFunction()
  return {
    // vite config
  }
})

在配置中使用环境变量

在配置评估时可用的环境变量仅限于当前进程环境 (process.env) 中已有的变量。Vite 会刻意延迟加载任何 .env* 文件，直到用户配置被解析完成，因为要加载的文件集取决于 root 和 envDir 等配置选项，以及最终的 mode。

这意味着：在 vite.config.* 运行期间，定义在 .env、.env.local、.env.[mode] 或 .env.[mode].local 中的变量不会自动注入到 process.env 中。它们会在稍后自动加载，并通过 import.meta.env 暴露给应用程序代码（默认带有 VITE_ 前缀过滤器），正如环境变量和模式文档所述。因此，如果你只需要将 .env* 文件中的值传递给应用，则无需在配置文件中进行任何额外调用。

然而，如果 .env* 文件中的值必须影响配置本身（例如设置 server.port、有条件地启用插件或计算 define 替换），你可以使用导出的 loadEnv 辅助函数手动加载它们。

import { defineConfig
, loadEnv
 } from 'vite'

export default defineConfig
(({ mode
 }) => {
  // Load env file based on `mode` in the current working directory.
  // Set the third parameter to '' to load all env regardless of the
  // `VITE_` prefix.
  const env
 = loadEnv
(mode
, process
.cwd
(), '')
  return {
    define
: {
      // Provide an explicit app-level constant derived from an env var.
      __APP_ENV__
: JSON
.stringify
(env
.APP_ENV
),
    },
    // Example: use an env var to set the dev server port conditionally.
    server
: {
      port
: env
.APP_PORT
 ? Number
(env
.APP_PORT
) : 5173,
    },
  }
})

在 VS Code 中调试配置文件

在使用默认的 --configLoader bundle 行为时，Vite 会将生成的临时配置文件写入 node_modules/.vite-temp 文件夹。在 Vite 配置文件中设置断点调试时，会发生“找不到文件”错误。要修复此问题，请将以下配置添加到 .vscode/settings.json：

json

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

配置 Vite ​

配置智能提示 ​

条件配置 ​

异步配置 ​

在配置中使用环境变量 ​