深入 vite 原理，vite 是如何解析配置文件的

在上一篇文章介绍了在开发环境启动 vite 的整体实现过程，其中第一步配置文件解析是最为重要的部分，下面展开讲讲 vite 解析配置文件的实现原理

const config = await resolveConfig(inlineConfig, 'serve')

配置文件解析

配置文件解析的核心方法是 resolveConfig ，方法定义在 packages/vite/src/node/config.ts 文件下，解析配置文件的过程主要有五步

加载配置文件
解析用户插件
加载环境变量
创建路径解析器
解析插件流水线，调用每个插件的 configResolved 钩子

第一步：加载配置文件

vite 的配置主要来自两个地方：命令行和配置文件。命令行配置在启动项目时，通过 cac 解析并传递到了 resolveConfig 方法中，而配置文件中的配置则需要通过 loadConfigFromFile 方法加载

获取到命令行和配置文件的配置后，通过 mergeConfig 方法合并两个配置，其中命令行配置的优先级是高于配置文件的

export async function resolveConfig(inlineConfig: InlineConfig) {
  // 此处的 config 是 命令行配置
  let config = inlineConfig

  // ========== 1. 加载配置文件 ==========
  let { configFile } = config
  if (configFile !== false) {
    const loadResult = await loadConfigFromFile(
      configEnv,
      configFile,
      config.root,
      config.logLevel
    )
    if (loadResult) {
      // 命令行配置和配置文件配置合并
      config = mergeConfig(loadResult.config, config)
      configFile = loadResult.path
      configFileDependencies = loadResult.dependencies
    }
  }
}

vite 的配置文件都定义 vite.config 文件下，但根据 ts / js、ESModule / CommonJS 划分，一共有六种文件后缀

export const DEFAULT_CONFIG_FILES = [
  'vite.config.js',
  'vite.config.mjs',
  'vite.config.ts',
  'vite.config.cjs',
  'vite.config.mts',
  'vite.config.cts',
]

loadConfigFromFile 解析配置文件的第一步就是获取配置文件路径，然后根据文件类型和 package.json 的配置判断是 ESModule 还是 CommonJS，因为两种模式的配置文件加载方式存在一定区别

export async function loadConfigFromFile(
  configEnv: ConfigEnv,
  configFile?: string,
  configRoot: string = process.cwd(),
  logLevel?: LogLevel,
): Promise<{
  path: string
  config: UserConfig
  dependencies: string[]
} | null> {

  // 1. 获取配置文件路径
  let resolvedPath: string | undefined
  // 如果定义配置文件路径，直接解析
  if (configFile) {
    resolvedPath = path.resolve(configFile)
  } else {
    // 没有定义，从默认的 6 个配置文件定义中获取
    for (const filename of DEFAULT_CONFIG_FILES) {
      const filePath = path.resolve(configRoot, filename)
      if (!fs.existsSync(filePath)) continue

      resolvedPath = filePath
      break
    }
  }

  // 2. 判断是 ESModule 还是 CommonJS
  let isESM = false
  if (/\.m[jt]s$/.test(resolvedPath)) {
    isESM = true
  } else if (/\.c[jt]s$/.test(resolvedPath)) {
    isESM = false
  } else {
    try {
      const pkg = lookupFile(configRoot, ['package.json'])
      isESM =
        !!pkg && JSON.parse(fs.readFileSync(pkg, 'utf-8')).type === 'module'
    } catch (e) {}
  }

  try {
    // 3. 通过 EsBuild 将配置文件打包成 js 代码
    const bundled = await bundleConfigFile(resolvedPath, isESM)
    // 4. 解析配置参数
    const userConfig = await loadConfigFromBundledFile
    (
      resolvedPath,
      bundled.code,
      isESM,
    )

    const config = await (typeof userConfig === 'function'
      ? userConfig(configEnv)
      : userConfig
    }
    return {
      path: normalizePath(resolvedPath),
      config,
      dependencies: bundled.dependencies,
    }
  } catch (e) {
    throw e
  }
}

