小程序分包加载与启动性能优化实战指南 2026

// app.json
{
  "pages": [
    "pages/home/index",
    "pages/search/index",
    "pages/profile/index"
  ],
  "subpackages": [
    {
      "root": "package-trade",
      "name": "trade",
      "pages": [
        "pages/order-list/index",
        "pages/order-detail/index",
        "pages/refund/index"
      ]
    },
    {
      "root": "package-activity",
      "name": "activity",
      "pages": [
        "pages/campaign/index",
        "pages/coupon/index"
      ]
    },
    {
      "root": "package-share",
      "name": "share",
      "pages": [
        "pages/landing/index"
      ],
      "independent": true
    }
  ],
  "preloadRule": {
    "pages/home/index": {
      "network": "all",
      "packages": ["trade"]
    },
    "pages/search/index": {
      "network": "wifi",
      "packages": ["activity"]
    },
    "package-share/pages/landing/index": {
      "network": "wifi",
      "packages": ["__APP__"]
    }
  },
  "lazyCodeLoading": "requiredComponents",
  "window": {
    "navigationBarTitleText": "MiniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f6f7f9"
  },
  "tabBar": {
    "color": "#667085",
    "selectedColor": "#1652f0",
    "backgroundColor": "#ffffff",
    "list": [
      { "pagePath": "pages/home/index", "text": "首页" },
      { "pagePath": "pages/search/index", "text": "搜索" },
      { "pagePath": "pages/profile/index", "text": "我的" }
    }
  ]
}

miniprogram/
├── app.js
├── app.json
├── app.wxss
├── components/
│   └── shell/                 # 多包共用，保留主包前先确认是否真被主包使用
├── pages/
│   ├── home/
│   ├── search/
│   └── profile/
├── package-trade/
│   ├── components/order-card/
│   ├── services/order.js
│   ├── assets/empty-order.png
│   └── pages/order-detail/
├── package-activity/
│   ├── components/coupon-card/
│   └── pages/campaign/
└── package-share/
    ├── app-shell.wxss         # 独立分包不能依赖 app.wxss，需有自己的基础样式
    └── pages/landing/

// package-trade/pages/order-detail/index.js
function renderRefundPanel(mod) {
  // 使用异步加载到的模块渲染面板
}

require.async('../../package-refund/index.js')
  .then(renderRefundPanel)
  .catch(({ mod, errMsg }) => {
    // 上报加载失败，并展示本包兜底 UI
    reportLoadError({ mod, errMsg });
  });

// package-trade/pages/order-detail/index.json
{
  "usingComponents": {
    "refund-panel": "../../package-refund/components/refund-panel/index",
    "refund-placeholder": "../components/refund-placeholder/index"
  },
  "componentPlaceholder": {
    "refund-panel": "refund-placeholder"
  }
}

// package-share/pages/landing/index.js
function createAppState() {
  return {
    scene: '',
    inviteCode: '',
    bootstrapReady: false,
  };
}

Page({
  data: {
    loading: true,
    inviteCode: '',
  },

  onLoad(query) {
    // 独立分包不能假设主包 App 已经存在。
    const app = getApp({ allowDefault: true }) || {};
    app.shareBootstrap = createAppState();
    app.shareBootstrap.scene = query.scene || '';
    app.shareBootstrap.inviteCode = query.invite || '';

    this.setData({
      inviteCode: app.shareBootstrap.inviteCode,
      loading: false,
    });
  },
});

{
  "preloadRule": {
    "pages/home/index": {
      "network": "all",
      "packages": ["trade"]
    },
    "pages/profile/index": {
      "network": "wifi",
      "packages": ["activity", "settings"]
    },
    "package-share/pages/landing/index": {
      "network": "wifi",
      "packages": ["__APP__"]
    }
  }
}

{
  "lazyCodeLoading": "requiredComponents"
}

{
  "usingComponents": {
    "editor": "../heavy-editor/index",
    "editor-skeleton": "../editor-skeleton/index"
  },
  "componentPlaceholder": {
    "editor": "editor-skeleton"
  }
}

{
  "initialRenderingCache": "static"
}

// pages/home/index.js
Page({
  data: {
    shellReady: true,
    listStatus: 'loading', // loading | success | empty | error
  },
});

<!-- pages/home/index.wxml -->
<view class="home-shell">
  <view class="home-title">精选商品</view>
  <view wx:if="{{shellReady}}" class="home-skeleton">
    <view class="skeleton-row" />
    <view class="skeleton-row" />
    <view class="skeleton-row short" />
  </view>
</view>

