杨艺韬讲堂

Appearance

第3章 配置系统 ​

"Simplicity is the ultimate sophistication." -- Leonardo da Vinci

本章要点

  • 深入剖析 config.ts（2704 行），理解 Vite 配置系统的完整架构
  • 掌握 UserConfig 到 ResolvedConfig 的转换过程及其设计动因
  • 理解配置文件的多种加载策略：bundle、runner 和 native
  • 剖析 resolveConfig() 函数的完整流程——从内联配置到最终的解析配置
  • 理解 .env 文件的加载机制与环境变量暴露策略
  • 掌握配置合并的层级关系：内联 > 配置文件 > 插件 > 默认值

3.1 config.ts：Vite 最庞大的单文件 ​

src/node/config.ts 是 Vite 源码中最大的单文件，包含 2704 行代码。这并非偶然——配置系统是连接用户意图与内部实现的桥梁，它需要处理类型定义、默认值、多层合并、环境适配、向后兼容等诸多关切。在任何复杂的软件系统中，配置层往往是最容易膨胀的部分，因为它要同时满足"对新手友好"（合理的默认值）和"对专家开放"（细粒度的控制能力）两个看似矛盾的需求。

为什么没有将这个文件拆分成多个小文件？这主要是出于内聚性和循环依赖的考虑。UserConfig 接口被 Vite 几乎所有模块引用，如果将其与 ResolvedConfig、resolveConfig、loadConfigFromFile 等密切相关的定义分开，会引入大量的跨文件导入，增加理解成本。此外，TypeScript 的类型在同一文件中更容易管理和导出。尽管代码量大，但该文件内部有着清晰的逻辑分区。

让我们首先了解这个文件的整体组织：

3.2 UserConfig：用户的配置空间 ​

UserConfig 接口（约第 339 行）定义了用户可以在 vite.config.ts 中配置的完整选项集。它继承自 DefaultEnvironmentOptions，后者包含可以在环境级别覆盖的选项（如 define、resolve、optimizeDeps、dev、build）：

typescript
// 文件: packages/vite/src/node/config.ts

export interface UserConfig extends DefaultEnvironmentOptions {
  root?: string               // 项目根目录，默认 process.cwd()
  base?: string               // 公共基础路径，默认 '/'
  publicDir?: string | false  // 静态资源目录，默认 'public'
  cacheDir?: string           // 缓存目录，默认 'node_modules/.vite'
  mode?: string               // 运行模式
  plugins?: PluginOption[]    // 插件数组
  html?: HTMLOptions          // HTML 相关选项
  css?: CSSOptions            // CSS 相关选项
  json?: JsonOptions          // JSON 加载选项
  esbuild?: ESBuildOptions | false  // (已弃用) esbuild 转换选项
  oxc?: OxcOptions | false    // Oxc 转换选项
  assetsInclude?: string | RegExp | (string | RegExp)[]  // 额外的资源类型
  server?: ServerOptions      // 开发服务器选项
  preview?: PreviewOptions    // 预览服务器选项
  builder?: BuilderOptions    // 构建器选项
  worker?: { ... }            // Web Worker 选项
  ssr?: SSROptions            // SSR 选项
  envDir?: string | false     // .env 文件目录
  envPrefix?: string | string[]  // 暴露到客户端的环境变量前缀，默认 'VITE_'
  environments?: Record<string, EnvironmentOptions>  // 环境级配置
  experimental?: ExperimentalOptions
  future?: FutureOptions | 'warn'
  legacy?: LegacyOptions
  logLevel?: LogLevel
  customLogger?: Logger
  clearScreen?: boolean
  appType?: AppType           // 应用类型: 'spa' | 'mpa' | 'custom'
}

UserConfig 的设计体现了一个重要原则：所有选项都是可选的。用户可以从空对象 {} 开始，只配置自己关心的选项，其余由 Vite 的默认值系统填充。这种设计遵循了"约定优于配置"的哲学——Vite 为每个选项都提供了经过深思熟虑的默认值，大多数项目无需任何配置即可正常工作。

值得注意的是 UserConfig 继承自 DefaultEnvironmentOptions 而非直接定义所有字段。DefaultEnvironmentOptions 包含了可以在环境级别（environments.client、environments.ssr）覆盖的选项，如 define、resolve、optimizeDeps、dev、build。这意味着顶级配置中设置的这些选项实际上是所有环境的默认值，每个环境可以选择性地覆盖。这种继承关系是 Vite 8.0 Environment API 的基础设计。

另一个值得关注的类型设计是 UserConfigExport 联合类型。它不仅接受普通对象，还接受函数和 Promise 形式。函数形式使得配置可以根据运行时上下文（如 command、mode）动态生成，Promise 形式支持异步的配置初始化（如从远程获取配置）。这种灵活性使得 Vite 配置能够适应各种复杂的工程场景。

3.2.1 Environment API 带来的配置层级 ​