接下来通过 bundleConfigFile 方法，使用 esbuild 将配置文件打包成 js 代码

除了基础的配置参数外，注意到 write 参数配置的是 false，也就是不写入文件，这样可以提升打包速度

此外在打包过程中也会定义两个插件

externalize-deps 插件：用于处理外部依赖解析，通过 onResolve 钩子处理依赖解析，将非相对路径的依赖和内置模块标记为外部依赖。这样打包工具就不需要处理被标记过的外部插件，可以有效减少打包体积
inject-file-scope-variables 插件：用于在文件作用域内注入变量

async function bundleConfigFile(
  fileName: string,
  isESM: boolean
): Promise<{ code: string; dependencies: string[] }> {
  const dirnameVarName = '__vite_injected_original_dirname'
  const filenameVarName = '__vite_injected_original_filename'
  const importMetaUrlVarName = '__vite_injected_original_import_meta_url'
  const result = await build({
    absWorkingDir: process.cwd(), // 工作目录绝对路径
    entryPoints: [fileName], // 打包入口文件
    outfile: 'out.js', // 输出文件路径（实际上不会写入文件）
    write: false, // 不写入文件
    target: ['node14.18', 'node16'], // 打包 ndoe 版本
    platform: 'node', // 目标平台为 Node.js
    bundle: true, // 打包为单个文件
    format: isESM ? 'esm' : 'cjs', // 打包格式，esm 或者 cjs
    mainFields: ['main'], // 入口文件字段
    sourcemap: 'inline',
    metafile: true,
    // 需要注入的全局字段
    define: {
      __dirname: dirnameVarName,
      __filename: filenameVarName,
      'import.meta.url': importMetaUrlVarName,
    },
    plugins: [
      {
        // 处理外部依赖解析
        // 通过 onResolve 钩子处理依赖解析，将非相对路径的依赖和内置模块标记为外部依赖
        // 通过返回 { external: true } 来告知打包工具不需要处理
        name: 'externalize-deps',
        setup(build) {},
      },
      {
        // 作用：文件作用域内注入变量
        // 通过 onLoad 钩子读取文件内容，在内容前添加变量的注入代码
        name: 'inject-file-scope-variables',
        setup(build) {},
      },
    ],
  })
  const { text } = result.outputFiles[0]
  return {
    code: text,
    dependencies: result.metafile ? Object.keys(result.metafile.inputs) : [],
  }
}

在获取打包好的配置文件之后，会通过 loadConfigFromBundledFile 方法来解析配置参数，这里对于 ESModule 和 CommonJS 的处理逻辑的是有区别的，对于 ESModule 采用的 AOP 编译的方式，主要分为三步

将编译后代码写入临时文件
通过 ESM import 读取临时内容
获取配置内容后删除临时内容

async function loadConfigFromBundledFile(
  fileName: string,
  bundledCode: string,
  isESM: boolean
): Promise<UserConfigExport> {
  if (isESM) {
    const fileBase = `${fileName}.timestamp-${Date.now()}-${Math.random().toString(16).slice(2)}`
    const fileNameTmp = `${fileBase}.mjs`
    const fileUrl = `${pathToFileURL(fileBase)}.mjs`
    // 编译后代码写入 临时文件
    await fsp.writeFile(fileNameTmp, bundledCode)
    try {
      // 通过 ESM import 读取临时内容
      return (await dynamicImport(fileUrl)).default
    } finally {
      // 获取配置内容后删除临时内容
      fs.unlink(fileNameTmp, () => {})
    }
  }
  // CommonJS 处理方式
  else {
  }
}

而对于 CommonJS，采用的是 JIT 即时编译的方式

重写原生 require.entensions 方法，特殊处理 vite 配置文件
清除 require 缓存，调用 require 方法获取配置
恢复原生 require.entensions 方法

