# 微信小程序miniprogram-ci示例接口API代码

**Repository Path**: rivuai/miniprogram-ci

## Basic Information

- **Project Name**: 微信小程序miniprogram-ci示例接口API代码
- **Description**: 微信小程序miniprogram-ci示例接口API代码，微信小程序线传接口全封装代码
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-03
- **Last Updated**: 2025-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微信小程序代码上传API服务 - 更新版

这是一个基于微信小程序CI工具的代码上传API服务，支持多小程序管理、文件上传和远程代码发布功能。

## 🆕 新功能特性

- 🗂️ **多代码包管理** - 支持上传多个不同的小程序前端代码包
- 📁 **文件上传接口** - 直接上传ZIP压缩包到服务器
- 🏷️ **版本管理** - 按时间戳自动命名，支持多版本共存
- 🔄 **灵活选择** - 可指定使用哪个代码包进行发布
- 📋 **文件夹列表** - 查看所有已上传的代码包

## 🚀 功能特性

- 🚀 自动复制代码副本并按时间命名
- 🔧 自动替换配置文件中的appid、域名、uniacid等参数
- 📦 使用官方miniprogram-ci工具上传代码
- 🧹 自动清理临时文件
- ✅ 完整的错误处理和日志记录
- 🗂️ 支持多个小程序项目管理

## 📋 API接口一览

| 接口 | 方法 | 路径 | 功能 |
|------|------|------|------|
| 健康检查 | GET | `/health` | 检查服务状态 |
| 上传文件 | POST | `/upload-file` | 上传小程序代码包 |
| 获取文件夹列表 | GET | `/folders` | 查看已上传的代码包 |
| 上传代码 | POST | `/upload` | 发布小程序到微信后台 |

## 安装依赖

```bash
npm install
```

## 启动服务

```bash
# 方法一：使用启动脚本（推荐）
./start.sh

# 方法二：手动启动
npm start

# 开发环境启动（自动重启）
npm run dev
```

服务默认运行在 `http://localhost:3000`

## 🔐 安全认证

⚠️ **重要提醒：** 除健康检查接口外，所有API接口都需要进行密钥验证！

**API密钥：** `yueqiankejiyueqiankejiyueqiankeji`

**在所有API请求中添加请求头：**
```bash
X-API-Key: yueqiankejiyueqiankejiyueqiankeji
```

或者使用Authorization头：
```bash
Authorization: Bearer yueqiankejiyueqiankejiyueqiankeji
```

**如果密钥验证失败，将返回以下错误：**
- `401 Unauthorized` - 缺少API密钥
- `403 Forbidden` - API密钥无效

## 🛠️ 完整使用流程

### 步骤1: 上传代码包

**使用 cURL:**
```bash
curl -X POST http://localhost:3000/upload-file \
  -H "X-API-Key: yueqiankejiyueqiankejiyueqiankeji" \
  -F "file=@/path/to/your/miniprogram.zip"
```

**响应示例:**
```json
{
  "success": true,
  "message": "文件上传并解压成功",
  "data": {
    "folderName": "code_1703123456789",
    "timestamp": 1703123456789,
    "originalName": "miniprogram.zip",
    "uploadTime": "2023-12-21T03:04:16.789Z"
  }
}
```

### 步骤2: 查看已上传的文件夹

```bash
curl -X GET http://localhost:3000/folders \
  -H "X-API-Key: yueqiankejiyueqiankejiyueqiankeji"
```

**响应示例:**
```json
{
  "success": true,
  "message": "获取文件夹列表成功",
  "data": {
    "folders": [
      {
        "folderName": "code_1703123456789",
        "timestamp": "1703123456789",
        "createTime": "2023-12-21T03:04:16.789Z",
        "modifyTime": "2023-12-21T03:04:16.789Z"
      }
    ],
    "total": 1
  }
}
```

### 步骤3: 使用指定文件夹上传代码

```bash
curl -X POST http://localhost:3000/upload \
  -H "Content-Type: application/json" \
  -H "X-API-Key: yueqiankejiyueqiankejiyueqiankeji" \
  -d '{
    "appid": "wx1234567890abcdef",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "backendDomain": "api.example.com",
    "uniacid": 123,
    "entryPagePath": "pages/index/index",
    "folderName": "code_1703123456789"
  }'
```

## 💡 使用场景

### 1. 多端小程序管理

```javascript
// 上传用户端代码包
const userAppResult = await uploadFile('user-miniprogram.zip');

// 上传商家端代码包  
const merchantAppResult = await uploadFile('merchant-miniprogram.zip');

// 分别发布到不同的小程序
await uploadToWeChat({
    appid: 'wx_user_appid',
    folderName: userAppResult.folderName,
    // ... 其他参数
});

await uploadToWeChat({
    appid: 'wx_merchant_appid', 
    folderName: merchantAppResult.folderName,
    // ... 其他参数
});
```

### 2. 版本管理

```javascript
// 上传不同版本
const v1 = await uploadFile('miniprogram-v1.0.zip');
const v2 = await uploadFile('miniprogram-v2.0.zip');

// 选择版本发布
await uploadToWeChat({
    folderName: v2.folderName, // 使用v2版本
    // ... 其他参数
});
```

## 🗂️ 目录结构

