npm package: @oukeye/wechat-mp-build-upload-tool
Description: 微信小程序自动化打包上传工具
Latest version: 1.0.0

# 微信小程序自动化打包上传工具

一个独立的微信小程序自动化构建和上传工具，支持批量构建、多环境配置，并自动上传到微信平台。

## 功能特性

- ✅ **自动化构建**：一键构建多个微信小程序
- ✅ **自动上传**：自动上传代码到微信平台，支持版本号和描述
- ✅ **多配置管理**：支持不同小程序使用不同的配置（AppID、环境变量等）
- ✅ **批量处理**：支持一次性处理多个小程序
- ✅ **灵活配置**：通过 JSON 文件管理配置，易于维护
- ✅ **全局安装**：作为 npm 全局工具安装，可在任何项目中使用

## 安装

使用 npm 全局安装：

```bash
npm install -g wechat-mp-build-upload-tool
```

安装完成后，你将获得三个全局命令：
- `mp-build-upload`: 构建并上传
- `mp-build`: 仅构建
- `mp-upload`: 仅上传

## 快速开始

### 1. 准备配置文件

在你的项目根目录下创建一个 `mp-configs` 文件夹，并添加小程序配置文件（JSON 格式）。

```bash
my-project/
├── mp-configs/
│   ├── app-1.json
│   └── app-2.json
└── ...
```

### 2. 创建配置文件

例如 `mp-configs/app-1.json`：

```json
{
  "name": "我的小程序1",
  "appid": "xxxxxxx",
  "projectPath": "dist/build/mp-weixin",
  "version": "1.0.0",
  "desc": "自动上传",
  "env": {
    "VITE_API_URL": "https://api.example.com",
    "VITE_APP_TITLE": "My App"
  }
}
```

**配置说明：**
- **name**: 小程序名称（日志显示用）
- **appid**: 微信小程序 AppID
- **projectPath**: 构建输出路径（相对于项目根目录的相对路径）
- **version**: 上传版本号（可选，默认 1.0.0）
- **desc**: 上传描述（可选，默认 "自动上传"）
- **env**: 环境变量对象，构建时会写入 `.env.local`

### 3. 运行命令

在项目根目录下运行：

```bash
# 构建并上传所有小程序
mp-build-upload

# 构建并上传指定小程序（配置文件的文件名，不含后缀）
mp-build-upload app-1

# 覆盖版本号和描述
mp-build-upload app-1 --version=1.1.0 --desc="修复已知问题"

# 仅构建（不上传）
mp-build app-1

# 仅上传（适用于已经构建好的情况）
mp-upload app-1
```

## 详细使用说明

### 命令行参数

#### `mp-build-upload` (构建并上传)

```bash
mp-build-upload [小程序名称...] [选项]
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `小程序名称` | 指定要处理的配置名称（对应 JSON 文件名） | `app-1` `app-2` |
| `--version` | 指定上传版本号（覆盖配置文件） | `--version=1.2.0` |
| `--desc` | 指定上传描述（覆盖配置文件） | `--desc="功能更新"` |
| `--help` | 显示帮助信息 | `--help` |

#### `mp-build` (仅构建)

```bash
mp-build [小程序名称...] [选项]
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `小程序名称` | 指定要处理的配置名称 | `app-1` `app-2` |
| `--help` | 显示帮助信息 | `--help` |

#### `mp-upload` (仅上传)

```bash
mp-upload <小程序名称> [选项]
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `小程序名称` | 指定要上传的配置名称 | `app-1` |
| `--version` | 指定上传版本号 | `--version=1.2.0` |
| `--desc` | 指定上传描述 | `--desc="功能更新"` |

### 环境变量覆盖

你也可以通过环境变量来覆盖版本号和描述（优先级：命令行参数 > 环境变量 > 配置文件）：

```bash
# Linux/macOS
VERSION=2.0.0 DESC="大版本更新" mp-build-upload app-1

# Windows PowerShell
$env:VERSION="2.0.0"; $env:DESC="大版本更新"; mp-build-upload app-1
```

## 前置条件

### 1. 微信开发者工具

确保已安装微信开发者工具，并开启服务端口（设置 -> 安全设置 -> 服务端口 -> 打开）。

**重要：** 运行命令前，请确保微信开发者工具**已启动并登录**。

### 2. 配置 CLI 路径（如需）

工具会自动在默认路径查找微信开发者工具 CLI。如果安装在非标准路径，请设置环境变量 `WECHAT_CLI_PATH`：

- **Windows**: `C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`
- **macOS**: `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`

```bash
# 示例：设置自定义路径
export WECHAT_CLI_PATH="/path/to/cli"
```

## 项目结构要求

工具假设你的项目符合常规的 uni-app 或类似结构，关键在于配置文件中的 `projectPath` 要指向正确的构建输出目录。

```
my-project/
├── mp-configs/             # [必须] 存放小程序配置文件的目录
│   └── *.json
├── src/                    # 源代码
├── dist/                   # 构建输出
│   └── build/
│       └── mp-weixin/      # [配置] projectPath 应指向这里
└── ...
```

## 常见问题

### 1. 找不到配置文件
确保在当前执行命令的目录下存在 `mp-configs` 文件夹，且里面有 `.json` 结尾的配置文件。

### 2. 微信开发者工具未运行
上传功能依赖微信开发者工具 CLI，请确保工具已启动并登录。

### 3. 上传失败
- 检查 AppID 是否正确且有权限。
- 检查是否开启了代码上传白名单或 IP 限制。

## 许可证

MIT