前端工程化 / 系统课时

处理包解析与重复依赖

处理包解析与重复依赖

本课解决两类常见故障:同一个包在不同环境进入了错误入口,以及 monorepo、软链接项目中同一运行时被加载多次。完成后,你能用 conditions、mainFields、dedupe 与 preserveSymlinks 建立可验证的解析策略。

学习目标

  • 区分“入口选错”和“包实例重复”两类问题
  • 理解条件导出、传统入口字段与符号链接身份的优先关系
  • 配置依赖去重,并按固定顺序验证开发和构建结果

先判断故障属于哪一类

包能被找到却运行异常,不一定是安装失败。若报错集中在浏览器 API、ESM/CJS 兼容或开发版与生产版差异,优先检查入口解析;若出现 Hook、上下文、状态容器或插件注册失效,则更像同一运行时存在多个实例。

现象 优先检查 典型原因
浏览器中加载了 Node 专用代码 conditions、包的 exports 条件分支与目标环境不匹配
包声明了多个传统入口却选错文件 mainFields 入口字段顺序不符合项目需要
上下文、单例或 Hook 跨包失效 dedupe 根项目与链接包各解析到一份依赖
开启软链接后模块身份变化 preserveSymlinks 原始链接路径与真实路径被视为不同身份

Vite 包入口选择与模块身份判定流程

理解入口解析的优先级

现代包通常通过 package.json 的 exports 声明条件导出。resolve.conditions 用来补充允许命中的条件;当 exports 已成功解析入口时,resolve.mainFields 不再参与。只有包没有可用的 exports 入口时,Vite 才按 mainFields 的顺序尝试传统字段。

下面是一个用于说明的包清单片段。它不是应用配置,而是被依赖包可能提供的声明:

json
{
  "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 为依赖或对等依赖”的场景。自定义条件只应添加项目真实需要的值;不要用它强行绕过包作者声明的兼容边界。

ts
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 会按新解析规则重新预构建依赖。

bash
rm -rf node_modules/.vite
npm run dev -- --force

预期输出

text
VITE v<VERSION>  ready in <TIME> ms

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

停止开发服务器后执行构建:

bash
npm run build

预期输出

text
vite v<VERSION> building for production...
✓ <COUNT> modules transformed.
✓ built in <TIME>

浏览器中还应确认原有的重复实例症状消失。若构建成功但运行时问题仍在,检查链接包是否把单例运行时错误地放进 dependencies,以及包管理器锁文件中是否存在不兼容的主版本。

按固定顺序排查

先查看出问题包的 exports,确认目标分支名称和文件格式;再检查是否真的需要覆盖 conditions 或 mainFields。入口正确后,才处理重复实例:核对根项目与工作区包的依赖声明,给有单例语义的包配置 dedupe,最后评估符号链接身份。

不要同时大范围修改四个选项。每次只改变一个解析变量,并在开发与构建两种模式下验证,否则很难判断修复来自哪一项。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理包解析与重复依赖

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

登录哪都通