async function loadConfigFromBundledFile(
  fileName: string,
  bundledCode: string,
  isESM: boolean
): Promise<UserConfigExport> {
  if (isESM) {
  }
  // CommonJS 处理方式
  else {
    const extension = path.extname(fileName)
    const realFileName = await promisifiedRealpath(fileName)
    const loaderExt = extension in _require.extensions ? extension : '.js'
    // 默认拦截器
    const defaultLoader = _require.extensions[loaderExt]!
    // 通过拦截原生 require.extensions 的加载函数实现加载 bundle 后配置
    _require.extensions[loaderExt] = (module: NodeModule, filename: string) => {
      if (filename === realFileName) {
        // 特殊处理 vite 配置文件
        ;(module as NodeModuleWithCompile)._compile(bundledCode, filename)
      } else {
        defaultLoader(module, filename)
      }
    }
    // 清除 require 缓存
    delete _require.cache[_require.resolve(fileName)]
    // 调用 require 获取配置对象
    const raw = _require(fileName)
    // 恢复原生 require.extensions
    _require.extensions[loaderExt] = defaultLoader
    return raw.__esModule ? raw.default : raw
  }
}

之所以要做这样的区分，是因为 ESModule 在 Node 环境执行过程中需要手动加上 --experimental-loader 参数才能正常运行自定义 loader，所以要采用 AOP 编译这种 hack 的方式保证 ESModule 配置文件的正确执行。对于 CommonJS，可以直接注册一个自定义 loader 处理配置文件，所以通过拦截 require.extensions 来实现对打包后的配置文件的加载

小结一下获取配置文件这一步骤，通过入口方法 loadConfigFromFile 加载配置文件，经过获取配置文件的路径，判断配置文件类型之后，通过 bundleConfigFile 方法将配置文件打包成 js 代码，再通过 loadConfigFromBundledFile 方法解析配置参数

第二步：解析用户插件

在解析用户插件时，会先通过 apply 参数过滤出用户定义的插件，然后按照 pre、normal、post 获取三类用户插件

// 通过 apply 参数过滤出用户插件
const filterPlugin = (p: Plugin) => {
  if (!p) {
    return false
  } else if (!p.apply) {
    return true
  } else if (typeof p.apply === 'function') {
    return p.apply({ ...config, mode }, configEnv)
  } else {
    return p.apply === command
  }
}

// resolve plugins
const rawUserPlugins = (
  (await asyncFlatten(config.plugins || [])) as Plugin[]
).filter(filterPlugin)

// 对用户插件进行排序，获取 pre、normal、post 三类用户插件
const [prePlugins, normalPlugins, postPlugins] = sortUserPlugins(rawUserPlugins)

接下来根据 pre、normal、post 顺序，通过 runConfigHook 方法执行用户定义的插件

const userPlugins = [...prePlugins, ...normalPlugins, ...postPlugins]
config = await runConfigHook(config, userPlugins, configEnv)

async function runConfigHook(
  config: InlineConfig,
  plugins: Plugin[],
  configEnv: ConfigEnv
): Promise<InlineConfig> {
  let conf = config

  for (const p of getSortedPluginsByHook('config', plugins)) {
    const hook = p.config
    const handler = hook && 'handler' in hook ? hook.handler : hook
    if (handler) {
      const res = await handler(conf, configEnv)
      if (res) {
        conf = mergeConfig(conf, res)
      }
    }
  }

  return conf
}

这一步相对比较简单，就是获取用户定义的插件，然后依次执行就好

第三步：加载环境变量

加载环境变量的第一步是先通过 normalizePath 方法获取到环境变量文件地址，然后通过 loadEnv 方法获取环境变量

// 获取环境变量文件地址
const envDir = config.envDir
  ? normalizePath(path.resolve(resolvedRoot, config.envDir))
  : resolvedRoot
// 加载环境变量配置
const userEnv = loadEnv(mode, envDir, resolveEnvPrefix(config))

loadEnv 方法首先会读取 .env 文件配置，按照 .env -> .env.local -> .env.[mode] -> .env.[mode].local 的顺序依次读取配置文件，然后会读取 process.env 的配置

需要注意的是，不论是 .env 配置还是 process.env 配置，都需要以 VITE_ 开头

