uni-app小程序分包路径必须为根目录相对的绝对路径且不带.vue后缀，预加载仅App端支持preloadSubNVue，小程序依赖自动按需加载；tabBar页面必须在主包且配置于tabBar.list；单个分包体积不得超过2MB。
分包路径报错：pages.json 里写的路径找不到文件
根本原因是 uni-app 的分包路径必须是相对于项目根目录的绝对路径，且不能带 .vue 后缀，但开发者常误写成相对路径或漏掉 subNVue/subNVue 目录层级。比如在 subPackages 下写了 "root": "./subpackageA"，实际应为 "root": "subpackageA"（无点、无斜杠开头）。
常见错误现象：ERROR in ./subPackages/subA/pages/index/index.vue Module not found: Error: Can't resolve './subPackages/subA/pages/index/index.vue' 或小程序开发者工具提示“页面不存在”。
-
subPackages数组中每个对象的root值必须是合法子目录名，不支持../、./、/开头 - 所有分包内页面路径要写在对应分包的
pages数组里，不能写进主包pages - 路径大小写敏感，尤其在 macOS/Linux 下容易因命名不一致导致编译时没报错、运行时报白屏
预加载分包失败：调用 uni.preloadSubNVue 或 uni.loadSubNVue 报错
uni-app 小程序端不支持 uni.preloadSubNVue（该 API 仅 App 端有效），很多人直接把 App 写法搬过来，结果真机调试时静默失败或控制台报 TypeError: uni.preloadSubNVue is not a function。
小程序分包预加载本质靠的是「自动按需加载」机制，不是手动 preload。真正能做的只有两件事：确保分包 JSON 配置正确 + 在主包页面的 onLoad 中提前调用 uni.navigateTo 触发分包初始化（间接触发预加载）。
- 删掉小程序平台下所有对
uni.preloadSubNVue的调用，它在微信/支付宝/百度等小程序中根本不存在 - 如果想让某个分包更快打开，可在主包首页
onLoad里用setTimeout延迟 100ms 调用一次uni.navigateTo({ url: '/subPackages/subA/pages/index/index' })再uni.navigateBack()，触发分包资源下载（慎用，可能影响首屏） - 确认分包内页面的
path和style字段完整，缺失style可能导致 iOS 小程序白屏且无报错
uni.switchTab 跳转分包 tab 页面报错：路径不合法或不在 tabBar 列表中
小程序 tabbar 页面必须满足两个硬性条件：一是必须在主包（不能在分包），二是必须在 tabBar.list 配置里声明。但有人把分包里的页面加进 tabBar.list，结果编译不报错，真机运行时点击 tab 直接卡死或跳回首页。
uni-app 不允许分包页面作为 tabbar 页面——这是小程序底层限制，uni-app 只是透传。强行配置会导致路由系统无法识别目标页面，最终 fallback 到默认页。
- 检查
pages.json中tabBar.list所有pagePath是否都落在pages数组内（即主包 pages） - 若需分包内容出现在 tab 中，只能把 tab 页面放在主包，再通过
uni.navigateTo跳转到分包页面（注意：这样会失去 tabbar 底部高亮状态） - 微信小程序还要求
tabBar.list中的pagePath必须是小写字母 + 下划线，含大写或横杠会编译警告、运行异常
分包体积超限：构建后提示 “分包大小超过 2MB” 或 “主包过大”
微信小程序单个分包不能超过 2MB，主包不能超过 2MB（基础库 2.25.0+ 放宽至 4MB，但旧版本仍受限）。uni-app 默认不会校验分包体积，得靠人工或脚本发现，往往上线前才暴露。
问题根源常出在分包里意外引入了主包资源（如全局 utils、store、大型 UI 库组件），或者图片/字体文件没压缩直接扔进分包目录。
- 用
npx size-limit或构建后查看unpackage/dist/build/mp-weixin/subPackages/xxx/目录大小，定位大文件 - 分包内避免 import 主包路径（如
import api from '@/api/index.js'），应改为相对路径或单独抽离公共模块到common/并配置subNVue共享 - 图片资源优先用 CDN，本地图务必走 webpack 图片压缩插件（如
url-loader+image-webpack-loader），否则一个未压缩 PNG 就占几百 KB
分包路径和预加载逻辑是跨平台最易混淆的点，尤其当团队同时开发 App 和小程序时，很容易把 App 的 subNVue 思路套到小程序上。最稳妥的做法：小程序分包只管「静态路径配置 + 按需加载」，别碰任何 preload 相关 API，也别试图绕过 tabbar 限制。
