前端工程化 / 系统课时
理解配置加载方式
理解配置加载方式
本课解释 Vite 如何读取配置文件,以及为什么同一份配置在普通项目、TypeScript 项目和 monorepo 中可能表现不同。完成后,你能根据报错位置切换加载器,并判断问题来自打包转换、模块格式还是运行时能力。
学习目标
- 区分
bundle、runner与native的加载链路 - 为 TypeScript、CJS 和 monorepo 配置选择合适加载器
- 按固定顺序定位配置无法加载或修改不生效的问题
三种加载器的工作方式
当前 Vite 默认使用 bundle:先用 Rolldown 将配置及相关依赖打成临时文件,再交给运行时加载。runner 不生成临时配置包,而是通过模块运行器按需转换文件;native 则让当前运行时直接加载配置。:contentReference[oaicite:1]{index=1}

bundle 兼容性最好,适合作为默认选项,但打包边界可能放大 monorepo 中跨包导入 TypeScript 文件的问题。runner 更接近源码模块关系,适合排查这类问题,不过配置文件本身不能使用 CJS;外部 CJS 包通常仍可正常使用。native 最接近真实运行时,但 TypeScript 配置要求运行时具备相应支持,而且配置导入模块发生变化时,开发服务器不会自动重启。:contentReference[oaicite:2]{index=2}
用同一配置验证三种方式
为了让三个命令都可直接运行,先把配置写成原生 ESM JavaScript。项目仍需包含标准 Vite 入口文件。
// vite.config.mjs
export default {
build: {
outDir: 'dist',
emptyOutDir: true,
},
}依次执行三次构建:
npx vite build --config vite.config.mjs --configLoader bundle
npx vite build --config vite.config.mjs --configLoader runner
npx vite build --config vite.config.mjs --configLoader native预期输出
vite v<VERSION> building for production...
✓ <N> modules transformed.
dist/index.html <SIZE>
dist/assets/<ID>.js <SIZE>
✓ built in <TIME>
以上成功构建流程会出现 3 次。动态版本、模块数、文件名、体积和耗时可能不同。三个命令得到相同产物,说明当前配置不依赖 TypeScript 转换或特殊模块互操作;真正的差异通常会在配置导入其他文件时出现。
按场景选择加载器
普通单仓库项目优先保留默认 bundle,不要为了“更原生”主动增加变量。只有当报错堆栈指向临时配置文件、跨工作区 TypeScript 导入解析异常,或配置依赖被错误内联时,再切换到 runner 比较结果。
配置文件或其本地依赖使用 CommonJS 时,优先使用 bundle,或者把本地配置迁移为 ESM。若选择 native,应先确认当前 Node.js 或其他运行时能够直接理解配置文件扩展名与语法;否则常见结果是未知 .ts 扩展名或语法解析失败。
典型故障的定位顺序
先使用默认加载器复现并保留完整错误,再只改变 --configLoader,不要同时修改配置内容。若 runner 成功而 bundle 失败,重点检查 monorepo 跨包 TypeScript 导入、路径别名和配置依赖的打包边界。
若 bundle 成功而 runner 失败,检查 vite.config 及其本地依赖是否使用 require、module.exports 或其他 CJS 写法。若 native 无法读取 .ts,说明当前运行时没有直接加载该 TypeScript 配置的能力,应退回 bundle 或 runner。
使用 native 启动开发服务器后,如果只修改了被配置文件导入的辅助模块而服务器没有重启,这是该方式的已知边界。手动重启服务,或改用能追踪这些依赖变化的加载方式。:contentReference[oaicite:3]{index=3}