export function loadEnv(
  mode: string,
  envDir: string,
  prefixes: string | string[] = 'VITE_'
): Record<string, string> {
  prefixes = arraify(prefixes)
  const env: Record<string, string> = {}
  const envFiles = [
    /** default file */ `.env`,
    /** local file */ `.env.local`,
    /** mode file */ `.env.${mode}`,
    /** mode local file */ `.env.${mode}.local`,
  ]

  // 解析 .env 文件配置
  const parsed = Object.fromEntries(
    envFiles.flatMap((file) => {
      const filePath = path.join(envDir, file)
      if (!tryStatSync(filePath)?.isFile()) return []

      return Object.entries(parse(fs.readFileSync(filePath)))
    })
  )
  expand({ parsed })

  // 依次读取 .env 文件配置, .env.local 文件配置, .env.[mode] 文件配置, .env.[mode].local 文件配置，需要以 VITE_ 开头
  for (const [key, value] of Object.entries(parsed)) {
    if (prefixes.some((prefix) => key.startsWith(prefix))) {
      env[key] = value
    }
  }

  // 读取 process.env 配置,需要以 VITE_ 开头
  for (const key in process.env) {
    if (prefixes.some((prefix) => key.startsWith(prefix))) {
      env[key] = process.env[key] as string
    }
  }

  return env
}

第四步：构建解析对象

最终返回的 resolved 解析对象有非常多的属性和方法，这里单独介绍两个和依赖预构建相关的属性

第一个 cacheDir 是预构建产物缓存的目录，顺序为：自定义 cacheDir 配置 -> node_modules/.vite 目录 -> .vite 目录

// 解析依赖预构建的缓存目录
const cacheDir = normalizePath(
  config.cacheDir
    ? path.resolve(resolvedRoot, config.cacheDir)
    : pkgDir
      ? path.join(pkgDir, `node_modules/.vite`)
      : path.join(resolvedRoot, `.vite`)
)

第二个 createResolver 方法会创建一个创建模块解析器，用于解析模块的依赖关系和别名，处理依赖预构建，对于别名解析和实际模块解析会使用不同的 pluginContaier，最后统一调用插件容器的 resolveId 方法获取解析结果

const createResolver: ResolvedConfig['createResolver'] = (options) => {
  let aliasContainer: PluginContainer | undefined
  let resolverContainer: PluginContainer | undefined
  return async (id, importer, aliasOnly, ssr) => {
    let container: PluginContainer
    // 别名解析和实际模块解析使用不同的 container
    if (aliasOnly) {
      // 新建别名 container
      container =
        aliasContainer ||
        (aliasContainer = await createPluginContainer({
          ...resolved,
          plugins: [aliasPlugin({ entries: resolved.resolve.alias })],
        }))
    } else {
      // 新建解析 container
      container =
        resolverContainer ||
        (resolverContainer = await createPluginContainer({
          ...resolved,
          plugins: [
            aliasPlugin({ entries: resolved.resolve.alias }),
            resolvePlugin({
              ...resolved.resolve,
              root: resolvedRoot,
              isProduction,
              isBuild: command === 'build',
              ssrConfig: resolved.ssr,
              asSrc: true,
              preferRelative: false,
              tryIndex: true,
              ...options,
              idOnly: true,
            }),
          ],
        }))
    }
    return (
      // 调用插件容器的 resolveId 方法来查找给定模块 ID 的解析结果
      (
        await container.resolveId(id, importer, {
          ssr,
          scan: options?.scan,
        })
      )?.id
    )
  }
}

然后会创建一个 resolvedConfig 对象，resolvedConfig 包含在配置文件解析过程中新增的属性和方法，最后将 config 和 resolvedConfig 统一汇总到 resolved 对象

