---
name: uniapp-subpackage-node-modules
description: 仅用于诊断 uni-app 小程序分包场景下，分包引用的 node_modules 依赖为什么仍被打进主包 common/vendor.js，而没有进入分包 vendor.js。适用于检查 uni-app 或 HBuilderX 版本、manifest.json 的分包优化开关、pages.json 的 subPackages 配置、分包根目录 package.json、以及主包与分包对 npm 依赖的规划是否符合 uni-app 内置分包依赖能力的要求。
---

# uni-app 分包 node_modules 归属诊断

## 作用

当用户怀疑“分包使用的 npm 依赖没有进入分包 `vendor.js`，而是仍在主包 `common/vendor.js`”时，使用这个 skill。

这个 skill 只分析 **uni-app 内置的分包依赖能力** 是否被正确使用，不引导外部构建后脚本，也不默认修改项目。

如果问题本质是 `uni_modules`、`easycom` 或组件目录归属，改用 `uniapp-subpackage-uni-modules`。

## 适用范围

只在以下条件满足时使用：

- 项目是 uni-app
- 目标是 uni-app 已支持分包优化的小程序平台
- 项目是 `vue3`
- 问题对象是 `node_modules` 中的 js 相关文件
- 用户关心的是主包 `common/vendor.js` 与分包 `vendor.js` 的归属

以下情况不适用：

- `vue2`
- H5、App、非小程序端
- 主要问题是 `uni_modules`
- 期待图片、字体、样式等非 js 资源也跟着拆进分包 `vendor.js`

## 核心规则

- 先在 `manifest.json` 的目标小程序平台节点开启 `optimization.subPackages`
- 先做依赖划分，再判断 vendor 归属
- 只有“只被单个分包使用的 node_modules js 依赖”才适合进入该分包 `vendor.js`
- 被主包引用、被多个分包引用、或通过共享模块间接复用的依赖，留在主包通常是正常结果
- 文章补充注意事项：
- 只对 `vue3` 生效
- 支持 HBuilderX 项目和 CLI 项目
- 仅支持 `node_modules` 中的 js 相关文件

详细规则放在 [references/node-modules-subpackage-rules.md](references/node-modules-subpackage-rules.md)。

## 诊断流程

### 1. 确认问题域

先确认：

- 存在 `manifest.json`
- 存在 `pages.json`
- 配置了 `subPackages`
- 问题描述明确提到 `common/vendor.js`、分包 `vendor.js` 或 `node_modules`

如果用户在问 `uni_modules`、`easycom`、分包组件归属，不要继续用这个 skill。

### 2. 检查版本前提

优先看版本，再看其他配置。

- HBuilderX 项目：检查是否达到文章提到的 `5.04` 或更高版本
- CLI 项目：检查 `@dcloudio/*` 构建链路依赖是否已升级到具备同等能力的版本

版本过旧时，应优先标记为高风险。

### 3. 检查配置

重点检查两处：

- `manifest.json` 是否开启 `optimization.subPackages`
- `pages.json` 的 `subPackages` 是否有效，`root` 和 `pages` 是否正确

如果分包本身没建立成功，就不要继续讨论为什么依赖没进分包 `vendor.js`。

### 4. 检查依赖划分

必须先把依赖分成三类：

- 主包专用依赖
- 单分包专用依赖
- 主包与多个分包共享的依赖

输出时要明确提醒开发者：

- 不要先改配置，再回头想哪些依赖应该分包
- 应该先梳理依赖边界，再决定哪个分包根目录需要自己的 `package.json`

### 5. 检查分包根目录 `package.json`

如果某个依赖本应只属于单个分包，应检查对应分包根目录下是否维护了自己的 `package.json`。

例如：

```text
pages/sub/package.json
```

如果这类依赖只声明在项目根 `package.json`，要列为高风险信号。

### 6. 检查引用链

重点确认目标依赖是否被以下位置拉回主包：

- 主包页面
- `App.vue`
- 根目录共享模块，例如 `utils/`、`api/`、`store/`、`hooks/`
- 其他分包

只要出现这些情况，依赖继续留在主包通常是符合规则的。

### 7. 检查产物

如果已有小程序构建产物，继续检查：

- 主包是否存在 `common/vendor.js`
- 目标分包根目录下是否生成自己的 `vendor.js`
- 目标依赖代码最终落在哪个 `vendor.js`

如果分包根目录没有自己的 `vendor.js`，回头检查版本、配置、依赖划分和引用链。

### 8. 可选扫描

如果开发者不确定“某个分包文件到底有没有用到某个依赖”，可以先征得同意，再继续扫描代码。

扫描目标：

- 找出只被单个分包使用的依赖
- 找出被主包或多个分包共用的依赖
- 给出“适合拆到分包”和“应留在主包”的建议

如果开发者没有同意继续扫描，就停在规则说明、人工检查口径和操作步骤，不要默认深入分析整个项目。

## 判定规则

### 基本满足前提

出现以下条件时，可判定为“已基本满足 uni-app 内置能力前提”：

- `vue3`
- 版本满足前提
- `manifest.json` 已开启分包优化
- `pages.json` 分包有效
- 目标依赖只服务于单个分包
- 分包根目录有自己的 `package.json`
- 引用链没有把依赖拉回主包

### 直接不符合前提

出现以下任一情况时，应直接说明为什么它不会进入分包 `vendor.js`：

- 不是 `vue3`
- 版本过旧
- 没开 `optimization.subPackages`
- 分包配置无效
- 依赖被主包引用
- 依赖被多个分包共享
- 分包专用依赖没有在分包根目录声明

### 容易误判的情况