```
project/
├── code/                          # 存放上传的代码包
│   ├── code_1703123456789/       # 时间戳命名的文件夹
│   │   ├── code/                 # 解压的原始代码
│   │   └── codecopy/             # 代码副本（用于上传）
│   └── code_1703123456790/
│       ├── code/
│       └── codecopy/
├── codecopy/                      # 默认代码目录（向后兼容）
├── uploads/                       # 临时上传目录
├── upload-service.js              # 服务主文件
├── test-file-upload.js           # 文件上传测试脚本
└── examples/                      # 示例文件夹
    └── complete-workflow-example.js
```

## 🔧 参数说明

### 上传文件接口参数

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| file | file | ✅ | ZIP格式的小程序代码压缩包 |

### 上传代码接口参数

| 参数名 | 类型 | 必需 | 描述 | 示例 |
|--------|------|------|------|------|
| appid | string | ✅ | 小程序AppID | `"wx1234567890abcdef"` |
| privateKey | string | ✅ | 小程序上传密钥内容 | `"-----BEGIN PRIVATE KEY-----\n..."` |
| backendDomain | string | ✅ | 后端域名（不含协议） | `"api.example.com"` |
| uniacid | number | ✅ | 后端uniacid数字 | `123` |
| entryPagePath | string | ✅ | 小程序首页路径 | `"pages/index/index"` |
| **folderName** | string | ❌ | **[新增]** 指定文件夹名 | `"code_1703123456789"` |

> **注意：** 新增的 `folderName` 参数用于指定使用哪个已上传的代码包。不传此参数时使用默认的 `codecopy` 目录。

## 🔍 测试工具

```bash
# 测试文件上传功能
node test-file-upload.js --full

# 测试代码上传功能
node test-upload.js

# 运行完整工作流程示例
node examples/complete-workflow-example.js

# 显示CURL命令示例
node test-file-upload.js --curl
```

## 🛠️ JavaScript SDK 使用示例

```javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

class MiniProgramManager {
    constructor(baseUrl = 'http://localhost:3000') {
        this.baseUrl = baseUrl;
    }

    // 上传文件
    async uploadFile(filePath) {
        const formData = new FormData();
        formData.append('file', fs.createReadStream(filePath));
        
        const response = await axios.post(`${this.baseUrl}/upload-file`, formData, {
            headers: formData.getHeaders()
        });
        
        return response.data.data;
    }

    // 获取文件夹列表
    async getFolders() {
        const response = await axios.get(`${this.baseUrl}/folders`);
        return response.data.data;
    }

    // 上传到微信
    async uploadToWeChat(config) {
        const response = await axios.post(`${this.baseUrl}/upload`, config);
        return response.data.data;
    }
}

// 使用示例
async function main() {
    const manager = new MiniProgramManager();
    
    // 1. 上传代码包
    const uploadResult = await manager.uploadFile('./miniprogram.zip');
    console.log('上传成功:', uploadResult.folderName);
    
    // 2. 发布到微信
    const wxResult = await manager.uploadToWeChat({
        appid: 'wx1234567890abcdef',
        privateKey: 'your-private-key',
        backendDomain: 'api.example.com',
        uniacid: 123,
        entryPagePath: 'pages/index/index',
        folderName: uploadResult.folderName
    });
    console.log('发布成功:', wxResult);
}
```

## 📤 工作原理

1. **文件上传阶段:**
   - 接收ZIP压缩包
   - 创建按时间戳命名的文件夹 (`code_时间戳`)
   - 解压文件到 `code/` 子目录
   - 复制到 `codecopy/` 子目录作为备份

2. **代码发布阶段:**
   - 根据 `folderName` 参数选择代码包
   - 复制到临时目录
   - 替换配置文件中的参数
   - 使用 miniprogram-ci 上传到微信
   - 清理临时文件

## 使用前准备

1. **获取小程序上传密钥：**
   - 登录微信公众平台
   - 进入"管理-开发管理-开发设置-小程序代码上传"
   - 生成「代码上传密钥」
   - 配置IP白名单（建议开启）

2. **准备代码包：**
   - 将小程序源代码打包成ZIP文件
   - 确保包含完整的项目结构

## 🐛 常见问题

### Q: 如何知道使用哪个文件夹名？
**A:** 调用 `/folders` 接口获取所有可用的文件夹列表

### Q: 支持哪些文件格式？
**A:** 目前只支持ZIP格式的压缩包，文件大小限制100MB

### Q: 可以删除旧的代码包吗？
**A:** 可以手动删除 `code/` 目录下不需要的文件夹

### Q: 不传folderName参数会怎样？
**A:** 系统会使用默认的 `codecopy` 目录，保持向后兼容

### Q: 上传失败怎么办？
**A:** 检查文件格式、网络连接、密钥配置和IP白名单设置

## ⚠️ 注意事项

1. **密钥安全：** 私钥包含敏感信息，请妥善保管
2. **IP白名单：** 确保服务器IP在微信公众平台的白名单中
3. **文件大小：** 上传文件限制100MB以内
4. **并发限制：** 避免同时发起多个上传请求
5. **向后兼容：** 现有的接口调用方式仍然有效

## 📚 详细文档

- [API调用指南-更新版.md](./API调用指南-更新版.md) - 完整的接口文档
- [examples/](./examples/) - 各种使用示例
- [test-file-upload.js](./test-file-upload.js) - 文件上传测试脚本

## 环境要求

- Node.js >= 14.0.0
- 网络可访问微信服务器

## 许可证

MIT License

---

**最后更新：** 2024年12月