Vite 8.0 引入 Environment API 后，配置形成了两层结构：

顶级配置中的 resolve、optimizeDeps、build、dev 等选项作为所有环境的默认值。client 环境额外继承顶级的 resolve（包括 mainFields 和 conditions）和 optimizeDeps，而非客户端环境则使用更保守的默认值。

这种层级设计解决了一个实际问题：在引入 Environment API 之前，用户想要为 SSR 设置不同的模块解析策略（例如不同的 conditions 或 external 列表），需要使用分散的 ssr.external、ssr.noExternal 等选项。现在，用户可以在 environments.ssr.resolve 中集中配置 SSR 相关的解析选项，同时让 environments.client 继承顶级的 resolve 配置。如果需要创建自定义环境（如边缘运行时），只需在 environments 下添加一个新的键值对，它会自动继承顶级默认值。

3.3 defineConfig()：类型辅助的精妙设计 ​

defineConfig 是 Vite 提供给用户的类型辅助函数。在 JavaScript 中，它完全没有运行时效果；在 TypeScript 中，它通过精心设计的类型重载为配置对象提供完整的智能提示和类型检查。这是一种在现代前端工具中广泛使用的模式——通过一个恒等函数为用户提供类型安全的编写体验。

让我们看看它的多重载签名：

typescript
// 文件: packages/vite/src/node/config.ts

export function defineConfig(config: UserConfig): UserConfig
export function defineConfig(config: Promise<UserConfig>): Promise<UserConfig>
export function defineConfig(config: UserConfigFnObject): UserConfigFnObject
export function defineConfig(config: UserConfigFnPromise): UserConfigFnPromise
export function defineConfig(config: UserConfigFn): UserConfigFn
export function defineConfig(config: UserConfigExport): UserConfigExport
export function defineConfig(config: UserConfigExport): UserConfigExport {
  return config
}

这个函数的实现仅仅是 return config——它不做任何运行时处理。它的全部价值在于 TypeScript 类型推断：

typescript
// 用法一：直接配置对象，获得完整的类型提示
export default defineConfig({
  server: { port: 3000 },
})

// 用法二：函数形式，可以根据命令和模式动态配置
export default defineConfig(({ command, mode }) => {
  if (command === 'serve') {
    return { /* 开发配置 */ }
  } else {
    return { /* 构建配置 */ }
  }
})

// 用法三：异步函数
export default defineConfig(async ({ command }) => {
  const data = await someAsyncOperation()
  return { /* 基于异步数据的配置 */ }
})

ConfigEnv 对象传递给配置函数，包含关键的上下文信息：

typescript
// 文件: packages/vite/src/node/config.ts

export interface ConfigEnv {
  command: 'build' | 'serve'  // 当前执行的命令
  mode: string                 // 运行模式（development, production, 自定义）
  isSsrBuild?: boolean        // 是否为 SSR 构建
  isPreview?: boolean          // 是否为预览模式
}

3.4 configDefaults：默认值系统 ​

默认值系统是配置架构的根基。好的默认值意味着用户不需要理解每一个选项就能开始工作，同时又不会在遇到特殊需求时被限制住。Vite 的默认值经过了社区大量反馈的打磨，反映了前端开发的最佳实践。

Vite 的默认配置定义在一个冻结的对象中（约第 762 行），确保默认值不会被意外修改：

typescript
// 文件: packages/vite/src/node/config.ts

const configDefaults = Object.freeze({
  define: {},
  dev: {
    warmup: [],
    sourcemap: { js: true },
    sourcemapIgnoreList: undefined,
  },
  build: buildEnvironmentOptionsDefaults,
  resolve: {
    externalConditions: [...DEFAULT_EXTERNAL_CONDITIONS],
    extensions: DEFAULT_EXTENSIONS,  // ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
    dedupe: [],
    noExternal: [],
    external: [],
    preserveSymlinks: false,
    tsconfigPaths: false,
    alias: [],
  },

  base: '/',
  publicDir: 'public',
  plugins: [],
  html: { cspNonce: undefined },
  css: cssConfigDefaults,
  json: { namedExports: true, stringify: 'auto' },
  assetsInclude: undefined,
  builder: builderOptionsDefaults,
  server: serverConfigDefaults,
  preview: { port: DEFAULT_PREVIEW_PORT },
  experimental: {
    importGlobRestoreExtension: false,
    renderBuiltUrl: undefined,
    hmrPartialAccept: false,
    bundledDev: false,
  },
  future: {
    removePluginHookHandleHotUpdate: undefined,
    removePluginHookSsrArgument: undefined,
    removeServerModuleGraph: undefined,
    removeServerHot: undefined,
    removeServerTransformRequest: undefined,
    removeServerWarmupRequest: undefined,
    removeSsrLoadModule: undefined,
  },
  legacy: { skipWebSocketTokenCheck: false },
  logLevel: 'info',
  customLogger: undefined,
  clearScreen: true,
  envDir: undefined,
  envPrefix: 'VITE_',
  worker: {
    format: 'iife',
    plugins: (): never[] => [],
  },
  optimizeDeps: {
    include: [],
    exclude: [],
    needsInterop: [],
    rolldownOptions: {},
    extensions: [],
    disabled: 'build',
    holdUntilCrawlEnd: true,
  },
})

