subpackage-component-placeholder/README.md

微信小程序分包组件占位插件

# SubpackageComponentPlaceholder 使用指南

## 简介

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

## 功能

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

## 安装

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

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

## 配置

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

```javascript
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`：

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

插件会自动将其转换为：

```json
{
  "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: 可以，只需在插件配置中指定：

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

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

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

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

## 贡献

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