- 主包和分包都用了同一个 npm 包
- 分包通过根目录共享模块间接使用依赖
- 开发者期待非 js 资源也进入分包 `vendor.js`
- 分包里没有自己的 `package.json`

## 输出模板

拿到项目后，按下面顺序输出：

### 1. 诊断结论

- 是否属于“分包 node_modules 仍在主包 vendor.js”问题域
- 是否满足 uni-app 内置能力前提
- 当前更像是哪类原因：
- 版本不满足
- 配置未开启
- 分包未成功建立
- 依赖划分不合理
- 引用链把依赖拉回主包

### 2. 已确认事实

- uni-app / HBuilderX / CLI 关键版本
- `manifest.json` 的分包优化配置
- `pages.json` 的 `subPackages`
- 项目根与分包根目录下的 `package.json`
- 依赖被哪些页面或模块引用

### 3. 风险点

逐条列出，并说明依据来自哪个文件或哪个现象。

### 4. 建议

- 应升级哪个版本
- 应补哪项 `manifest.json` 配置
- 应在哪个分包根目录补 `package.json`
- 哪些依赖应留在主包，哪些依赖适合拆到单个分包
- 哪些共享模块需要避免再引用分包专用依赖

### 5. 验证方式

- 重新打包后看分包根目录是否生成自己的 `vendor.js`
- 对照 `common/vendor.js` 和分包 `vendor.js` 搜索目标依赖
- 核对分包页面最终引用的 vendor 路径

### 6. 操作步骤

如果用户问“接下来怎么做”，按 `dd.md` 的顺序给步骤，只给步骤，不直接修改：

1. 先在 `manifest.json` 的目标小程序平台节点开启 `optimization.subPackages`
2. 先梳理依赖边界，确认哪些依赖只属于某一个分包
3. 在对应分包根目录新增 `package.json`
4. 把该分包专用依赖写入这个分包自己的 `package.json`
5. 安装该分包需要的依赖
6. 重新执行小程序打包
7. 检查产物，确认分包根目录是否生成自己的 `vendor.js`
8. 再核对目标依赖是否已从主包 `common/vendor.js` 转移到分包 `vendor.js`

如果证据不足，就明确说“目前只能做源码层判断”。

## 推荐对话模板

### 模板一：先判断规则是否满足

```text
我先按 uni-app 内置的分包依赖规则帮你判断这个问题是否成立。

我会先检查：
1. uni-app / HBuilderX / CLI 版本
2. manifest.json 是否开启 optimization.subPackages
3. pages.json 是否配置了有效分包
4. 你是否已经先做了主包依赖、单分包依赖、共享依赖的划分
5. 分包根目录下是否已经有自己的 package.json

先说明一个关键前提：只有只被单个分包使用的 node_modules js 依赖，才适合进入该分包的 vendor.js。被主包或多个分包共用的依赖，继续留在 common/vendor.js 往往是正常结果。
```

### 模板二：提醒先做依赖划分

```text
这个能力不能脱离“依赖划分”单独看。

你需要先把依赖分成三类：
- 主包专用依赖
- 单个分包专用依赖
- 主包和多个分包共享的依赖

如果这一步还没做，建议先不要急着判断为什么 vendor.js 没拆开。
```

### 模板三：征求是否继续扫描

```text
如果你愿意，我可以继续帮你检测“某个分包下面的哪些文件实际引用了哪些依赖”，再据此判断哪些依赖符合这个优化规则。

这一步我会重点识别：
- 哪些依赖只被单个分包使用
- 哪些依赖被主包引用了
- 哪些依赖被多个分包共用了

如果你同意，我再继续做这一步扫描；如果不同意，我就只给你人工检查口径和操作步骤。
```

### 模板四：给出扫描建议

```text
基于当前扫描结果，可以先这样分：

- 适合尝试进入分包 vendor.js 的依赖：
- 建议继续留在主包 common/vendor.js 的依赖：

判断依据：
- 是否只在单个分包目录出现
- 是否被 App.vue、主包页面或根目录共享模块引用
- 是否被多个分包同时引用
```

### 模板五：给出操作步骤

```text
如果你要按 dd.md 这套方式落地，建议按这个顺序操作：

1. 先在 manifest.json 的目标小程序平台节点开启 optimization.subPackages
2. 先完成依赖划分，确认哪些依赖只属于某一个分包
3. 在对应分包根目录新增 package.json
4. 把该分包专用依赖写入这个分包自己的 package.json
5. 安装该分包需要的依赖
6. 重新执行小程序打包
7. 检查产物，确认分包根目录是否生成自己的 vendor.js
8. 再核对目标依赖是否已经从 common/vendor.js 转移到分包 vendor.js

这一步只建议给操作步骤，不要默认直接改项目。
```

## 推荐检查命令

```bash
rg --files <项目目录> | rg 'manifest\.json$|pages\.json$|package\.json$|unpackage|dist'
rg -n '"subPackages"|optimization|mp-weixin' <项目目录>/manifest.json <项目目录>/pages.json
rg --files <项目目录> | rg '/package\.json$'
rg -n 'from .*(lodash-es|axios|dayjs)|require\\(' <项目目录>
rg --files <产物目录> | rg 'vendor\.js$'
rg -n 'lodash-es|axios|dayjs' <产物目录> -g 'vendor.js'
```

如果用户已经给出具体依赖名，把示例包名替换成真实依赖名。

如果用户同意继续做依赖划分扫描，可以补充：

```bash
rg -n "from '依赖名'|from \"依赖名\"|require\\('依赖名'\\)|require\\(\"依赖名\"\\)" <项目目录>
rg -n "from '依赖名/|from \"依赖名/|require\\('依赖名/|require\\(\"依赖名/" <项目目录>
```