Vite resolve.dedupe 使用教程

本文介绍 Vite 中 resolve.dedupe 的作用、适用场景、配置方式，以及与其他依赖治理手段的配合关系。

---

1. 它是什么

resolve.dedupe 是 Vite 的模块解析配置项，用于强制指定依赖在构建时只使用一份实例。

配置位置：

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    dedupe: ['package-name'],
  },
});

当代码中出现 import ... from 'package-name' 时，Vite 会优先从项目根 node_modules（当前应用的直接依赖）查找，而不是使用嵌套在间接依赖里的另一份副本。

---

2. 为什么需要它

2.1 依赖可能被安装多份

在使用 pnpm、yarn workspaces 或 monorepo 时，同一个包名可能同时存在多份物理路径：

my-app/node_modules/foo-lib          → 2.0.0（直接依赖）
node_modules/.pnpm/.../bar-lib/.../    → 1.x（bar-lib 的间接依赖）

在业务中代码按 2.0 API 编写，但 Vite 在预构建（optimizeDeps）或打包时若解析到 1.x，就会在运行时出现 API 不兼容。

2.2 典型症状

现象	可能原因
xxx is not a function	加载了错误版本的包
React / Vue hooks 报错	框架被实例化两次
Pinia / Router 状态异常	单例库存在多份
主题 / 上下文错乱	UI 库被重复加载
包体积异常增大	同一依赖被打进 bundle 两次

2.3 dedupe 不做什么

• 不能自动把旧版本升级到新版本，只决定「用哪一份」
• 不能 替代依赖版本治理（仍需在 package.json 或包管理器 overrides 中统一版本）
• 不建议给所有依赖都加，只针对已知会重复或必须单例的包

---

3. 基本用法

3.1 单个包

export default defineConfig({
  resolve: {
    dedupe: ['vue'],
  },
});

3.2 多个包

export default defineConfig({
  resolve: {
    dedupe: ['vue', 'vue-router', 'pinia'],
  },
});

3.3 在 monorepo 子应用中配置

子应用通常有独立的 vite.config.ts，在子应用内配置即可：

// packages/admin/vite.config.ts
export default defineConfig({
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
});

3.4 与 resolve.alias 的区别

配置	作用
dedupe	多个合法路径指向同一包时，优先用根目录那一份
alias	把导入路径硬映射到指定文件或目录

dedupe 不改变 import 路径，只影响「同名包选哪一份」；alias 则直接替换解析目标。多数重复依赖问题优先用 dedupe + 版本统一，不必滥用 alias。

---

4. 与包管理器 overrides 的配合

dedupe 作用于构建解析阶段 ；包管理器的 overrides 作用于安装阶段。两者职责不同，建议组合使用。

手段	作用阶段	职责
pnpm overrides / npm overrides	安装依赖时	强制全仓库只安装一个版本
vite dedupe	开发 / 构建解析时	强制模块图里只引用一份实例

4.1 pnpm overrides 示例

# pnpm-workspace.yaml 或 package.json
overrides:
  'some-lib': '2.0.0'

4.2 推荐修复顺序

1. 在 package.json 中声明目标版本
2. 用 overrides 统一间接依赖版本
3. 对仍可能重复解析的包，在 vite.config.ts 中加 dedupe
4. 重启 dev server，必要时清理 Vite 缓存

---

5. 教学案例：@antv/layout 多版本冲突

@antv/layout 是 AntV 生态中的图布局算法库，@antv/g6 等包会间接依赖它。由于 1.x 与 2.0 存在破坏性 API 变更 ，多版本并存时极易在 Vite 项目中踩坑。以下以该库为例，说明 dedupe 的实际价值。

5.1 背景

假设某 Vite 应用在 package.json 中直接声明了 @antv/layout@2.0.0，页面里使用环形布局：

// src/pages/GraphDemo.vue
import { CircularLayout } from '@antv/layout';

async function applyCircularLayout(
  nodes: Array<{ id: string }>,
  center: [number, number],
) {
  const layoutData = { nodes };
  const layout = new CircularLayout({
    center,
    radius: Math.max(16 * nodes.length, 64),
  });

  await layout.execute(layoutData);

  const positions = new Map<string, { x: number; y: number }>();
  layout.forEachNode((node) => {
    positions.set(String(node.id), { x: node.x, y: node.y });
  });
  layout.destroy();

  return positions;
}

这是 2.0 的标准写法：

• 入参为 { nodes, edges? } 普通对象
• execute() 返回 Promise<void>
• 坐标通过 forEachNode 读取 node.x / node.y

与此同时，项目中还安装了 @antv/g6-extension-3d 等扩展包，它们在其 package.json 中声明了 @antv/layout@1.2.14-beta.8。pnpm 安装后，可能出现两份物理路径：

