uniapp-subpackage-node-modules

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。

诊断流程

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。

例如：

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

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

推荐对话模板

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

我先按 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 往往是正常结果。

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

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

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

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

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

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

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

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

模板四：给出扫描建议

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

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

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

模板五：给出操作步骤

如果你要按 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

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

推荐检查命令

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'

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

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

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