Taro 小程序如何优雅地分包

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 官方文档 - 分包配置