uni-app预加载分包必须通过pages.json中与pages、subPackages同级的preloadRule字段配置,其key为触发页路径、value含packages(分包root或name)和network,且分包须已正确定义在subPackages中;生效需真机调试查看preloadSubpackages日志是否显示success。

uni-app 预加载分包页面不能靠 uni.preloadPage() 直接触发——这个 API 只对主包内页面有效,对分包页面无效。真正起作用的是配置驱动的预下载机制,且必须在用户进入某个「触发页」时,由框架自动拉取分包资源。
preloadRule 配置必须写在 pages.json 里
很多人误以为可以在 JS 里动态调用或写在 manifest.json 中,其实 uni-app 的分包预加载只认 pages.json 里的 preloadRule 字段。它不是运行时 API,而是构建/启动阶段解析的静态规则。
-
preloadRule是 pages.json 的顶层字段,和pages、subPackages同级 - 每个 key 是「触发页面路径」,比如
"pages/index/index",值对象里必须包含packages数组(填分包的root或name) -
network可选"all"或"wifi",不写默认为"all" - 示例:
{"preloadRule": {"pages/index/index": {"network": "all", "packages": ["subpackageA"]}}}
分包必须已正确定义在 subPackages 节点下
如果 preloadRule 里写了 "subpackageA",但 pages.json 的 subPackages 里没有对应项,预加载会静默失败,控制台也不会报错。
-
subPackages中每个分包需明确root(物理路径)和pages(子页面列表) -
root值要和preloadRule.packages中的字符串完全一致(区分大小写) - TabBar 页面不能放在分包里,否则小程序平台会拒绝编译
- 分包内页面跳转路径要带前缀,比如从主包跳分包页:
uni.navigateTo({ url: '/subpackageA/pages/list' })
怎么确认预加载是否生效
光配对了不一定成功。真机调试时,进入触发页后看控制台是否有 preloadSubpackages 日志,且状态为 success。
- 微信开发者工具中需开启「调试基础库」并勾选「显示系统信息日志」
- HBuilderX 中可在运行日志里搜索
preloadSubpackages,失败时可能提示package not found或network restricted - 注意:预加载是后台静默进行的,不会阻塞当前页面渲染,但会占用网络带宽和内存;WiFi 下预加载大分包可能导致首页滚动卡顿
- 如果分包体积超过 2MB,部分平台(如微信)会直接拒绝下载,此时需先压缩图片、移除未用组件,或拆更细的分包
最容易被忽略的一点:预加载只在「首次进入触发页」时发生,且只触发一次。后续再进该页不会重复拉取——但如果你清除了小程序缓存或更新了分包版本号,它会重新触发。别指望每次打开首页都重载分包,那是资源浪费。