const resolvedConfig: ResolvedConfig = {
  // 配置文件的路径
  configFile: configFile ? normalizePath(configFile) : undefined,
  // 配置文件依赖的文件路径列表
  configFileDependencies: configFileDependencies.map((name) =>
    normalizePath(path.resolve(name))
  ),
  // 内联的配置对象（命令行配置）
  inlineConfig,
  // 项目根目录的绝对路径
  root: resolvedRoot,
  // 项目的基础路径
  base: resolvedBase.endsWith('/') ? resolvedBase : resolvedBase + '/',
  rawBase: resolvedBase, // 未经处理的项目基础路径
  // 模块解析选项
  resolve: resolveOptions,
  // 公共目录的绝对路径
  publicDir: resolvedPublicDir,
  // 缓存目录的绝对路径
  cacheDir,
  // 命令行命令
  command,
  // 运行模式（开发模式或生产模式）
  mode,
  // 是否作为 worker 运行
  isWorker: false,
  // 主配置文件，当前版本无效
  mainConfig: null,
  // 是否是生产环境
  isProduction,
  // 用户配置的插件列表
  plugins: userPlugins,
  // CSS 配置选项
  css: resolveCSSOptions(config.css),
  // esbuild 配置选项
  esbuild:
    config.esbuild === false
      ? false
      : {
          jsxDev: !isProduction,
          ...config.esbuild,
        },
  // 服务器配置选项
  server,
  // 构建配置选项
  build: resolvedBuildOptions,
  // 预览配置选项
  preview: resolvePreviewOptions(config.preview, server),
  // 环境变量目录的绝对路径
  envDir,
  // 环境变量的映射对象
  env: {
    ...userEnv,
    BASE_URL,
    MODE: mode,
    DEV: !isProduction,
    PROD: isProduction,
  },
  // 决定是否包含在构建的资源文件列表中
  assetsInclude(file: string) {
    return DEFAULT_ASSETS_RE.test(file) || assetsFilter(file)
  },
  // 日志记录器
  logger,
  // 包缓存
  packageCache,
  // 创建模块解析器的函数
  createResolver,
  // 优化依赖的选项
  optimizeDeps: {
    disabled: 'build',
    ...optimizeDeps,
    esbuildOptions: {
      preserveSymlinks: resolveOptions.preserveSymlinks,
      ...optimizeDeps.esbuildOptions,
    },
  },
  // Worker 配置选项
  worker: resolvedWorkerOptions,
  // 应用类型（SPA 或 SSR）
  appType: config.appType ?? (middlewareMode === 'ssr' ? 'custom' : 'spa'),
  // 获取排序后的插件列表的函数
  getSortedPlugins: undefined!,
  // 获取排序后的插件钩子列表的函数
  getSortedPluginHooks: undefined!,
}

// 解析后的对象统一放入 resolved 中
const resolved: ResolvedConfig = {
  ...config,
  ...resolvedConfig,
}

第五步：解析插件流水线

这一步首先首先通过 resolvePlugins 方法收集执行过程所有插件，主要分为五类插件

别名插件
用户自定义 pre 插件(带有enforce: "pre"属性)
vite 核心插件
Vite 生产环境插件 & 用户插件(带有 enforce: "post"属性)
开发特有插件

// 目录：packages/vite/src/node/plugins/index.ts

