前端工程化 / 系统课时
处理 monorepo 链接包
处理 monorepo 链接包
本课建立一套可复用的 monorepo 链接包处理顺序:先确认包入口与模块格式,再决定是否预构建,最后统一共享依赖并清理缓存。完成后,你能解决工作区源码不热更新、条件导出选错入口、React 或 Vue 重复实例以及链接切换后缓存过期等问题。
学习目标
- 判断链接包应作为源码处理还是强制进入依赖预构建
- 正确配置条件导出、软链接解析和共享依赖去重
- 用缓存重建与依赖树检查验证修复结果
建立故障定位模型
Vite 默认把不从 node_modules 解析到的工作区链接包视为源码,不会直接预构建该包,而会继续分析它引用的依赖。这要求链接包能够以 ESM 形式被浏览器开发链路处理;如果它只发布 CommonJS,才需要通过 optimizeDeps.include 强制预构建。
条件导出决定实际读取 src 还是 dist,软链接策略决定模块身份,共享依赖的安装位置决定是否产生多个运行时实例。这四个环节互相影响,排查时应按“入口、模块格式、模块身份、缓存”顺序处理。

先修正链接包边界
工作区源码包应声明 ESM,并把共享框架放入 peerDependencies,避免包内再安装一份运行时。需要在开发期直接读取源码时,可以增加自定义 source 条件,同时保留构建产物作为普通消费入口。
{
"name": "@acme/ui",
"version": "1.0.0",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"source": "./src/index.ts",
"import": "./dist/index.js",
"default": "./dist/index.js"
}
},
"peerDependencies": {
"react": "^19.0.0"
}
}该配置不是独立命令,不产生控制台输出。验证方法是在应用中导入 @acme/ui,启动开发服务器后修改 packages/ui/src/index.ts;命中 source 条件时,页面应收到模块热更新,而不是继续读取旧的 dist 文件。
配置解析、去重与预构建
应用侧通过 resolve.conditions 启用 source 条件,通过 resolve.dedupe 强制共享运行时从项目根目录解析。resolve.preserveSymlinks 默认是 false,会按软链接解析后的真实路径确定文件身份,通常更适合工作区源码。
只有无法作为 ESM 源码处理的链接包才加入 optimizeDeps.include。若 ESM 链接包内部存在无法被初始扫描发现的 CommonJS 依赖,可以使用 父依赖 > 子依赖 语法只预构建嵌套依赖。
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
conditions: ['source', 'module', 'browser', 'development|production'],
dedupe: ['react', 'react-dom'],
preserveSymlinks: false,
},
optimizeDeps: {
include: [
'legacy-linked-cjs',
'@acme/ui > cjs-only-helper',
],
},
})这份配置的生效结果是:@acme/ui 继续按源码参与转换和 HMR,legacy-linked-cjs 与指定的嵌套 CommonJS 依赖进入预构建,React 与 React DOM 始终解析到根项目的一份副本。不要为了“更快”把所有工作区源码包都加入 include,否则源码修改可能需要重启并强制重建缓存。
清理旧缓存并检查重复实例
Vite 的优化缓存会根据锁文件和相关配置失效,但普通链接或取消链接不一定触发自动重建。每次改变 npm link、工作区链接关系或包入口后,都应强制重新优化。
node --input-type=module -e "import { createRequire } from 'node:module'; const root = createRequire(import.meta.url); const ui = createRequire(new URL('./packages/ui/package.json', import.meta.url)); console.log(root.resolve('react')); console.log(ui.resolve('react'))"
npm exec vite -- --force预期结果是前两行解析路径完全相同,随后开发服务器重新启动。路径、版本、耗时和端口会因环境而不同。
<REACT_PATH>
<REACT_PATH>
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/若依赖树仍出现两份 React 或 Vue,先检查链接包是否错误地把框架放进 dependencies,再检查锁文件和包管理器的提升结果。若入口始终落到 dist,检查 exports 中条件顺序和应用的 resolve.conditions。若 HMR 失效但刷新后正常,确认该源码包没有被误加入 optimizeDeps.include。
风险与边界
resolve.dedupe 主要解决客户端开发和常规构建中的重复副本;SSR 的 ESM 输出还需要单独验证模块加载行为。启用 preserveSymlinks: true 会按未跟随软链接的原始路径识别模块,可能让同一文件通过真实路径与链接路径形成两个模块身份,除非包管理或调试工具明确要求,否则不要把它当作通用修复。