前端工程化 / 系统课时
处理包解析与重复依赖
处理包解析与重复依赖
本课解决两类常见故障:同一个包在不同环境进入了错误入口,以及 monorepo、软链接项目中同一运行时被加载多次。完成后,你能用 conditions、mainFields、dedupe 与 preserveSymlinks 建立可验证的解析策略。
学习目标
- 区分“入口选错”和“包实例重复”两类问题
- 理解条件导出、传统入口字段与符号链接身份的优先关系
- 配置依赖去重,并按固定顺序验证开发和构建结果
先判断故障属于哪一类
包能被找到却运行异常,不一定是安装失败。若报错集中在浏览器 API、ESM/CJS 兼容或开发版与生产版差异,优先检查入口解析;若出现 Hook、上下文、状态容器或插件注册失效,则更像同一运行时存在多个实例。
| 现象 | 优先检查 | 典型原因 |
|---|---|---|
| 浏览器中加载了 Node 专用代码 | conditions、包的 exports |
条件分支与目标环境不匹配 |
| 包声明了多个传统入口却选错文件 | mainFields |
入口字段顺序不符合项目需要 |
| 上下文、单例或 Hook 跨包失效 | dedupe |
根项目与链接包各解析到一份依赖 |
| 开启软链接后模块身份变化 | preserveSymlinks |
原始链接路径与真实路径被视为不同身份 |

理解入口解析的优先级
现代包通常通过 package.json 的 exports 声明条件导出。resolve.conditions 用来补充允许命中的条件;当 exports 已成功解析入口时,resolve.mainFields 不再参与。只有包没有可用的 exports 入口时,Vite 才按 mainFields 的顺序尝试传统字段。
下面是一个用于说明的包清单片段。它不是应用配置,而是被依赖包可能提供的声明:
{
"name": "example-runtime",
"exports": {
".": {
"source": "./src/index.js",
"browser": "./dist/browser.js",
"default": "./dist/index.js"
}
},
"browser": "./dist/browser-legacy.js",
"module": "./dist/index.mjs",
"main": "./dist/index.cjs"
}当 source 条件被允许且包提供该分支时,会优先进入 ./src/index.js;否则继续匹配其他可用条件。browser、module、main 这些传统字段只在条件导出没有解决入口时才有意义。
配置入口选择与依赖去重
下面配置适合“应用引用工作区组件包,而组件包又声明了 React 为依赖或对等依赖”的场景。自定义条件只应添加项目真实需要的值;不要用它强行绕过包作者声明的兼容边界。
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
// 保留常用客户端条件,并允许工作区包优先暴露源码入口。
conditions: ['source', 'module', 'browser', 'development|production'],
mainFields: ['browser', 'module', 'main'],
// 强制这些有单例语义的运行时从项目根目录解析。
dedupe: ['react', 'react-dom'],
// 默认跟随真实路径,通常更利于把软链接包识别为同一模块。
preserveSymlinks: false,
},
})dedupe 改变的是 Vite 的解析结果,不会删除包管理器磁盘上的重复目录。preserveSymlinks: false 会按跟随软链接后的真实路径判定模块身份;只有确实依赖链接原始路径或特殊包管理布局时,才考虑改为 true,并重新检查是否产生多实例。
验证配置是否真正生效
先清理 Vite 依赖缓存,再分别启动开发服务器和生产构建。缓存清理后,Vite 会按新解析规则重新预构建依赖。
rm -rf node_modules/.vite
npm run dev -- --force预期输出
VITE v<VERSION> ready in <TIME> ms
➜ Local: http://localhost:<PORT>/停止开发服务器后执行构建:
npm run build预期输出
vite v<VERSION> building for production...
✓ <COUNT> modules transformed.
✓ built in <TIME>浏览器中还应确认原有的重复实例症状消失。若构建成功但运行时问题仍在,检查链接包是否把单例运行时错误地放进 dependencies,以及包管理器锁文件中是否存在不兼容的主版本。
按固定顺序排查
先查看出问题包的 exports,确认目标分支名称和文件格式;再检查是否真的需要覆盖 conditions 或 mainFields。入口正确后,才处理重复实例:核对根项目与工作区包的依赖声明,给有单例语义的包配置 dedupe,最后评估符号链接身份。
不要同时大范围修改四个选项。每次只改变一个解析变量,并在开发与构建两种模式下验证,否则很难判断修复来自哪一项。