export async function resolvePlugins(
  config: ResolvedConfig,
  prePlugins: Plugin[],
  normalPlugins: Plugin[],
  postPlugins: Plugin[]
): Promise<Plugin[]> {
  const isBuild = config.command === 'build'
  const isWatch = isBuild && !!config.build.watch
  const buildPlugins = isBuild
    ? await (await import('../build')).resolveBuildPlugins(config)
    : { pre: [], post: [] }
  const { modulePreload } = config.build

  return [
    ...(isDepsOptimizerEnabled(config, false) ||
    isDepsOptimizerEnabled(config, true)
      ? [
          isBuild
            ? optimizedDepsBuildPlugin(config)
            : optimizedDepsPlugin(config),
        ]
      : []),
    isWatch ? ensureWatchPlugin() : null,
    isBuild ? metadataPlugin() : null,
    watchPackageDataPlugin(config.packageCache),
    // ===== 1. 别名插件 =====
    preAliasPlugin(config),
    aliasPlugin({ entries: config.resolve.alias }),
    // ===== 2. 用户自定义 pre 插件(带有`enforce: "pre"`属性) =====
    ...prePlugins,
    // ===== 3. vite 核心插件 =====
    modulePreload === true ||
    (typeof modulePreload === 'object' && modulePreload.polyfill)
      ? modulePreloadPolyfillPlugin(config)
      : null,
    resolvePlugin({
      ...config.resolve,
      root: config.root,
      isProduction: config.isProduction,
      isBuild,
      packageCache: config.packageCache,
      ssrConfig: config.ssr,
      asSrc: true,
      getDepsOptimizer: (ssr: boolean) => getDepsOptimizer(config, ssr),
      shouldExternalize:
        isBuild && config.build.ssr && config.ssr?.format !== 'cjs'
          ? (id, importer) => shouldExternalizeForSSR(id, importer, config)
          : undefined,
    }),
    htmlInlineProxyPlugin(config),
    cssPlugin(config),
    config.esbuild !== false ? esbuildPlugin(config) : null,
    jsonPlugin(
      {
        namedExports: true,
        ...config.json,
      },
      isBuild
    ),
    wasmHelperPlugin(config),
    webWorkerPlugin(config),
    assetPlugin(config),
    ...normalPlugins,
    wasmFallbackPlugin(),
    // ===== 4. Vite 生产环境插件 & 用户插件(带有 `enforce: "post"`属性) =====
    definePlugin(config),
    cssPostPlugin(config),
    isBuild && buildHtmlPlugin(config),
    workerImportMetaUrlPlugin(config),
    assetImportMetaUrlPlugin(config),
    ...buildPlugins.pre,
    dynamicImportVarsPlugin(config),
    importGlobPlugin(config),
    ...postPlugins,
    ...buildPlugins.post,
    // ===== 6. 开发特有插件 =====
    ...(isBuild
      ? []
      : [clientInjectionsPlugin(config), importAnalysisPlugin(config)]),
  ].filter(Boolean) as Plugin[]
}

获取所有插件之后，通过 createPluginHookUtils 方法添加插件操作工具函数，主要是获取排序后的插件和排序后的插件 hooks，这里单独封装的目的主要是将获取结果放到缓存中，提升性能

export function createPluginHookUtils(
  plugins: readonly Plugin[]
): PluginHookUtils {
  const sortedPluginsCache = new Map<keyof Plugin, Plugin[]>()

  // 获取排序后的插件
  function getSortedPlugins(hookName: keyof Plugin): Plugin[] {
    if (sortedPluginsCache.has(hookName))
      return sortedPluginsCache.get(hookName)!
    const sorted = getSortedPluginsByHook(hookName, plugins)
    sortedPluginsCache.set(hookName, sorted)
    return sorted
  }
  // 获取排序后插件 hooks
  function getSortedPluginHooks<K extends keyof Plugin>(
    hookName: K
  ): NonNullable<HookHandler<Plugin[K]>>[] {
    const plugins = getSortedPlugins(hookName)
    return plugins
      .map((p) => {
        const hook = p[hookName]!
        return typeof hook === 'object' && 'handler' in hook
          ? hook.handler
          : hook
      })
      .filter(Boolean)
  }

  return {
    getSortedPlugins,
    getSortedPluginHooks,
  }
}

最后再通过 Promise.all 方法，按顺序执行执行所有插件的 configResolved 钩子

await Promise.all([
  ...resolved
    .getSortedPluginHooks('configResolved')
    .map((hook) => hook(resolved)),
  ...resolvedConfig.worker
    .getSortedPluginHooks('configResolved')
    .map((hook) => hook(workerResolved)),
])

总结

最后总结一下 vite 解析配置文件的全过程，一共分为五个步骤

加载配置文件：获取配置文件路径后，通过 EsBuild 将配置文件打包成 js 代码，并根据配置文件是 ESM 还是 CommonJS 进行不同的解析操作
解析用户插件：过滤出用户插件之后，依次执行用户插件的 config 钩子
加载环境变量：依次加载 .env 配置文件和 process.env 中以 VITE_ 开头的环境变量
构建解析对象：包含配置文件解析过程中新增的属性和方法
解析插件流水线：获取所有插件后，并行执行插件的 configResolved 钩子