Taro 小程序如何优雅地分包？------以「AI作文」项目为例
在小程序开发中，随着业务功能不断丰富，代码体积很容易逼近甚至突破平台限制（如微信小程序主包 2MB 上限）。这时，"分包加载"就成为一项必备的性能优化手段。本文将以我们正在开发的 AI作文小程序（项目名：Composition） 为例，深入解析如何在 Taro 框架 下进行清晰、可维护的分包配置。
一、为什么需要分包？
简单来说，分包的核心目的是：
- 控制主包体积：避免超过平台限制；
- 按需加载：用户未访问的功能不提前下载，提升首屏速度；
- 模块解耦：按业务域组织代码，结构更清晰。
微信小程序官方文档指出：整个小程序所有分包大小不超过 20M，单个主包或分包不超过 2M（实际建议 ≤1.5M 以留有余量）。
二、Taro 分包的本质：对齐平台规范
很多开发者误以为"分包是 Taro 的特性"，其实不然。
Taro 并没有发明一套自己的分包规则 ，而是将各小程序平台（如微信、支付宝）原生的 app.json 分包配置方式，映射到 Taro 的 app.config.ts 中。也就是说：
- 分包根目录 (
root) 和页面路径 (pages) 必须符合平台规范； - Taro 在编译时会将
app.config.ts转换为各端所需的app.json。
因此，理解分包的关键在于理解 小程序平台本身的分包机制，Taro 只是提供了配置入口。
三、「AI作文」项目的分包实践
在 Composition 项目中，我们采用了一套集中式路由管理 + 显式分包声明 的方案，核心文件是 src/routerMap.ts。
1. 定义分包结构
我们有两个业务分包：
packageWriting：写作相关功能packageMaterial：素材搜索与收藏
对应的配置如下：
ts
// routerMap.ts
export const subPackagesConfig = [
{
root: 'packageWriting',
pages: [
'pages/writingProgress/WritingProgress',
'pages/composition/Composition',
'pages/compositionShare/Composition',
],
},
{
root: 'packageMaterial',
pages: [
'pages/materialSearch/MaterialSearch',
'pages/materialDetail/MaterialDetail',
'pages/materialCollection/MaterialCollection',
],
},
];注意：页面路径是相对于
root的，最终在磁盘上的真实路径为src/packageWriting/pages/writingProgress/WritingProgress。
2. 主包页面自动过滤
为了避免同一个页面同时出现在主包和分包中（这是平台禁止的），我们维护了一个 分包页面 key 集合：
ts
const SUBPACKAGE_PAGE_KEYS = new Set([
'writingProgress',
'composition',
'compositionShare',
'materialSearch',
'materialDetail',
'materialCollection',
]);然后通过 getMainPackagePagePaths() 函数，从全局路由表 mainRouterMap 中排除这些 key ，生成主包的 pages 列表：
ts
export function getMainPackagePagePaths(): string[] {
return Object.entries(mainRouterMap)
.filter(([key]) => !SUBPACKAGE_PAGE_KEYS.has(key))
.map(([, path]) => path);
}3. 配置 app.config.ts
最后，在 app.config.ts 中直接引用上述函数：
ts
import { getMainPackagePagePaths } from './src/routerMap';
import { subPackagesConfig } from './src/routerMap';
export default defineAppConfig({
pages: getMainPackagePagePaths(),
subPackages: subPackagesConfig,
// ...其他配置
});✅ 优势：
- 路由定义唯一源头（
routerMap.ts）； - 新增页面只需在
mainRouterMap中注册，若属于分包，加入SUBPACKAGE_PAGE_KEYS即可自动归入分包； - 避免手动维护
pages和subPackages导致的遗漏或重复。
四、分包的常见误区与注意事项
-
TabBar 页面必须在主包
虽然 Composition 项目中
writingProgress是 TabBar 页面，但它被放在了分包中 ------ 这其实是 平台允许的特例 ：当用户点击 TabBar 时，小程序运行时会自动加载对应分包。但要注意，首次启动时不能直接跳转到分包的 TabBar 页面。 -
分包不能互相引用
普通分包之间不能直接 require 对方的 JS 或组件。公共逻辑应放在主包的
utils或components中。 -
目录结构必须严格匹配
root + pages如果配置了
root: 'packageA',pages: ['pages/home/Home']，那么文件必须位于src/packageA/pages/home/Home.tsx。 -
独立分包（independent: true）慎用
独立分包不依赖主包，适合活动页等场景，但会增加总包体积（无法共享主包代码）。
五、不分包会怎样？
如果不分包：
- 所有页面都进入主包，极易超过 2MB 限制；
- 用户首次打开就要下载全部代码，首屏时间变长；
- 代码耦合度高，后期拆分成本大。
当然，对于极简小程序（如工具类），若主包远小于 1MB，也可暂不分包。
六、总结
在 Taro 项目中实现分包，关键不在于"Taro 怎么做"，而在于"如何遵循小程序平台的分包规则，并用 Taro 的配置方式表达出来"。
Composition 项目通过 集中式路由管理 + 自动过滤机制，实现了清晰、可扩展的分包架构。这种模式不仅适用于写作类小程序，也适用于电商、内容、工具等各类复杂业务场景。
参考资料：
- 微信小程序分包加载文档
- Taro 官方文档 - 分包配置