Vite 依赖预构建为什么会因条件导出重复

我在排查 Vite 开发服务器反复重新预构建时，最容易误判的一点是：看到同一个依赖出现两次，就马上删除 node_modules/.vite。缓存确实会放大现象，但条件导出更常见的根因是，同一个包名在不同解析条件下落到了不同入口，Vite 于是无法把它们当成一个稳定的预构建对象。

Vite 的依赖预构建只发生在开发模式，主要为 CommonJS/UMD 转成 ESM，并把内部模块较多的 ESM 依赖合并，减少浏览器请求数。排查时要把“重复的网络请求”“重复的依赖入口”和“重复生成缓存”分开看。

官方地址：https://vite.dev/guide/dep-pre-bundling.html

真正有效的处理顺序是先确认条件导出造成了哪些入口分叉，再统一源码和插件的导入方式；只有入口已经稳定后，才用 optimizeDeps 或 --force 处理预构建范围和缓存。

先判断重复到底发生在哪里

我通常先把问题限定在开发服务器：如果生产构建没有类似现象，优先检查依赖预构建和浏览器缓存，不要立刻改生产打包配置。Vite 会自动扫描源码中的 bare import，找到新的依赖后可能重新运行预构建并刷新页面。

可以先记录三件事：重复项的包名是否完全相同、两次请求的路径是否不同、日志中是否伴随“重新生成依赖缓存”。如果包名相同但入口分别是 ESM 与浏览器分支，这不是简单的请求重复，而是解析条件已经分叉。

排查记录
包名：example-lib
入口 A：dist/index.mjs
入口 B：dist/browser.mjs
出现位置：应用源码 / 插件转换结果
现象：开发服务器重新预构建

上面只是记录模板，不是运行输出。关键是把“来源入口”写清楚，后面的配置才不会变成盲目加白名单。

沿着 package.json 的 exports 看解析分叉

条件导出允许一个包根据环境、导入方式或自定义条件选择不同文件。Node.js 文档说明，条件对象的键顺序有意义，较具体的条件应放在前面，并建议保留 default 作为通用回退。Vite、插件和浏览器侧工具对条件的组合不一定完全相同，于是同一个包名可能被解析到不同目标。

{
  "exports": {
    ".": {
      "browser": "./dist/browser.mjs",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.mjs"
    }
  }
}

这个声明本身没有“必然错误”，但它提醒我们不要用文件路径深度导入绕开包的公开入口，也不要让应用源码和插件各自声明不同的解析条件。一个入口走 browser，另一个入口走 import，就可能让预构建看到两个不同模块。

统一应用和插件使用的依赖入口

在我实际修复时，最稳的一步不是先写复杂配置，而是先统一入口：应用代码使用包名或包文档推荐的公开子路径，插件转换后的代码也尽量保持同一入口，不要一边导入 example-lib，一边直接导入 example-lib/dist/browser.mjs。

对于“插件生成的 import 初始扫描不到”的情况，Vite 官方建议使用 optimizeDeps.include 明确纳入预构建。这个配置解决的是发现范围，不是替换包的条件导出规则。

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    include: [
      // 插件转换后才出现的公开依赖入口，明确纳入开发预构建
      'example-lib'
    ]
  }
})

如果依赖本身是 CommonJS，或者内部模块很多，纳入预构建通常更有价值；如果它是小型、有效的 ESM 依赖，让浏览器直接加载可能更合适。配置时只写实际需要的包名，不要把整个依赖树都塞进 include。

不要把 exclude 当成万能去重开关

optimizeDeps.exclude 适合把已经是有效 ESM、且不需要 Vite 预构建的依赖排除出去。它不适合用来掩盖一个包存在两个条件入口的问题。若包仍然通过不同路径被引用，排除后只会把解析工作交给浏览器或后续转换，重复现象可能换一种形式出现。

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: [
      // 仅排除已经确认是小型、有效 ESM 的依赖
      'small-esm-lib'
    ]
  }
})

这里的判断边界是：CommonJS 依赖通常不要随意排除；有效 ESM 小包才有排除的候选空间；条件导出混乱时先修入口和包声明，再决定是否排除。

清理预构建缓存，但要放在最后

Vite 会把预构建依赖放在 node_modules/.vite，并根据锁文件、补丁目录时间、相关 Vite 配置和 NODE_ENV 判断是否需要重建。入口或配置已经修正后，可以用 --force 让开发服务器重新生成缓存。

# 强制重新生成开发依赖缓存，用于验证入口修正是否生效
npx vite --force

也可以手动删除 node_modules/.vite 后重新启动，但我更倾向先用 --force，因为它把“重新生成”表达得更明确。浏览器还会强缓存已解析的依赖请求，必要时配合开发者工具临时关闭缓存再刷新。

monorepo 链接包要单独看 ESM 边界

如果依赖来自 monorepo，Vite 会识别没有从 node_modules 解析到的链接包，并把它作为源码处理，再分析它自己的依赖。这个路径要求链接包以 ESM 形式导出；如果不是，可以把它加入 optimizeDeps.include，然后重启开发服务器。

因此，重复预构建的最后一个检查点是链接包的公开入口：应用是否按包名导入、包的 exports 是否提供稳定的 ESM 分支、插件是否又生成了另一种深层路径。三处一致后，缓存重建才有意义。

我的发布前检查顺序

1. 确认现象只发生在 Vite 开发模式，记录重复包名和实际入口。
2. 打开依赖的 package.json，按条件顺序比较 browser、import、require 与 default。
3. 统一应用源码、插件转换结果和 monorepo 链接包的公开导入入口。
4. 只有插件生成的依赖无法被初始扫描时，才添加精确的 optimizeDeps.include。
5. 只有确认是有效 ESM 小包时，才考虑 optimizeDeps.exclude。
6. 最后用 --force 重新生成 node_modules/.vite，再观察是否仍有入口分叉。

这套顺序的好处是每一步都有明确对象：条件导出负责解释“为什么不同”，入口统一负责减少“从哪里来”，optimizeDeps 负责补充“是否预构建”，缓存清理负责验证“旧结果是否还在”。

相关问题

Vite 依赖预构建只影响生产构建吗？

不会。Vite 官方文档明确把依赖预构建描述为开发模式行为，生产构建应按另一套构建配置排查。

什么时候优先写 optimizeDeps.include？

当依赖是插件转换后才出现、初始源码扫描发现不了，但又需要在开发启动阶段稳定预构建时，优先考虑精确的 include。

删除 node_modules/.vite 能解决条件导出重复吗？

它只能清掉旧的预构建缓存。如果源码和插件仍然走不同条件入口，缓存重建后重复仍可能出现，所以它应该是最后一步。