@taro-minify-pack/plugin-async-pack

异步加载主包代码，优化主包体积（包含异步模块js与样式文件）

✨ 功能特性

• 主包体积优化：将动态导入的模块自动拆分到异步分包，有效减少主包体积
• 样式文件异步加载：支持异步模块的样式文件同步异步加载
• 自动转换 React.lazy：无需手动修改代码，自动将 React.lazy 转换为增强版实现
• 灵活配置：可自定义异步分包名称前缀和数量
• 自动化处理：自动修改小程序配置文件和页面WXML，无需手动操作
• 性能提升：减少小程序启动时间，提升用户体验

📦 安装

必需依赖安装

使用该预设时，需要同时安装 @taro-minify-pack/react-lazy-enhanced或 @taro-minify-pack/vue-lazy-enhanced 包以支持异步组件样式加载：

react

npm 安装

npm install @taro-minify-pack/plugin-async-pack @taro-minify-pack/react-lazy-enhanced

yarn 安装

yarn add @taro-minify-pack/plugin-async-pack @taro-minify-pack/react-lazy-enhanced

pnpm 安装

pnpm add @taro-minify-pack/plugin-async-pack @taro-minify-pack/react-lazy-enhanced

vue

npm 安装

npm install @taro-minify-pack/plugin-async-pack @taro-minify-pack/vue-lazy-enhanced

yarn 安装

yarn add @taro-minify-pack/plugin-async-pack @taro-minify-pack/vue-lazy-enhanced

pnpm 安装

pnpm add @taro-minify-pack/plugin-async-pack @taro-minify-pack/vue-lazy-enhanced

⚙️ 配置

babel配置

// babel-preset-taro 更多选项和默认值：
// https://docs.taro.zone/docs/next/babel-config
module.exports = {
    presets: [
        ['taro', {
            framework: 'react',
            ts: true,
            compiler: 'webpack5',
            // 在原有基础上添加这个配置即可
            'dynamic-import-node': process.env.TARO_ENV !== 'weapp', 
        }]
    ]
}

Taro 配置

// config/index.js
module.exports = {
    compiler: {
        type: 'webpack5',
        prebundle: {
            // 关闭预打包,这里和分包异步编译有冲突
            enable: false,
        }
    },
    plugins: [
        ['@taro-minify-pack/plugin-async-pack', {
            // 框架类型，可选 'react' 或 'vue'
            framework: 'react',
            // 异步分包名前缀，默认为 'dynamic-common'
            dynamicPackageNamePrefix: 'dynamic-common',
            // 异步分包数量，默认为 1
            dynamicPackageCount: 2
        }],
    ],
};

🚀 使用

基本使用

// 动态导入模块
const module = await import('./dynamic-module')

React 组件懒加载

// 插件会自动将 React.lazy 转换为使用 @taro-minify-pack/react-lazy-enhanced 的实现
import { lazy, Suspense } from 'react'

const DynamicComponent = lazy(() => import('./DynamicComponent'))

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <DynamicComponent />
    </Suspense>
  )
}

Vue 组件懒加载

<template>
  <view class="index">
    <Suspense>
      <template #default>
         <AsyncComponent/>
      </template>
      <template #fallback>
        <view>loading...</view>
      </template>
    </Suspense>
  </view>
</template>

<script setup>
import {defineAsyncComponent, ref} from 'vue'
const AsyncComponent = defineAsyncComponent(() => import('./async-component')
)
</script>

📝 工作原理

1. Webpack 配置修改：

   • 覆盖 splitChunks 规则，使common与vendors只处理同步模块
   • 配置 chunkFilename 生成规则，确保异步模块正确输出到指定分包
   • 修改 miniCssExtractPlugin 配置，确保异步模块的样式文件也能正确拆分到指定分包

2. Babel 转换：

   • 自动将所有 React.lazy 调用转换为使用 @taro-minify-pack/react-lazy-enhanced 的实现
   • 无需手动修改代码即可获得增强功能

3. 样式处理：

   • 为每个异步分包生成样式组件
   • 自动收集该分包下的所有样式文件并通过 @import 引入
   • 确保异步模块的样式在组件加载时同步加载

4. 小程序配置修改：

   • 自动修改 app.json，添加异步分包配置
   • 添加异步组件到全局 usingComponents
   • 设置 componentPlaceholder 以优化渲染性能
   • 更新页面 WXML 文件，在每个页面中自动添加样式组件引用

⚠️ 注意事项

1. 仅支持微信小程序：当前插件仅适用于微信小程序环境
2. 关闭预打包：必须关闭 Taro 的预打包功能，否则可能与异步分包功能冲突
3. Babel 配置：需要正确配置 Babel 的 dynamic-import-node 选项
4. Webpack 版本：仅支持 Webpack 5 编译器
5. 自动转换：插件会自动转换所有 React.lazy 调用，无需手动使用 @taro-minify-pack/react-lazy-enhanced 包中的懒加载函数
6. 分包数量：根据项目实际情况配置 dynamicPackageCount，过多的分包可能会影响性能

🔧 配置选项

| 选项名 | 类型 | 默认值 | 描述 | |----------------------------|----------|--------------------|----------| | dynamicPackageNamePrefix | string | 'dynamic-common' | 异步分包名称前缀 | | dynamicPackageCount | number | 1 | 异步分包数量 |

🤝 常见问题

1. 异步模块没有被拆分到分包？

• 请检查是否正确配置了 dynamic-import-node 选项
• 确保已关闭 Taro 的预打包功能
• 确认使用了 Webpack 5 编译器
• 确保代码中使用了 import() 动态导入语法

2. 异步组件的样式没有加载？

• 请确保已正确安装 @taro-minify-pack/react-lazy-enhanced 包
• 检查是否有编译错误或警告信息

3. 配置后编译失败？

• 请检查配置选项是否正确
• 确认 Taro 版本与插件版本兼容
• 查看编译日志，排查具体错误原因

4. 页面加载时出现白屏？

• 请检查是否正确使用了 Suspense 组件包裹异步组件
• 确保异步组件的导入路径正确
• 检查网络请求是否正常

5. 分包数量配置后没有生效？

• 请确保 dynamicPackageCount 配置的值大于0
• 检查是否有足够的动态导入模块来拆分到多个分包

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

该插件是 @taro-minify-pack 系列插件的一部分，致力于提供完整的 Taro 项目优化解决方案。