uniapp-subpackage-uni-modules

name	uniapp-subpackage-uni-modules
description	仅用于诊断 uni-app 小程序分包场景下，分包使用的 uni_modules 为什么被错误打入主包。只适用于 uni-app 已支持的小程序平台；适用于检查 manifest.json、pages.json、uni_modules 目录布局、easycom 指向和 unpackage 编译结果，并针对目录放错、easycom 配置错误、或分包优化缺失等原因输出具体建议。

uni-app 分包 uni_modules 误入主包诊断

作用

当用户给出一个 uni-app 项目，并怀疑“分包使用的 uni_modules 最终被打进了主包”时，使用这个 skill。

这个 skill 只分析这一类问题的成因，不负责泛化分析所有分包组件冲突问题。

这个 skill 只对 uni-app 已支持的小程序平台生效，例如 mp-weixin 等 mp-* 平台节点；如果问题指向的是非小程序平台，或不是 uni-app 已支持的小程序平台，就不要套用这套结论。

默认输出应当是“问题是否成立 + 导致误入主包的原因 + 具体修改建议”。只有当用户明确要求落地修改时，再进入改代码阶段。

诊断流程

第一步：确认是否属于这个问题域

先检查项目是否同时具备以下特征：

• 存在 manifest.json
• 存在 pages.json
• 存在 uni-app 已支持的小程序平台配置，例如 mp-weixin
• 存在 subPackages 配置，或目录结构明显存在分包根目录
• 项目中存在供分包页面使用的 uni_modules

如果这些条件都不满足，就不要套用这套结论。

如果项目主要目标不是 uni-app 小程序平台，或者用户给出的平台不在 uni-app 已支持的小程序平台范围内，也不要继续使用这个 skill。

第二步：检查 manifest.json

重点检查目标 uni-app 小程序平台节点下是否包含：

{
  "mp-weixin": {
    "optimization": {
      "subPackages": true
    },
    "usingComponents": true
  }
}

检查时要注意：

• 原始资料里有时会写成 mainfest.json，实际项目通常是 manifest.json
• subPackages: true 是分包优化开关
• usingComponents: true 会影响组件输出和小程序组件引用行为

如果缺少这两项中的任意一项，要明确标记为高优先级建议，因为这会直接影响分包资源是否按包归属输出。

如果项目里只有 app-plus、h5 等非小程序节点，或者当前问题指向的不是 uni-app 已支持的小程序平台，直接说明此 skill 不适用。

第三步：检查源码目录布局是否把分包组件库放错了位置

核心规则：

• 主包组件库应位于项目根目录的 uni_modules/
• 分包组件库应位于分包根目录下的 uni_modules/

例如分包根目录为 sub/ 时，分包组件库应该放在：

sub/uni_modules/<组件库名>/

重点看三件事：

• 分包专用组件库是否误放在项目根 uni_modules/
• 分包根目录下是否根本没有自己的 uni_modules/
• 开发者是否把“分包页面会用到的组件库”全部只放在主包里

如果同一个组件库在主包和分包都存在，不要立刻判定为错误。要继续检查 easycom 是否真的把分包页面导向了分包目录。

第四步：检查 pages.json 的 easycom 是否仍把分包页面指向主包

如果主包和分包都使用同一个组件库，必须重点检查 easycom.custom 是否把分包页面使用的标签指向了分包根目录。

典型做法如下：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^rice-(.*)": "uni_modules/rice-ui/components/rice-$1/rice-$1.uvue",
      "^sub-rice-(.*)": "sub/uni_modules/rice-ui/components/rice-$1/rice-$1.uvue"
    }
  }
}

审查时要明确判断：

• 是否存在“主包前缀”和“分包前缀”两套规则
• 分包别名是否真正指向分包根目录下的 uni_modules
• 主包别名是否仍然指向项目根的 uni_modules

出现以下情况时，直接判定为高风险：

• 分包页面使用的标签最终映射到根目录 uni_modules
• 根本没有分包专用别名规则
• 看起来配置了双前缀，但两个前缀都指向主包路径

第五步：检查页面实际标签写法

不要只看 pages.json，还要检查页面源码里实际使用的标签。

目标规则：

• 主包页面使用主包前缀，例如 rice-button
• 分包页面使用分包前缀，例如 sub-rice-avatar

这一层检查的目的只有一个：确认分包页面到底有没有走到分包那套 easycom 规则。

要特别注意：

