App Ship

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

Languages: English | 简体中文

目录

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

⚡ 3分钟快速开始

1️⃣ 安装

npm install -g @huoye/app-ship

2️⃣ 初始化配置

app-ship init

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

3️⃣ 编辑配置文件

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

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

4️⃣ 上传应用

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

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

💡 需要上传到特定平台？使用 --platform 参数：

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 流水线和命令行用户。

常用命令：

# 查看支持的平台
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 库（编程集成）

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

多平台上传：

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}`);
  }
}

单平台上传：

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 插件文档。

支持平台

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

| 平台 | 文件 | 认证 | 官方 API 文档 | 状态 | | ---------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | 🐧 蒲公英 | APK, IPA | API Key | pgyer.com/api | ✅ 已实测 | | 🟥 华为 | APK, AAB | OAuth2 | AppGallery Connect | ✅ 已实测 | | 🔴 小米 | APK | RSA 签名 | 小米开放平台 | ✅ 已实测 | | 🟠 OPPO | APK | HMAC-SHA256 | OPPO 开发者平台 | ✅ 已实测 | | 🔵 vivo | APK | HMAC + MD5 | vivo 开放平台 | ✅ 已实测 | | 🐧 腾讯应用宝 | APK | HMAC-SHA256 | 应用宝平台 | ✅ 已实测 | | 🍎 Apple App Store | IPA | Apple ID / API | App Store Connect API | ✅ 已实测 | | 🟣 鸿蒙 | HAP | OAuth2 | AppGallery Connect | ✅ 已实测 | | 🍎 TestFlight | IPA | Apple API | TestFlight API | ⚠️ 开发中 | | 🍎 Ad Hoc | IPA | 证书 | Apple 文档 | ⚠️ 开发中 | | 🎮 Google Play | APK, AAB | Service Account | Google Play API | 🔄 v0.2.0 |

详细配置参考

完整的 app-ship.yaml 配置

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

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: "[email protected]"
      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} 语法引用环境变量，避免敏感信息硬编码：

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

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

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

常见问题

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

蒲公英: 登录 pgyer.com → 账号设置 → API 信息

华为: AppGallery Connect → 我的项目 → 项目设置 → 密钥管理

小米: 小米开放平台 → 应用管理 → 应用详情 → 上传接口

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

Apple: App Store Connect → 用户和访问权限 → API 密钥

Q: 上传失败如何排查？

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

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

2. 检查以下几点：

   • 网络连接正常
   • 各平台服务状态正常
   • API Key 和权限配置正确
   • 应用包格式是否正确

3. 查看 Issues 是否有类似问题

Q: 支持 Windows / Mac 吗？

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

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

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

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

GitHub Actions 示例：

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

   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

本地开发

# 安装依赖
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、日志）    │
└─────────────────────────────────┘

社区与支持

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

| 关注公众号 | 加作者微信入群 | 赞赏支持 | | :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: | | 火叶 | 微信: Huoye-TT（备注: flu-cli） | 给作者加鸡腿 ☕️ |

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

License

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