SubpackageComponentPlaceholder 使用指南

简介

SubpackageComponentPlaceholder 是一个用于微信小程序的 Webpack 插件，它自动检测跨分包引用的组件，并为这些组件添加占位组件配置，以避免微信小程序的跨分包组件引用限制。

功能

• 自动扫描项目中的所有 JSON 配置文件
• 检测跨分包引用的组件
• 为这些组件添加 componentPlaceholder 配置
• 默认使用 view 作为占位组件，可自定义

安装

首先，确保你的项目是基于 uni-app 或类似框架构建的微信小程序项目。

npm install subpackage-component-placeholder --save-dev
# 或
yarn add subpackage-component-placeholder --dev

配置

在你的 Webpack 配置文件中添加插件：

const SubpackageComponentPlaceholder = require('subpackage-component-placeholder');

module.exports = {
  // ...其他配置
  plugins: [
    new SubpackageComponentPlaceholder({
      placeholderComponent: 'view' // 可选，默认是 'view'
    })
  ]
};

选项

| 选项名称 | 类型 | 默认值 | 描述 | |---------|------|--------|------| | placeholderComponent | string | 'view' | 指定用作占位符的组件名称 |

工作原理

1. 插件首先会解析 app.json 文件，获取所有分包配置信息
2. 然后扫描项目中所有 JSON 配置文件中的 usingComponents 部分
3. 对于每个引用的组件，检查它是否属于另一个分包
4. 如果是跨分包引用，则自动添加 componentPlaceholder 配置
5. 最终修改后的 JSON 文件会被写入到编译输出中

示例

假设你的项目结构如下：

project/
├── app.json
├── pages/
│   └── index/
│       └── index.json
└── subpackages/
    └── sub1/
        └── pages/
            └── subpage/
                └── subpage.json

如果 pages/index/index.json 引用了 subpackages/sub1/pages/subpage/components/my-component：

{
  "usingComponents": {
    "my-component": "/subpackages/sub1/pages/subpage/components/my-component"
  }
}

插件会自动将其转换为：

{
  "usingComponents": {
    "my-component": "/subpackages/sub1/pages/subpage/components/my-component"
  },
  "componentPlaceholder": {
    "my-component": "view"
  }
}

注意事项

1. 插件仅在 mp-weixin 平台（微信小程序）生效
2. 不会处理 node_modules 中的组件
3. 同一个分包内的组件引用不会被处理
4. 确保你的 app.json 中正确配置了 subPackages 或 subpackages

常见问题

Q: 为什么我的组件没有被处理？

A: 请检查：

• 组件是否确实位于另一个分包中
• 项目是否设置为微信小程序平台 (mp-weixin)

Q: 我可以使用自定义组件作为占位符吗？

A: 可以，只需在插件配置中指定：

new SubpackageComponentPlaceholder({
  placeholderComponent: 'your-custom-placeholder'
})

确保你的自定义组件已经在全局或页面中注册。

Q: 插件会影响开发环境的热更新吗？

A: 不会，插件只在编译过程中修改输出文件，不会影响开发环境的实时预览。

贡献

欢迎提交 Issue 或 Pull Request 来改进这个插件。