// src/app.config.js
export default {
  pages: [
    'pages/home/index',
    'pages/profile/index',
  ],
  subpackages: [
    {
      root: 'package-trade',
      pages: [
        'pages/order-list/index',
        'pages/order-detail/index',
      ],
    },
    {
      root: 'package-activity',
      pages: [
        'pages/campaign/index',
      ],
    },
    {
      root: 'package-share',
      pages: ['pages/landing/index'],
      independent: true,
    },
  ],
  preloadRule: {
    'pages/home/index': {
      network: 'all',
      packages: ['package-trade'],
    },
    'package-share/pages/landing/index': {
      network: 'wifi',
      packages: ['__APP__'],
    },
  },
  lazyCodeLoading: 'requiredComponents',
  window: {
    navigationBarTitleText: 'MiniApp',
    navigationBarBackgroundColor: '#ffffff',
    navigationBarTextStyle: 'black',
  },
};

import Taro from '@tarojs/taro';

export function openOrderDetail(orderId: string) {
  return Taro.navigateTo({
    url: `/package-trade/pages/order-detail/index?id=${orderId}`,
  });
}

// config/index.js
const config = {
  mini: {
    optimizeMainPackage: {
      enable: true,
    },
  },
};

module.exports = config;

// pages.json
{
  "pages": [
    {
      "path": "pages/home/index",
      "style": { "navigationBarTitleText": "首页" }
    },
    {
      "path": "pages/profile/index",
      "style": { "navigationBarTitleText": "我的" }
    }
  ],
  "subPackages": [
    {
      "root": "package-trade",
      "pages": [
        {
          "path": "pages/order-list/index",
          "style": { "navigationBarTitleText": "订单" }
        },
        {
          "path": "pages/order-detail/index",
          "style": { "navigationBarTitleText": "订单详情" }
        }
      ]
    },
    {
      "root": "package-activity",
      "pages": [
        {
          "path": "pages/campaign/index",
          "style": { "navigationBarTitleText": "活动" }
        }
      ]
    },
    {
      "root": "package-share",
      "pages": [
        {
          "path": "pages/landing/index",
          "style": { "navigationBarTitleText": "邀请" }
        }
      ],
      "independent": true
    }
  ],
  "preloadRule": {
    "pages/home/index": {
      "network": "all",
      "packages": ["package-trade"]
    },
    "package-share/pages/landing/index": {
      "network": "wifi",
      "packages": ["__APP__"]
    }
  },
  "globalStyle": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f6f7f9"
  }
}

// manifest.json
{
  "name": "miniapp",
  "versionName": "1.0.0",
  "mp-weixin": {
    "appid": "wx-app-id",
    "setting": {
      "urlCheck": true,
      "es6": true,
      "minified": true
    },
    "lazyCodeLoading": "requiredComponents"
  }
}

uni.navigateTo({
  url: '/package-trade/pages/order-detail/index?id=1001',
});

// utils/performance.js
const METRICS = new Set(['appLaunch', 'route', 'firstRender']);
const records = [];

function toRecord(entry) {
  if (!METRICS.has(entry.name)) return;

  records.push({
    name: entry.name,
    entryType: entry.entryType,
    startTime: entry.startTime,
    duration: entry.duration,
    path: entry.path,
    raw: entry,
  });
}

export function collectPerformance(report) {
  const performance = wx.getPerformance();

  const observer = performance.createObserver((entryList) => {
    entryList.getEntries().forEach(toRecord);
    report(records);
  });

  observer.observe({ entryTypes: ['navigation', 'render'] });

  // observer 注册太晚可能错过早期 entry，导出前再读取一次全量列表。
  performance.getEntries().forEach(toRecord);
  return {
    records,
    disconnect: () => observer.disconnect(),
  };
}

实验 ID: package-split-2026-08-15
设备: Android low-end / iPhone mainstream
基础库: 3.x 实际版本
版本: 正式版 baseline vs treatment
入口: 首页冷启动 / 分享落地页冷启动

主包大小: baseline X KiB -> treatment Y KiB
总包大小: baseline X KiB -> treatment Y KiB
appLaunch P75: baseline X ms -> treatment Y ms
firstRender P75: baseline X ms -> treatment Y ms
内容可见 P75: baseline X ms -> treatment Y ms
核心分包路由 P75: baseline X ms -> treatment Y ms
失败率: baseline N% -> treatment N%

export const ROUTES = {
  orderDetail: (id) => `/package-trade/pages/order-detail/index?id=${id}`,
  campaign: '/package-activity/pages/campaign/index',
};