Taro 多端小程序动态模块打包方案

📋 项目概述

这是一个基于 Taro 3 框架的多端小程序项目，主要针对电商业务场景，支持微信小程序、支付宝小程序和 H5 等多端部署。项目采用动态模块化的架构，可以针对不同商户进行个性化定制和打包。

核心技术栈

• 框架: Taro 3.6.34
• UI 库: 二方包taro-core, materials
• 语言: TypeScript + React 18
• 样式: SCSS + TailwindCSS
• 构建工具: Webpack 5
• 包管理: Yarn

---

🏗️ 项目架构特点

1. 动态模块化系统

项目采用了独特的动态模块打包机制，通过配置文件控制不同商户的页面和功能模块：

src/
├── pages/              # 主包页面（通用页面）
├── packCommon/         # 通用分包
├── packPageA/          # 分包A（扩展功能）
├── packJumpGame/       # 游戏分包
├── packageGoods/       # 商品相关分包
└── merchantPage/       # 商户定制页面
    ├── matsukiyo/      # 业务定制1
    ├── yohjiyamamoto/  # 业务定制1
    └── brisbaneAirport/ # 业务定制3

2. 模块配置机制

核心配置文件

• merchantRouterConfig.json: 商户路由模块配置
• .dynamic-modules-rules.json: 运行时生成的动态打包规则
• ext.json: 小程序第三方平台扩展配置

配置规则结构

{
  "name": "商户标识",
  "title": "商户名称",
  "type": "custom|base",
  "miniRules": {
    "include": ["包含的页面路径"],
    "exclude": ["排除的页面路径"],
    "replace": {
      "原始页面": "替换页面"
    }
  }
}

---

📦 打包流程分析

构建流程图

开始打包
    ↓
1. 读取 ext.json（获取商户ID和环境）
    ↓
2. 调用后端接口获取商户的模块配置
    ↓
3. 生成 .dynamic-modules-rules.json
    ↓
4. 执行页面替换（replacePage）
    ↓
5. 获取物料组件配置，生成 .materials.js
    ↓
6. 执行 Taro 构建
    ↓
完成打包

核心构建脚本

1. build/dynamic-modules-builder.js

• 从后端获取商户的打包配置
• 生成 .dynamic-modules-rules.json 文件
• 支持 include/exclude/replace 三种规则

2. build/dynamic-materials-builder.js

• 获取商户可用的装修物料组件
• 动态生成 .materials.js 导出文件

3. dynamic-modules-config/replacePage.js

• 执行页面文件的物理替换
• 支持文件监听和自动替换

---

🎯 不同商户的打包方案

方案一：基础商户（标准版）

适用场景: 普通电商商户，使用所有基础功能

模块配置:

{
  "modules": [
    "$base",           // 基础模块（必选）
    "$game",           // 游戏市场（可选）
    "$promoter",       // 分销员（可选）
    "$storeShop",      // 门店自提（可选）
    "$tripGoods"       // 旅游产品（可选）
  ]
}

打包命令:

# 开发环境
yarn dev:weapp

# 生产环境
yarn build:weapp

配置步骤:

1. 修改 src/ext.json 中的 businessNo 为商户ID
2. 在 Iron 运营后台配置商户的模块（选择上述模块）
3. 执行打包命令

包大小预估: 基础模块 + 2-3个可选模块，约 2-4MB

---

方案二：定制商户（松本清/山本耀司）

适用场景: 需要定制页面的高端品牌商户

定制内容:

• 松本清 (matsukiyo):

  • 定制首页
  • 定制个人中心
  • 定制收藏页

• 山本耀司 (yohjiyamamoto):

  • 定制商品详情页

模块配置:

{
  "name": "matsukiyo",
  "type": "custom",
  "miniRules": {
    "include": [
      "merchantPage/matsukiyo/**/*"
    ],
    "replace": {
      "pages/mine/index/index": "merchantPage/matsukiyo/mine/index",
      "pages/templateTab/index": "merchantPage/matsukiyo/collection/index"
    }
  }
}

打包流程:

1. 在 merchantRouterConfig.json 添加商户配置
2. 在 src/merchantPage/商户名/ 创建定制页面
3. 配置 replace 规则替换标准页面
4. 上传配置到 Iron 后台
5. 执行打包

注意事项:

• ⚠️ 商户定制页面必须使用绝对路径引用
• ⚠️ 替换页面会物理删除原页面文件夹并复制新文件

包大小预估: 基础模块 + 定制模块，约 2.5-5MB

---

方案三：功能扩展商户

适用场景: 需要特殊业务功能的商户

示例配置：

1. 日本国家馆（支付服务）

{
  "name": "japanNationalPavilion",
  "miniRules": {
    "include": [
      "packPageA/japanPayment/**/*",
      "packPageA/tuition/**/*"
    ]
  }
}

