前端工程化 / 系统课时

配置 include 与 exclude

配置 include 与 exclude

默认依赖扫描通常无需人工干预,但插件转换、动态导入和 Monorepo 链接包可能让依赖在启动扫描阶段缺席。本课用一份可复用配置说明 include 与 exclude 的选择标准、验证方法和最容易踩中的边界。

学习目标

  • 判断依赖应强制预构建还是绕过预构建
  • 正确配置直接依赖、链接包和嵌套 CommonJS 依赖
  • 通过强制重新优化验证配置是否消除重复重载

先判断使用 include 还是 exclude

optimizeDeps.include 表示即使自动扫描没有发现,也要把指定依赖加入预构建。适合插件转换后才出现的导入、位于 node_modules 之外的链接包,以及模块数量很多或需要 CommonJS 兼容处理的依赖。

optimizeDeps.exclude 表示让依赖绕过预构建,由浏览器按原始 ESM 形式加载。它只适合体积较小、已经是有效 ESM 且没有 CommonJS 兼容需求的包。CommonJS 依赖不应放入 exclude。

情况 建议配置 原因
首屏之后才发现的大型依赖 include 提前完成预构建,避免运行中再次优化
Monorepo 中未从 node_modules 解析的内部包 视模块格式使用 include 非标准链接路径可能不会默认预构建
小型、原生 ESM 依赖 可考虑 exclude 让浏览器直接加载,减少不必要的预构建
CommonJS 或 UMD 依赖 include 或保持默认 需要转换为开发环境可消费的 ESM

编写主配置

下面是完整的 vite.config.ts 示例。包名用于展示三种关系,落地时应替换为项目实际安装的依赖名称。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    include: [
      '@acme/internal-ui',
      'feature-shell > legacy-cjs-runtime',
    ],
    exclude: ['tiny-esm-helper'],
  },
})

配置生效后,@acme/internal-ui 会被强制加入预构建;feature-shell > legacy-cjs-runtime 表示即使外层 ESM 依赖未参与优化,也要单独预构建其嵌套 CommonJS 依赖;tiny-esm-helper 则由浏览器直接加载。

这里的 > 不是 Shell 重定向符,而是 Vite 配置字符串中的依赖链表达方式。必须保留在引号内,并使用实际的父依赖与子依赖包名。

处理三类典型问题

插件转换后才出现的依赖

某些插件会把虚拟模块或模板语法转换成真实导入。初始源码扫描看不到最终包名,浏览器请求转换结果后才暴露依赖,开发服务器可能立刻重新优化并刷新页面。将该大型依赖加入 include,可以把工作提前到启动阶段。

Monorepo 内部链接包

Vite 通常把不从 node_modules 解析的链接包当作源码处理。如果内部包已经输出标准 ESM,这通常是正确行为;如果它仍包含 CommonJS,或内部模块数量很多,可将包名加入 include。修改链接关系后还要使用 --force,避免继续复用旧缓存。

排除项包含嵌套 CommonJS

一个包本身可能是 ESM,但内部依赖仍是 CommonJS。若外层包确实需要 exclude,应把嵌套 CommonJS 依赖用 父包 > 子包 写法加入 include。否则可能出现命名导入失败、导出对象结构异常或启动后再次优化。

强制重新优化并验证

修改 optimizeDeps 后重启开发服务器。为避免旧缓存干扰,本次验证直接强制重新优化。

bash
npm run dev -- --force

预期输出如下,实际版本、耗时和端口可能不同。

text
Forced re-optimization of dependencies

VITE v<VERSION>  ready in <TIME> ms

Local: http://localhost:<PORT>/

随后依次访问首屏、懒加载路由和会触发插件转换的页面。正确结果是页面功能正常,终端不会在每次访问时重复触发依赖优化,也不会因为同一个依赖反复整页刷新。若问题仍在,先核对配置中的包名是否与锁文件解析出的名称一致。

常见错误与修正

不要为了“启动更快”把大量包全部加入 include。强制预构建过多依赖会增加冷启动工作量,应只处理扫描遗漏、链接包兼容或明显的多模块依赖。

不要把 CommonJS 包加入 exclude。这会绕过本应执行的格式转换。若不确定包的发布格式,可查看其 package.json 中的 type、module、main 与 exports,并以实际解析入口为准。

浏览器缓存也可能掩盖配置变化。使用 --force 后若页面仍表现异常,可在开发者工具中临时禁用 Network 缓存并刷新,但完成排查后应恢复默认缓存设置,否则会把浏览器缓存关闭造成的慢加载误判为 Vite 性能问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 include 与 exclude

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通