前端工程化 / 系统课时

处理 monorepo 链接包

处理 monorepo 链接包

本课建立一套可复用的 monorepo 链接包处理顺序:先确认包入口与模块格式,再决定是否预构建,最后统一共享依赖并清理缓存。完成后,你能解决工作区源码不热更新、条件导出选错入口、React 或 Vue 重复实例以及链接切换后缓存过期等问题。

学习目标

  • 判断链接包应作为源码处理还是强制进入依赖预构建
  • 正确配置条件导出、软链接解析和共享依赖去重
  • 用缓存重建与依赖树检查验证修复结果

建立故障定位模型

Vite 默认把不从 node_modules 解析到的工作区链接包视为源码,不会直接预构建该包,而会继续分析它引用的依赖。这要求链接包能够以 ESM 形式被浏览器开发链路处理;如果它只发布 CommonJS,才需要通过 optimizeDeps.include 强制预构建。

条件导出决定实际读取 src 还是 dist,软链接策略决定模块身份,共享依赖的安装位置决定是否产生多个运行时实例。这四个环节互相影响,排查时应按“入口、模块格式、模块身份、缓存”顺序处理。

Vite monorepo 链接包解析与预构建路径

先修正链接包边界

工作区源码包应声明 ESM,并把共享框架放入 peerDependencies,避免包内再安装一份运行时。需要在开发期直接读取源码时,可以增加自定义 source 条件,同时保留构建产物作为普通消费入口。

json
{
  "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 依赖,可以使用 父依赖 > 子依赖 语法只预构建嵌套依赖。

ts
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、工作区链接关系或包入口后,都应强制重新优化。

bash
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

预期结果是前两行解析路径完全相同,随后开发服务器重新启动。路径、版本、耗时和端口会因环境而不同。

text
<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 会按未跟随软链接的原始路径识别模块,可能让同一文件通过真实路径与链接路径形成两个模块身份,除非包管理或调试工具明确要求,否则不要把它当作通用修复。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理 monorepo 链接包

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

登录哪都通