2. 布里斯班机场（机场服务）

{
  "name": "brisbaneAirport",
  "miniRules": {
    "include": [
      "packCommon/airportService/**/*",
      "merchantPage/brisbaneAirport/**/*"
    ],
    "replace": {
      "pages/goods/index/index": "merchantPage/brisbaneAirport/goods/index"
    }
  }
}

3. HFT退税

{
  "name": "htf",
  "miniRules": {
    "include": [
      "packPageA/taxRefund/**/*"
    ],
    "replace": {
      "pages/home/index": "pages/homeHFT/index"
    }
  }
}

包大小预估: 根据功能模块不同，约 2-6MB

---

方案四：平台多商户模式

适用场景: 类似天猫的平台商户模式

模块配置:

{
  "modules": [
    "$base",
    "$platform"  // 平台商户模块
  ],
  "miniRules": {
    "include": [
      "packPageA/shopPage/index"
    ],
    "replace": {
      "packCommon/order/order/submit/delivery/index": 
      "packCommon/order/order/platformSubmit/index"
    }
  }
}

特点:

• 支持多商家入驻
• 替换订单提交流程为平台订单
• 添加店铺页面

---

方案五：特殊业态（餐厅/预约服务）

适用场景: 餐厅堂食、预约服务等特殊业态

模块配置:

{
  "modules": [
    "$base",
    "$dineOrdering",    // 堂食点餐
    "$reservation",     // 虚拟服务预定
    "$restaurant"       // 餐厅预定
  ]
}

包含功能:

• 堂食点餐流程
• 时间选择/预约
• 特殊订单流程

---

🚀 打包命令详解

微信小程序

# 开发环境（带热更新）
yarn dev:weapp

# 生产环境打包
yarn build:weapp

# 生产环境打包（带体积分析）
yarn build:weapp:as

# 测试环境打包（用于自动化测试）
yarn build:test-weapp

支付宝小程序

# 开发环境
yarn dev:alipay

# 生产环境（包含所有插件）
yarn build:alipay:all

# 单独打包订阅插件
yarn build:alipay:subscribe

# 单独打包淘宝直播插件
yarn build:alipay:tblive

# 打包所有插件组合
yarn build:alipay:allplugins

H5 移动端

# 开发环境
yarn dev:h5

# 生产环境
yarn build:h5

---

⚙️ 环境配置

1. ext.json 配置说明

{
  "extEnable": true,
  "extAppid": "小程序AppID",
  "ext": {
    "backEndEnv": "test|prod",           // 后端环境
    "host": "https://dsapi.test.xyb2b.com",
    "attr": {
      "wxAppid": "微信AppID",
      "aliAppid": "支付宝AppID",
      "imageBaseUrl": "图片CDN地址",
      "businessNo": 30                    // 商户ID（关键配置）
    },
    "miniVersion": "2.2.2"
  }
}

2. 动态模块规则（.dynamic-modules-rules.json）

该文件由构建脚本自动生成，示例：

{
  "include": [
    "pages/home/index",
    "pages/goods/index/index",
    "packPageA/groupSell/index"
  ],
  "exclude": [],
  "replace": {
    "pages/mine/index/index": "merchantPage/matsukiyo/mine/index"
  }
}

---

📊 模块类型说明

基础模块（$base）

必选模块，包含核心电商功能：

• 首页、分类、购物车、我的
• 商品详情、订单流程
• 登录/注册、优惠券
• 直播、活动

页面数量: ~100+页面

可选功能模块

模块名	说明	页面数	适用场景
$game	游戏市场	10+	营销活动
$promoter	分销员	15+	社交电商
$platform	平台商户	5+	多商户平台
$dineOrdering	堂食点餐	8+	餐饮业务
$storeShop	门店自提	6+	O2O业务
$tripGoods	旅游产品	12+	旅游服务
$reservation	虚拟服务	10+	预约服务
$restaurant	餐厅预定	10+	餐厅业务

定制模块（custom）

完全自定义的商户专属页面，支持：

• 页面替换（replace）
• 新增页面（include）
• 独立样式和逻辑

---

🔧 开发新商户的步骤

方式一：使用现有模块组合（推荐）

1. 在 Iron 运营后台配置

   • 访问 Iron 工作台 (opens new window)
   • 选择对应商户
   • 在"模块配置"中勾选需要的模块

2. 修改本地 ext.json

   {
     "ext": {
       "backEndEnv": "test",
       "attr": {
         "businessNo": 新商户ID
       }
     }
   }
   

3. 执行打包

   yarn build:weapp
   

方式二：创建定制商户

1. 创建商户目录

   mkdir -p src/merchantPage/新商户名
   