my-app/node_modules/@antv/layout              → 2.0.0（直接依赖）
node_modules/.pnpm/.../g6-extension-3d/.../   → 1.x（间接依赖）

业务代码按 2.0 编写，但 Vite 预构建时若解析到 1.x，就会在运行时调用旧版内部逻辑。

5.2 报错表现

用户在页面上触发环形布局后，控制台出现：

TypeError: graph.getAllNodes is not a function
    at CircularLayout.genericCircularLayout (circular.js:46)

分析：

线索	含义
genericCircularLayout	1.x 内部方法名，2.0 已重构为 BaseLayout 体系
graph.getAllNodes()	1.x 要求传入 @antv/graphlib 的 Graph 实例
业务传入 { nodes: [...] }	符合 2.0 API，但与 1.x 不兼容
类型检查可能正常	TypeScript 解析的是 2.0 类型，运行时却加载了 1.x 实现

结论：这不是业务逻辑写错，而是构建时模块解析到了错误版本。

5.3 API 差异速览

维度	1.2.x	2.0.0
图数据入参	@antv/graphlib 的 Graph	{ nodes, edges? }
执行方法	execute(graph) 返回 LayoutMapping	execute(data) 返回 void
读取坐标	result.nodes[i].data.x	layout.forEachNode(n => n.x)
旧版同步 API	layout({ nodes })（0.x）	已移除

5.4 解决步骤

第一步：版本统一（根因）

在 monorepo 中可通过 pnpm-workspace.yaml 集中治理：

# pnpm-workspace.yaml
overrides:
  '@antv/layout': '2.0.0'

或在单仓库的 package.json 中：

{
  "pnpm": {
    "overrides": {
      "@antv/layout": "2.0.0"
    }
  }
}

执行 pnpm install 后，检查 lockfile 中是否只剩 @antv/layout@2.0.0：

rg "@antv/layout@" pnpm-lock.yaml

第二步：构建解析兜底

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    dedupe: ['@antv/layout'],
  },
});

第三步：重启开发服务

pnpm dev

# 若仍异常，清理预构建缓存后重试
rm -rf node_modules/.vite
pnpm dev

完成后，GraphDemo.vue 中的 2.0 API 应与运行时行为一致，环形布局可正常计算节点坐标。

---

6. 常见适用包

以下依赖在 monorepo + pnpm 中较常需要 dedupe：

包名	原因
vue	避免双 Vue 实例导致 composable / 组件异常
vue-router	与 Vue 单例配套
pinia	全局 store 必须单例
@vue/runtime-core	Vue 内部运行时
react / react-dom	React 生态同理
styled-components	多实例会导致样式上下文失效
带全局状态的 UI 库	多实例会导致主题、上下文错乱
@antv/layout	G6 扩展包可能锁定 1.x，与直接依赖的 2.0 冲突
存在多版本的工具库	状态管理、图表等间接依赖版本分裂

---

7. 排查清单

遇到「代码和类型都对，但运行行为像旧版本」时，可按下面步骤排查：

1. 确认直接依赖版本

 cat node_modules/<package>/package.json | grep '"version"'

2. 检查 lockfile 是否仍有多版本

 # pnpm
 rg '"<package>@' pnpm-lock.yaml

 # npm
 npm ls <package>

3. 确认 Vite 配置已生效 检查 vite.config.ts 中 resolve.dedupe 是否包含目标包名。
4. 清理缓存并重启

 rm -rf node_modules/.vite
 pnpm dev

5. 在浏览器 DevTools 中定位实际加载的模块 查看报错栈中的函数名、文件名，对照不同版本的 API 差异，判断运行时究竟加载了哪一版。

---

8. 最佳实践

1. 优先治理依赖版本 ，dedupe 是构建阶段兜底，不是万能药。
2. 只 dedupe 必要的包，避免过度配置掩盖真实的依赖冲突。
3. 改完 overrides / dedupe 后务必重启 dev server，Vite 预构建缓存不会自动失效。
4. 在团队文档中记录 ：为何某个包需要 dedupe，方便后续维护者理解。
5. 不要用它替代正常的 semver 管理：长期应通过升级间接依赖或换包解决版本分裂。

---

9. 快速决策表

情况	建议
lockfile 只有一个版本，但仍报双实例	加 dedupe
lockfile 有多个版本	先 overrides 统一，再加 dedupe
需要把导入指到特定文件	用 alias，不是 dedupe
所有依赖都想「只装一份」	不合理，只对单例 / 易冲突包使用

---

10. 参考

• Vite 官方文档 - resolve.dedupe
• pnpm overrides
• npm overrides