注意几个值得关注的默认值：

  • json.stringify: 'auto'：自动检测 JSON 文件大小，超过阈值时使用 JSON.parse() 代替对象字面量，提升构建后的加载性能
  • worker.format: 'iife'：Web Worker 默认输出为 IIFE 格式，确保最广泛的浏览器兼容性
  • optimizeDeps.holdUntilCrawlEnd: true：等待入口爬取完成后再运行优化器，减少二次优化的概率

3.5 resolveConfig()：配置解析的核心引擎 ​

resolveConfig 是整个配置系统的核心函数，位于第 1357 行，长达约 780 行。这是 Vite 启动过程中最先执行的关键函数之一——无论是 vite 开发命令还是 vite build 构建命令，第一步都是调用 resolveConfig 来获得完整的配置。

该函数接收用户的 InlineConfig（来自命令行参数和 API 调用的配置），经过十余个步骤，生成最终的 ResolvedConfig。这个过程涉及文件加载、插件执行、多层合并、选项标准化等复杂操作，是理解 Vite 配置系统的关键路径。

让我们逐步追踪这个函数的执行过程。

让我们逐步追踪这个函数的执行过程。每个步骤都有其存在的必要性，跳过任何一步都可能导致配置的不完整或不一致。

3.5.1 步骤一：初始化与兼容性处理 ​

typescript
// 文件: packages/vite/src/node/config.ts

export async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development',
  defaultNodeEnv = 'development',
  isPreview = false,
  patchConfig?: (config: ResolvedConfig) => void,
  patchPlugins?: (resolvedPlugins: Plugin[]) => void,
): Promise<ResolvedConfig> {
  let config = inlineConfig
  // 向后兼容：确保 rollupOptions 和 rolldownOptions 同步
  config.build ??= {}
  setupRollupOptionCompat(config.build, 'build')
  config.worker ??= {}
  setupRollupOptionCompat(config.worker, 'worker')
  config.optimizeDeps ??= {}
  setupRollupOptionCompat(config.optimizeDeps, 'optimizeDeps')

  let mode = inlineConfig.mode || defaultMode
  const isNodeEnvSet = !!process.env.NODE_ENV

  // 尽早设置 NODE_ENV，因为部分依赖（如 @vue/compiler-*）依赖它
  if (!isNodeEnvSet) {
    process.env.NODE_ENV = defaultNodeEnv
  }

  const configEnv: ConfigEnv = {
    mode,
    command,
    isSsrBuild: command === 'build' && !!config.build?.ssr,
    isPreview,
  }
  // ...
}

函数签名中的 patchConfig 和 patchPlugins 参数标记为 @internal，它们是供 Vite 构建器（Builder）在内部使用的回调，允许在配置组装完成后、插件解析完成后分别进行修补。

函数签名中的 patchConfig 和 patchPlugins 参数标记为 @internal，它们是供 Vite 内部的构建器（Builder）使用的回调。在多环境构建场景下，Builder 需要在配置组装完成后修改某些构建选项（如 SSR 相关的设置），这两个回调提供了一个安全的注入点，避免了对 resolveConfig 流程的侵入式修改。

setupRollupOptionCompat 函数处理了 Vite 从 Rollup 到 Rolldown 的命名迁移。由于许多用户和插件仍在使用 rollupOptions 这个名称，该函数确保 rollupOptions 和 rolldownOptions 双向同步——无论用户设置了哪一个，另一个都会得到相同的值。

3.5.2 步骤二：加载配置文件 ​

typescript
let { configFile } = config
if (configFile !== false) {
  const loadResult = await loadConfigFromFile(
    configEnv,
    configFile,
    config.root,
    config.logLevel,
    config.customLogger,
    config.configLoader,
  )
  if (loadResult) {
    config = mergeConfig(loadResult.config, config)
    configFile = loadResult.path
    configFileDependencies = loadResult.dependencies
  }
}

注意 mergeConfig 的参数顺序：mergeConfig(loadResult.config, config) 意味着内联配置（config，即命令行参数）优先于文件配置（loadResult.config）。这确保了 vite build --mode production 能覆盖配置文件中的 mode 设置。

3.5.3 步骤三：解析 mode ​

typescript
// 用户可能在配置文件中设置了 mode，但 --mode 标志优先级更高
mode = inlineConfig.mode || config.mode || mode
configEnv.mode = mode

mode 的优先级链为：命令行 --mode > 配置文件 config.mode > 默认值（development 或 production）。

基于 VitePress 构建

Copyright © 2024-present 杨艺韬