2. 开发定制页面

   • 复制基础页面或从零开发
   • ⚠️ 使用绝对路径引用: @/merchantPage/新商户名/...

3. 配置 merchantRouterConfig.json

   {
     "name": "新商户名",
     "title": "商户显示名称",
     "type": "custom",
     "miniRules": {
       "include": [
         "merchantPage/新商户名/**/*"
       ],
       "replace": {
         "pages/home/index": "merchantPage/新商户名/home/index"
       }
     }
   }
   

4. 上传到 Iron 后台

5. 本地测试

   # 开发模式（会有确认提示，防止代码覆盖）
   yarn dev:weapp
   

6. 生产打包

   yarn build:weapp
   

---

📈 打包优化建议

1. 按需加载模块

• 只选择商户实际需要的功能模块
• 避免打包未使用的分包

2. 代码分割

• 利用 Taro 的分包机制
• 将低频功能放入独立分包

3. 资源优化

• 图片使用 CDN
• 启用 tree-shaking（项目已配置）
• 使用 Webpack Bundle Analyzer 分析体积

yarn build:weapp:as  # 查看打包分析报告

4. 缓存策略

• 开发环境可开启 webpack cache（需要手动启用）
• 生产环境关闭缓存确保构建稳定性

---

⚠️ 注意事项

1. 页面替换机制

• replace 配置会物理删除目标文件夹
• 开发时会有确认提示，生产环境直接执行
• 建议在版本控制中保留原始页面备份

2. 路径引用规范

• 商户定制页面必须使用绝对路径
• 正确：import '@/merchantPage/matsukiyo/constants'
• 错误：import '../../constants'

3. 环境变量

• CI_MP3RD_EXT_INFO: CI/CD 环境的配置文件路径
• backEndEnv: test 或 prod
• TARO_ENV: weapp, alipay, h5

4. 支付宝特殊处理

• 需要去掉微信插件配置
• 使用 yalc 本地引用 @xy/tms-container-api-linkiebuy

5. 新商户提审前准备

参考 README.md 中的"新商户提审前置准备"章节：

• Iron 工作台数据同步
• 域名配置
• 隐私协议配置

---

📚 相关文档

• 飞书：动态模块打包模块 (opens new window)
• 飞书：商户定制开发方案 (opens new window)
• 飞书：新商户提审常见问题 (opens new window)
• 飞书：打包体积优化 (opens new window)
• 装修物料开发 (opens new window)
• Iron 运营后台 (opens new window)

---

🎨 打包流程示意图

┌─────────────────────────────────────────────────────────────┐
│                     开始打包流程                              │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  ▼
    ┌─────────────────────────┐
    │  读取 ext.json          │
    │  - businessNo (商户ID)  │
    │  - backEndEnv (环境)    │
    └─────────┬───────────────┘
              │
              ▼
    ┌──────────────────────────────────┐
    │  调用后端 API 获取模块配置        │
    │  /getPackageConfig?sellerId=XX   │
    └─────────┬────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────┐
    │  生成 .dynamic-modules-rules.json│
    │  - include: [...]               │
    │  - exclude: [...]               │
    │  - replace: {...}               │
    └─────────┬───────────────────────┘
              │
              ▼
    ┌─────────────────────────────┐
    │  执行页面替换 (replacePage)  │
    │  - 删除目标页面文件夹         │
    │  - 复制源页面文件夹           │
    │  - 重命名文件                │
    └─────────┬───────────────────┘
              │
              ▼
    ┌──────────────────────────────┐
    │  获取装修物料配置             │
    │  /querySellerOnlineDetails   │
    └─────────┬────────────────────┘
              │
              ▼
    ┌─────────────────────────┐
    │  生成 .materials.js     │
    │  (动态导出物料组件)      │
    └─────────┬───────────────┘
              │
              ▼
    ┌─────────────────────────┐
    │  执行 Taro 构建         │
    │  taro build --type XXX  │
    └─────────┬───────────────┘
              │
              ▼
    ┌─────────────────────────┐
    │  输出到 dist/ 目录      │
    │  - 小程序包             │
    │  - 分包结构             │
    └─────────────────────────┘

---

🔍 总结

本项目采用了高度灵活的模块化打包方案，能够满足不同商户的个性化需求：

✅ 标准商户: 通过模块组合快速上线
✅ 定制商户: 支持深度页面定制和品牌化
✅ 特殊业态: 灵活添加行业特定功能
✅ 多端部署: 一套代码支持微信/支付宝/H5

核心优势:

1. 配置化: 通过配置文件控制打包内容
2. 动态化: 运行时从后端获取配置
3. 可扩展: 新增商户/模块无需修改核心代码
4. 高复用: 基础模块跨商户共享

适用场景:

• SaaS 模式电商小程序
• 多品牌/多商户统一管理
• 快速定制化交付