# app-ship **Repository Path**: flu-cli/app-ship ## Basic Information - **Project Name**: app-ship - **Description**: 一站式多平台 App 上传工具。支持全平台安装包（安卓/iOS/鸿蒙）一键分发至各大应用商店，提供透明开源、官方 API 调用、多并发上传及环境变量配置支持。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-03-24 - **Last Updated**: 2026-04-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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 ` | `-c` | 配置文件路径 (YAML) | | `--file ` | `-f` | 安装包路径 (APK/IPA/AAB/HAP) | | `--platform ` | `-p` | 逗号分隔的平台列表（可选） | | `--version ` | `-v` | 版本号（默认："1.0.0"） | | `--build-number ` | `-b` | 构建号（默认："1"） | | `--changelog ` | - | 更新日志 | | `--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、日志） │ └─────────────────────────────────┘ ``` --- ## 社区与支持 扫描下方二维码或搜索公众号**火叶**关注我们 | 关注公众号 | 加作者微信入群 | 赞赏支持 | | :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: | | 微信号
**火叶** | 微信号
**微信**: `Huoye-TT`
（备注: `flu-cli`） | [给作者加鸡腿 ☕️](http://huozhiye.cn/flu-cli/advanced/rewards/rewards) | > 💡 你也可以点击插件详情页顶部的 **Sponsor** 按钮来支持本项目。 --- ## License MIT | Copyright © 2025-2026 火叶工作室