配置 Vite

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

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

export default {
  // 配置选项
}

需要注意的是，要在配置文件中使用 ES 模块语法，该文件需要被 Node.js 识别为 ESM 文件，例如使用 .mjs 扩展名，或最近的 package.json 中声明 "type": "module" 的 .js 文件。

你也可以使用 --config 命令行选项显式指定要使用的配置文件（相对于 cwd 解析）：

vite --config my-config.js

在 Scrimba 上观看交互式课程

::: tip 配置加载
默认情况下，Vite 使用 Rolldown 将配置打包到一个临时文件中并加载它。如果你使用的是支持 TypeScript 的环境（例如 Node.js 22.18+），或者你只编写纯 JavaScript，你可以指定 --configLoader native 来使用环境本身的运行时加载配置文件。configLoader: 'native' 计划在未来的主版本中成为默认值。
:::

配置智能提示

由于 Vite 自带 TypeScript 类型，你可以通过 JSDoc 类型提示来利用 IDE 的智能提示：

/** @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）、当前使用的模式、是否为 SSR 构建（isSsrBuild）或是否在预览构建产物（isPreview）来有条件地决定选项，则可以导出一个函数：

import { defineConfig } from 'vite'
// ---cut---
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // 开发环境专属配置
    }
  } else {
    // command === 'build'
    return {
      // 生产构建专属配置
    }
  }
})

需要特别注意的是，在 Vite 的 API 中，开发时 command 的值为 serve（在命令行中 vite、vite dev 和 vite serve 是别名），而为生产环境构建时（vite build）command 的值为 build。

isSsrBuild 和 isPreview 是额外的可选标志，用于区分 build 和 serve 命令的具体类型。某些加载 Vite 配置的工具可能不支持这些标志，并将它们作为 undefined 传入。因此，建议使用显式与 true 和 false 的比较。

异步配置

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

import { defineConfig } from 'vite'
// ---cut---
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 中定义的变量 不会 在 vite.config.* 运行时自动注入到 process.env。它们会在之后被自动加载，并通过 import.meta.env（默认带有 VITE_ 前缀过滤）暴露给应用代码，具体机制与 环境变量与模式 中描述的一致。因此，如果你只需要将 .env* 文件中的值传递给应用，则无需在配置中调用任何内容。

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

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 根据当前工作目录下的 `mode` 加载 env 文件。
  // 将第三个参数设置为 '' 以加载所有环境变量，而不管
  // 是否带有 `VITE_` 前缀。
  const env = loadEnv(mode, process.cwd(), '')
  return {
    define: {
      // 提供一个源自环境变量的显式应用级常量。
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
    // 示例：使用环境变量有条件地设置开发服务器端口。
    server: {
      port: env.APP_PORT ? Number(env.APP_PORT) : 5173,
    },
  }
})

在 VS Code 中调试配置文件

为了获得最可靠的调试体验，请在启动 Vite 时使用原生配置加载器：

vite --configLoader native

原生加载器会直接执行原始配置文件，因此配置文件中的断点以及 transform 等插件钩子中的断点都能映射到原始源码。它要求运行时支持你的配置文件所使用的语法，例如对于 TypeScript 文件需要 Node.js 22.18+。

使用 --configLoader bundle（当前默认值，但 native 计划在未来的主版本中成为默认值）时，Vite 会生成内联 source map，并在加载前将打包后的配置写入 node_modules/.vite-temp。如果你需要使用打包加载器，请在 .vscode/settings.json 中为 JavaScript 调试终端添加临时目录：

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

此设置仅适用于 JavaScript 调试终端，不会影响从“运行和调试”视图启动的启动配置。若要支持“运行和调试”视图，请在 .vscode/launch.json 中添加临时目录：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Vite",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["exec", "vite", "--configLoader", "bundle"],
      "console": "integratedTerminal",
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**",
        "**/node_modules/.vite-temp/**"
      ]
    }
  ]
}