• 页面层标签前缀需要隔离
• 组件库内部的组件互相引用，通常仍然使用组件库原生标签，例如 rice-icon

不要错误地要求把组件库内部源码也全部改成 sub-rice-*。页面层是否命中了分包别名，和组件库内部标签体系，不是同一个层次。

第六步：检查编译产物里是否真的落到了主包

如果项目里已经有 unpackage/dist/dev/mp-weixin 或类似编译输出，必须继续检查产物，不要只停在源码层。

重点检查：

• 分包页面生成的 usingComponents 是否指向分包路径
• 分包组件自身的 usingComponents 是否仍然回指主包路径
• 是否出现“页面入口组件在分包，但其子依赖仍被编译到主包”的情况

这是最终判定是否“误入主包”的关键证据。源码层看起来正确，并不代表产物层真正按包归属输出。

第七步：输出结论和建议

输出时按“事实 -> 风险 -> 建议”的顺序，不要只给笼统结论。

重点判定规则

可判定为基本正确

满足以下条件时，可判定为“源码层暂未发现明显导致误入主包的配置问题”：

• manifest.json 已开启小程序分包优化
• 当前检查的平台属于 uni-app 已支持的小程序平台
• 主包和分包的 uni_modules 放置位置正确
• pages.json 为分包页面提供了能指向分包目录的 easycom 规则
• 分包页面实际使用了会命中分包规则的标签前缀

仍需继续核查

即使源码层看起来正确，只要出现以下任一情况，就不能直接下最终结论：

• 已有编译产物，但还没检查 usingComponents
• 分包页面只引用了分包入口组件，但未确认入口组件的子依赖落点
• 分包组件库内部存在大量组件互相引用，可能导致子依赖继续落到主包

明确风险信号

出现以下情况时，要明确指出存在风险：

• 分包页面引用的是分包标签，但实际仍映射到根目录 uni_modules
• 分包专用组件库只放在项目根 uni_modules
• 分包页面使用的仍是主包标签，没有命名隔离
• 编译产物中，分包组件的 usingComponents 通过多级 ../ 回指到主包 uni_modules

最后这一类在源码审查时很容易漏掉，但往往才是“看起来配对了、实际上还是串包”的根因。

针对新项目的输出模板

拿到一个新项目后，按下面格式输出：

1. 诊断结论

• 是否属于“分包 uni_modules 误入主包”问题域
• 是否属于 uni-app 已支持的小程序平台
• 当前问题更像是哪一类原因：
• manifest.json 缺配置
• 分包组件库目录放错
• easycom 仍指向主包
• 编译产物存在跨包回指

2. 已确认事实

• manifest.json 的关键配置
• pages.json 里的分包配置和 easycom 指向
• 主包与分包的 uni_modules 实际目录位置
• 分包页面实际使用的组件标签

3. 风险点

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

4. 建议

建议要具体到动作：

• 应该补哪项配置
• 应该移动哪个目录
• 应该把哪条 easycom 规则改到哪个路径
• 应该检查哪类编译产物路径来确认是否还在主包

如果证据不足，就明确说“建议继续检查编译产物”，不要伪造结论。

针对测试项目总结出的经验

这个 skill 对应的测试项目验证出了一条非常实用的经验：

• 页面层可以通过 rice-* 和 sub-rice-* 做主包、分包隔离
• 但这并不自动保证分包组件的子依赖不会继续落入主包
• 因此，不能只看源码层 easycom，还要继续检查编译后分包组件自己的 usingComponents

在测试项目中，分包页面入口组件已经正确落在分包目录，但其内部子组件依赖存在回指主包 uni_modules 的现象。这类问题要在 skill 输出里单独提示用户复查，因为它直接关系到“是否仍然被打进主包”。

推荐检查命令

优先使用快速只读命令收集证据：

rg --files <项目目录> | rg 'manifest\.json$|pages\.json$|uni_modules|unpackage'
rg -n '"subPackages"|easycom|usingComponents|uni_modules' <项目目录>/pages.json <项目目录>/manifest.json
rg -n '<rice-|<sub-rice-' <项目目录>/pages <项目目录>/sub
rg -n 'usingComponents|uni_modules' <项目目录>/unpackage/dist/dev/mp-weixin -g '*.json'

如果产物目录不存在，就把结论限定为“源码层判断”。

参考资料

需要具体规则示例时，读取 references/uni-modules-subpackage-rules.md。