npm package: @huoye/app-ship
Description: 多平台应用商店上传引擎 — CLI 命令行工具 & npm 库，支持 APK / IPA / AAB / HAP 一键分发
Author: 火叶工作室
Latest version: 0.1.2

# App Ship

多平台应用商店上传引擎 — CLI 命令行工具 & npm 库，使用官方API来完成 APK / IPA / AAB / HAP 一键分发。

[![npm version](https://img.shields.io/npm/v/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship)
[![npm downloads](https://img.shields.io/npm/dm/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Languages**: [English](https://gitee.com/flu-cli/flu-cli/blob/main/packages/app-ship/README_EN.md) | 简体中文

## 目录

- [⚡ 3分钟快速开始](#-3分钟快速开始)
- [特性](#特性)
- [使用指南](#使用指南)
- [支持平台](#支持平台)
- [详细配置参考](#详细配置参考)
- [常见问题](#常见问题)
- [安全与隐私](#安全与隐私)
- [开发指南](#开发指南)
- [社区与支持](#社区与支持)

---

## ⚡ 3分钟快速开始

### 1️⃣ 安装

```bash
npm install -g @huoye/app-ship
```

### 2️⃣ 初始化配置

```bash
app-ship init
```

这会生成 `app-ship.yaml` 配置文件。

### 3️⃣ 编辑配置文件

在 `app-ship.yaml` 中填入你的平台 API Key（从各平台官方后台申请）：

```yaml
publish:
  pgyer:
    enable: true
    apiKey: "YOUR_PGYER_API_KEY" # 替换为你的 API Key
```

### 4️⃣ 上传应用

```bash
app-ship upload -c app-ship.yaml -f app-release.apk
```

✅ 完成！应用已上传到所有启用的平台。

> 💡 需要上传到特定平台？使用 `--platform` 参数：
>
> ```bash
> app-ship upload -c app-ship.yaml -f app.apk --platform pgyer,huawei
> ```

---

## 特性

- **8 大平台实测通过** ✅：蒲公英、华为、小米、OPPO、vivo、腾讯应用宝、App Store、鸿蒙
- **并行上传**：多平台同时上传，可配置并发数
- **智能分发**：自动路由 APK → Android 商店、IPA → Apple、HAP → 鸿蒙
- **指数退避重试**：网络波动自动重试，可配置退避策略
- **YAML 单配置**：一个配置文件管理所有平台凭据
- **三种使用方式**：CLI 命令行、npm 库、VSCode 插件
- **框架无关**：Flutter、React Native、原生 Android/iOS、鸿蒙均可使用
- **官方 API**：直接调用各平台官方 API，无第三方转接，透明开源

---

## 使用指南

### 1️⃣ CLI 命令行

适合 DevOps、CI/CD 流水线和命令行用户。

**常用命令**：

```bash
# 查看支持的平台
app-ship platforms

# 上传到所有启用的平台
app-ship upload -c app-ship.yaml -f app-release.apk

# 仅上传到指定平台
app-ship upload -c app-ship.yaml -f app-release.apk --platform pgyer,huawei

# 带元数据上传
app-ship upload -c app-ship.yaml -f app-release.apk \
  --version 2.0.0 \
  --build-number 42 \
  --changelog "修复了已知问题"

# 显示详细日志
app-ship upload -c app-ship.yaml -f app-release.apk --verbose

# 查看帮助
app-ship --help
app-ship --version
```

**CLI 参数说明**：

| 参数                 | 简写 | 说明                         |
| -------------------- | ---- | ---------------------------- |
| `--config <path>`    | `-c` | 配置文件路径 (YAML)          |
| `--file <path>`      | `-f` | 安装包路径 (APK/IPA/AAB/HAP) |
| `--platform <list>`  | `-p` | 逗号分隔的平台列表（可选）   |
| `--version <ver>`    | `-v` | 版本号（默认："1.0.0"）      |
| `--build-number <n>` | `-b` | 构建号（默认："1"）          |
| `--changelog <text>` | -    | 更新日志                     |
| `--verbose`          | -    | 显示详细输出                 |

---

### 2️⃣ npm 库（编程集成）

适合自建发布系统或集成到现有工作流。

**多平台上传**：

```typescript
import { UploadManager, ConfigValidator } from "@huoye/app-ship";

// 加载并验证配置
const config = ConfigValidator.loadAndValidate("./app-ship.yaml");

// 创建上传管理器
const manager = new UploadManager({
  maxConcurrent: 3, // 最大并发数
  continueOnError: true, // 部分失败后继续
  verbose: true, // 显示详细日志
});

// 执行上传
const report = await manager.uploadToMultiplePlatforms(
  "./app-release.apk",
  config,
  {
    version: "2.0.0",
    buildNumber: "42",
    changelog: "修复了已知问题",
  },
);

// 查看结果
console.log(`成功: ${report.successCount}, 失败: ${report.failureCount}`);
for (const result of report.results) {
  if (result.success) {
    console.log(`✅ ${result.platform}: ${result.url || result.consoleUrl}`);
  } else {
    console.log(`❌ ${result.platform}: ${result.message}`);
  }
}
```

**单平台上传**：

```typescript
import { PgyerUploader } from "@huoye/app-ship";

const uploader = new PgyerUploader();
const result = await uploader.upload(
  "./app-release.apk",
  { enable: true, apiKey: "YOUR_API_KEY" },
  { version: "1.0.0", buildNumber: "1", changelog: "首次发布" },
);

if (result.success) {
  console.log(`✅ 下载地址: ${result.url}`);
  console.log(`✅ 二维码: ${result.qrCode}`);
} else {
  console.log(`❌ 失败: ${result.message}`);
}
```

---

### 3️⃣ VSCode 插件（可视化）

安装 **Flu CLI** VSCode 插件，在 IDE 内点击操作即可完成构建和上传。

**功能特点**：

- 实时构建 & 上传进度展示
- 可视化配置面板
- 自动密钥管理
- 下载链接 + 二维码展示

详见 [VSCode 插件文档](https://gitee.com/flu-cli/flu-cli/tree/master/packages/vscode-extension#readme)。

---

## 支持平台

本工具直接调用各平台**官方 API**，所有 API 地址和文档均为平台官方提供。

| 平台                   | 文件     | 认证            | 官方 API 文档                                                                                                                               | 状态      |
| ---------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| 🐧 **蒲公英**          | APK, IPA | API Key         | [pgyer.com/api](https://www.pgyer.com/doc/view/api_basic)                                                                                   | ✅ 已实测 |
| 🟥 **华为**            | APK, AAB | OAuth2          | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/publish-app-0000001100974822)                  | ✅ 已实测 |
| 🔴 **小米**            | APK      | RSA 签名        | [小米开放平台](https://dev.mi.com/console/doc/detail?pId=1695)                                                                              | ✅ 已实测 |
| 🟠 **OPPO**            | APK      | HMAC-SHA256     | [OPPO 开发者平台](https://open.oppomobile.com/wiki/doc#id=10106)                                                                            | ✅ 已实测 |
| 🔵 **vivo**            | APK      | HMAC + MD5      | [vivo 开放平台](https://dev.vivo.com.cn/openAbility/interface)                                                                              | ✅ 已实测 |
| 🐧 **腾讯应用宝**      | APK      | HMAC-SHA256     | [应用宝平台](https://open.qq.com/doc/?id=11016)                                                                                             | ✅ 已实测 |
| 🍎 **Apple App Store** | IPA      | Apple ID / API  | [App Store Connect API](https://developer.apple.com/app-store-connect/api/)                                                                 | ✅ 已实测 |
| 🟣 **鸿蒙**            | HAP      | OAuth2          | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) | ✅ 已实测 |
| 🍎 **TestFlight**      | IPA      | Apple API       | [TestFlight API](https://developer.apple.com/testflight/testers/)                                                                           | ⚠️ 开发中 |
| 🍎 **Ad Hoc**          | IPA      | 证书            | [Apple 文档](https://developer.apple.com/documentation/xcode/distributing-your-app-for-beta-testing)                                        | ⚠️ 开发中 |
| 🎮 **Google Play**     | APK, AAB | Service Account | [Google Play API](https://developer.android.com/studio/publish)                                                                             | 🔄 v0.2.0 |

---

## 详细配置参考

### 完整的 app-ship.yaml 配置

所有 API 地址均来自官方平台，凭证需从各平台官方后台申请。

```yaml
version: "1.0.0"

# 重试策略（可选）
retry:
  maxRetries: 3
  initialDelayMs: 1000
  backoffMultiplier: 2
  maxDelayMs: 30000

publish:
  # ── 蒲公英 (官方 API: https://www.pgyer.com/doc/view/api_basic) ──
  pgyer:
    enable: true
    apiKey: "${PGYER_API_KEY}"
    description: "测试版本"

  # ── 华为 (官方 API: https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) ──
  huawei:
    enable: false
    auth:
      clientId: "${HUAWEI_CLIENT_ID}"
      clientSecret: "${HUAWEI_CLIENT_SECRET}"
    appId: "YOUR_APP_ID"
    releaseType: draft

  # ── 小米 (官方 API: https://dev.mi.com/console/doc/detail?pId=1695) ──
  xiaomi:
    enable: false
    auth:
      userName: "your@email.com"
      privateKey: "${XIAOMI_KEY}"
    packageName: "com.example.app"

  # ── OPPO (官方 API: https://open.oppomobile.com/wiki/doc#id=10106) ──
  oppo:
    enable: false
    auth:
      clientId: "${OPPO_CLIENT_ID}"
      clientSecret: "${OPPO_CLIENT_SECRET}"

  # ── vivo (官方 API: https://dev.vivo.com.cn/openAbility/interface) ──
  vivo:
    enable: false
    auth:
      accessKey: "${VIVO_ACCESS_KEY}"
      accessSecret: "${VIVO_ACCESS_SECRET}"

  # ── 腾讯应用宝 (官方 API: https://open.qq.com/doc/?id=11016) ──
  tencent:
    enable: false
    auth:
      userId: "${TENCENT_USER_ID}"
      appId: "${TENCENT_APP_ID}"
      accessSecret: "${TENCENT_SECRET}"

  # ── 鸿蒙 (官方 API: https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) ──
  harmony:
    enable: false
    auth:
      clientId: "${HARMONY_CLIENT_ID}"
      clientSecret: "${HARMONY_CLIENT_SECRET}"
    appId: "YOUR_APP_ID"

  # ── App Store / TestFlight (官方 API: https://developer.apple.com/app-store-connect/api/) ──
  app_store:
    enable: false
    mode: app_store
    auth:
      appleId: "${APPLE_ID}"
      appPassword: "${APP_PASSWORD}"

  # ── Google Play (官方 API: https://developer.android.com/studio/publish) ──
  google_play:
    enable: false
    auth:
      serviceAccountJsonPath: "./service-account.json"
    packageName: "com.example.app"
    track: production
```

### 环境变量支持

配置值支持 `${VAR_NAME}` 语法引用环境变量，避免敏感信息硬编码：

```yaml
pgyer:
  enable: true
  apiKey: ${PGYER_API_KEY} # 运行时自动替换
```

在 CI/CD 中设置环境变量即可：

```bash
export PGYER_API_KEY="your-actual-key"
app-ship upload -c app-ship.yaml -f app.apk
```

---

## 常见问题

### Q: 如何获取各平台的 API Key？

**蒲公英**: 登录 [pgyer.com](https://www.pgyer.com) → 账号设置 → API 信息

**华为**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → 我的项目 → 项目设置 → 密钥管理

**小米**: [小米开放平台](https://dev.mi.com/console/) → 应用管理 → 应用详情 → 上传接口

**OPPO/vivo/腾讯**: 对应开发者平台 → 应用管理 → API 管理

**Apple**: [App Store Connect](https://appstoreconnect.apple.com) → 用户和访问权限 → API 密钥

---

### Q: 上传失败如何排查？

1. 使用 `--verbose` 参数查看详细日志：

   ```bash
   app-ship upload -c app-ship.yaml -f app.apk --verbose
   ```

2. 检查以下几点：
   - 网络连接正常
   - 各平台服务状态正常
   - API Key 和权限配置正确
   - 应用包格式是否正确

3. 查看 [Issues](https://gitee.com/flu-cli/flu-cli/issues) 是否有类似问题

---

### Q: 支持 Windows / Mac 吗？

支持！本工具是跨平台的，可在以下环境运行：

- Windows 10+
- macOS 10.15+
- Linux (Ubuntu 18+, Fedora, etc.)

---

### Q: 可以在 CI/CD 中使用吗？

当然可以！使用环境变量存储凭证：

**GitHub Actions 示例**：

```yaml
- name: Upload App
  run: app-ship upload -c app-ship.yaml -f app.apk
  env:
    PGYER_API_KEY: ${{ secrets.PGYER_API_KEY }}
    HUAWEI_CLIENT_ID: ${{ secrets.HUAWEI_CLIENT_ID }}
    # ... 其他平台凭证
```

---

## 安全与隐私

### 🔐 密钥管理

- **用户掌控**：所有凭证仅保存在本地 `app-ship.yaml`，不上传到任何服务器
- **本地处理**：所有认证和签名操作都在你的机器本地执行
- **官方渠道**：直接调用各平台官方 API，无第三方转接

### 🛡️ 最佳实践

1. **保护配置文件** - 将 `app-ship.yaml` 加入 `.gitignore`：

   ```bash
   echo "app-ship.yaml" >> .gitignore
   ```

2. **在 CI/CD 中使用环境变量** - 不要提交凭证到版本控制

3. **定期轮换凭证** - 按各平台建议定期更新 API Key

4. **权限最小化** - 为 API Key 设置尽可能细粒度的权限

### 📜 法律声明

使用本工具时，你同意：

- 遵守各平台的服务协议和 API 使用政策
- 合法获取并妥善保管凭证和密钥
- 自行承担因不当使用造成的一切后果

本工具作者不对违规使用或产生的损失承担任何责任。

---

## 开发指南

### 项目结构

```
packages/app-ship/
├── src/
│   ├── index.ts                  # 📦 库入口 — 导出所有公共 API
│   ├── cli.ts                    # 🖥️ CLI 入口 — 命令行工具主程序
│   ├── types.ts                  # 📐 类型定义 — 所有接口和类型
│   ├── adapters/                 # 🔌 上传适配器层
│   │   ├── pgyer_uploader.ts
│   │   ├── huawei_uploader.ts
│   │   ├── xiaomi_uploader.ts
│   │   └── ...
│   ├── utils/                    # 🔧 工具层
│   │   ├── upload-manager.ts     # 并发调度 + 智能分发
│   │   ├── retry-strategy.ts     # 指数退避 + 错误分类
│   │   └── ...
│   └── validators/               # ✅ 验证层
│       ├── config_validator.ts
│       └── env_validator.ts
├── dist/
├── package.json
└── tsconfig.json
```

### 本地开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听文件变化）
npm run dev
```

### 新增平台支持（3 步）

1. **实现 `IUploader` 接口**（在 `src/adapters/` 下）
2. **在 `src/adapters/index.ts` 导出**
3. **在 `src/utils/upload-manager.ts` 注册**

详见源码注释。

---

## 目录架构

```
┌─────────────────────────────────┐
│        用户界面层                 │
├──────┬─────────────┬─────────────┤
│ CLI  │ VSCode 插件 │ npm 库      │
└──┬───┴──────┬──────┴──────┬──────┘
   │          │             │
   ▼          ▼             ▼
┌─────────────────────────────────┐
│     配置管理 & 验证               │
└──────────────┬──────────────────┘
               ▼
┌─────────────────────────────────┐
│   上传管理（并发、智能分发）      │
└──────────────┬──────────────────┘
               ▼
┌─────────────────────────────────┐
│   平台适配器（8+ 个平台）        │
└──────────────┬──────────────────┘
               ▼
┌─────────────────────────────────┐
│   基础设施（重试、JWT、日志）    │
└─────────────────────────────────┘
```

---

## 社区与支持

扫描下方二维码或搜索公众号**火叶**关注我们

|                                                                   关注公众号                                                                   |                                                                                    加作者微信入群                                                                                     |                                赞赏支持                                |
| :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: |
| <img src="https://gitee.com/flu-cli/flu-cli/raw/master/packages/vscode-extension/images/qcode-wx.jpg" alt="微信号" width="160"/> <br> **火叶** | <img src="https://gitee.com/flu-cli/flu-cli/raw/master/packages/vscode-extension/images/wechat-group.png" alt="微信号" width="160"/> <br> **微信**: `Huoye-TT`<br>（备注: `flu-cli`） | [给作者加鸡腿 ☕️](http://huozhiye.cn/flu-cli/advanced/rewards/rewards) |

> 💡 你也可以点击插件详情页顶部的 **Sponsor** 按钮来支持本项目。

---

## License

MIT | Copyright © 2025-2026 火叶工作室