@huoye/app-ship 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +57 -0
- package/README.md +314 -298
- package/dist/cli.js +909 -512
- package/dist/cli.js.map +1 -1
- package/dist/index.cjs +904 -507
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +141 -41
- package/dist/index.d.ts +141 -41
- package/dist/index.js +904 -507
- package/dist/index.js.map +1 -1
- package/package.json +37 -9
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# App Ship
|
|
2
2
|
|
|
3
|
-
多平台应用商店上传引擎 — CLI 命令行工具 & npm
|
|
3
|
+
多平台应用商店上传引擎 — CLI 命令行工具 & npm 库，使用官方API来完成 APK / IPA / AAB / HAP 一键分发。
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@huoye/app-ship)
|
|
6
6
|
[](https://www.npmjs.com/package/@huoye/app-ship)
|
|
@@ -8,48 +8,87 @@
|
|
|
8
8
|
|
|
9
9
|
**Languages**: [English](https://gitee.com/flu-cli/flu-cli/blob/main/packages/app-ship/README_EN.md) | 简体中文
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## 目录
|
|
12
12
|
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
13
|
+
- [⚡ 3分钟快速开始](#-3分钟快速开始)
|
|
14
|
+
- [特性](#特性)
|
|
15
|
+
- [使用指南](#使用指南)
|
|
16
|
+
- [支持平台](#支持平台)
|
|
17
|
+
- [详细配置参考](#详细配置参考)
|
|
18
|
+
- [常见问题](#常见问题)
|
|
19
|
+
- [安全与隐私](#安全与隐私)
|
|
20
|
+
- [开发指南](#开发指南)
|
|
21
|
+
- [社区与支持](#社区与支持)
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## ⚡ 3分钟快速开始
|
|
26
|
+
|
|
27
|
+
### 1️⃣ 安装
|
|
22
28
|
|
|
23
29
|
```bash
|
|
24
|
-
# 全局安装 CLI
|
|
25
30
|
npm install -g @huoye/app-ship
|
|
26
|
-
|
|
27
|
-
# 作为项目依赖
|
|
28
|
-
npm install @huoye/app-ship
|
|
29
31
|
```
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
### 2️⃣ 初始化配置
|
|
32
34
|
|
|
33
35
|
```bash
|
|
34
|
-
# 1. 安装
|
|
35
|
-
npm install -g @huoye/app-ship
|
|
36
|
-
|
|
37
|
-
# 2. 初始化配置
|
|
38
36
|
app-ship init
|
|
37
|
+
```
|
|
39
38
|
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
这会生成 `app-ship.yaml` 配置文件。
|
|
40
|
+
|
|
41
|
+
### 3️⃣ 编辑配置文件
|
|
42
|
+
|
|
43
|
+
在 `app-ship.yaml` 中填入你的平台 API Key（从各平台官方后台申请）：
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
publish:
|
|
47
|
+
pgyer:
|
|
48
|
+
enable: true
|
|
49
|
+
apiKey: "YOUR_PGYER_API_KEY" # 替换为你的 API Key
|
|
42
50
|
```
|
|
43
51
|
|
|
44
|
-
|
|
52
|
+
### 4️⃣ 上传应用
|
|
45
53
|
|
|
46
|
-
|
|
54
|
+
```bash
|
|
55
|
+
app-ship upload -c app-ship.yaml -f app-release.apk
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
✅ 完成！应用已上传到所有启用的平台。
|
|
59
|
+
|
|
60
|
+
> 💡 需要上传到特定平台？使用 `--platform` 参数：
|
|
61
|
+
>
|
|
62
|
+
> ```bash
|
|
63
|
+
> app-ship upload -c app-ship.yaml -f app.apk --platform pgyer,huawei
|
|
64
|
+
> ```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 特性
|
|
69
|
+
|
|
70
|
+
- **8 大平台实测通过** ✅：蒲公英、华为、小米、OPPO、vivo、腾讯应用宝、App Store、鸿蒙
|
|
71
|
+
- **并行上传**：多平台同时上传，可配置并发数
|
|
72
|
+
- **智能分发**：自动路由 APK → Android 商店、IPA → Apple、HAP → 鸿蒙
|
|
73
|
+
- **指数退避重试**：网络波动自动重试，可配置退避策略
|
|
74
|
+
- **YAML 单配置**：一个配置文件管理所有平台凭据
|
|
75
|
+
- **三种使用方式**：CLI 命令行、npm 库、VSCode 插件
|
|
76
|
+
- **框架无关**：Flutter、React Native、原生 Android/iOS、鸿蒙均可使用
|
|
77
|
+
- **官方 API**：直接调用各平台官方 API，无第三方转接，透明开源
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 使用指南
|
|
82
|
+
|
|
83
|
+
### 1️⃣ CLI 命令行
|
|
47
84
|
|
|
48
85
|
适合 DevOps、CI/CD 流水线和命令行用户。
|
|
49
86
|
|
|
87
|
+
**常用命令**：
|
|
88
|
+
|
|
50
89
|
```bash
|
|
51
|
-
#
|
|
52
|
-
app-ship
|
|
90
|
+
# 查看支持的平台
|
|
91
|
+
app-ship platforms
|
|
53
92
|
|
|
54
93
|
# 上传到所有启用的平台
|
|
55
94
|
app-ship upload -c app-ship.yaml -f app-release.apk
|
|
@@ -63,202 +102,214 @@ app-ship upload -c app-ship.yaml -f app-release.apk \
|
|
|
63
102
|
--build-number 42 \
|
|
64
103
|
--changelog "修复了已知问题"
|
|
65
104
|
|
|
66
|
-
#
|
|
67
|
-
app-ship
|
|
105
|
+
# 显示详细日志
|
|
106
|
+
app-ship upload -c app-ship.yaml -f app-release.apk --verbose
|
|
68
107
|
|
|
69
108
|
# 查看帮助
|
|
70
109
|
app-ship --help
|
|
110
|
+
app-ship --version
|
|
71
111
|
```
|
|
72
112
|
|
|
73
113
|
**CLI 参数说明**：
|
|
74
114
|
|
|
75
|
-
| 参数 | 简写 | 说明
|
|
76
|
-
| -------------------- | ---- |
|
|
77
|
-
| `--config <path>` | `-c` | 配置文件路径 (YAML)
|
|
78
|
-
| `--file <path>` | `-f` | 安装包路径 (APK/IPA/AAB/HAP)
|
|
79
|
-
| `--platform <list>` | `-p` |
|
|
80
|
-
| `--version <ver>` | `-v` |
|
|
81
|
-
| `--build-number <n>` | `-b` | 构建号（默认："1"）
|
|
82
|
-
| `--changelog <text>` |
|
|
83
|
-
| `--verbose` |
|
|
115
|
+
| 参数 | 简写 | 说明 |
|
|
116
|
+
| -------------------- | ---- | ---------------------------- |
|
|
117
|
+
| `--config <path>` | `-c` | 配置文件路径 (YAML) |
|
|
118
|
+
| `--file <path>` | `-f` | 安装包路径 (APK/IPA/AAB/HAP) |
|
|
119
|
+
| `--platform <list>` | `-p` | 逗号分隔的平台列表（可选） |
|
|
120
|
+
| `--version <ver>` | `-v` | 版本号（默认："1.0.0"） |
|
|
121
|
+
| `--build-number <n>` | `-b` | 构建号（默认："1"） |
|
|
122
|
+
| `--changelog <text>` | - | 更新日志 |
|
|
123
|
+
| `--verbose` | - | 显示详细输出 |
|
|
84
124
|
|
|
85
|
-
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
### 2️⃣ npm 库（编程集成）
|
|
86
128
|
|
|
87
129
|
适合自建发布系统或集成到现有工作流。
|
|
88
130
|
|
|
131
|
+
**多平台上传**：
|
|
132
|
+
|
|
89
133
|
```typescript
|
|
90
|
-
import { UploadManager, ConfigValidator } from
|
|
134
|
+
import { UploadManager, ConfigValidator } from "@huoye/app-ship";
|
|
91
135
|
|
|
92
136
|
// 加载并验证配置
|
|
93
|
-
const config = ConfigValidator.loadAndValidate(
|
|
137
|
+
const config = ConfigValidator.loadAndValidate("./app-ship.yaml");
|
|
94
138
|
|
|
95
139
|
// 创建上传管理器
|
|
96
140
|
const manager = new UploadManager({
|
|
97
141
|
maxConcurrent: 3, // 最大并发数
|
|
98
142
|
continueOnError: true, // 部分失败后继续
|
|
99
143
|
verbose: true, // 显示详细日志
|
|
100
|
-
})
|
|
144
|
+
});
|
|
101
145
|
|
|
102
146
|
// 执行上传
|
|
103
|
-
const report = await manager.uploadToMultiplePlatforms(
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
147
|
+
const report = await manager.uploadToMultiplePlatforms(
|
|
148
|
+
"./app-release.apk",
|
|
149
|
+
config,
|
|
150
|
+
{
|
|
151
|
+
version: "2.0.0",
|
|
152
|
+
buildNumber: "42",
|
|
153
|
+
changelog: "修复了已知问题",
|
|
154
|
+
},
|
|
155
|
+
);
|
|
108
156
|
|
|
109
157
|
// 查看结果
|
|
110
|
-
console.log(`成功: ${report.successCount}, 失败: ${report.failureCount}`)
|
|
111
|
-
console.log(`总耗时: ${report.totalDurationMs}ms`)
|
|
112
|
-
|
|
113
|
-
// 遍历每个平台的结果
|
|
158
|
+
console.log(`成功: ${report.successCount}, 失败: ${report.failureCount}`);
|
|
114
159
|
for (const result of report.results) {
|
|
115
160
|
if (result.success) {
|
|
116
|
-
console.log(`✅ ${result.platform}: ${result.url || result.consoleUrl}`)
|
|
161
|
+
console.log(`✅ ${result.platform}: ${result.url || result.consoleUrl}`);
|
|
117
162
|
} else {
|
|
118
|
-
console.log(`❌ ${result.platform}: ${result.message}`)
|
|
163
|
+
console.log(`❌ ${result.platform}: ${result.message}`);
|
|
119
164
|
}
|
|
120
165
|
}
|
|
121
166
|
```
|
|
122
167
|
|
|
123
|
-
|
|
168
|
+
**单平台上传**：
|
|
124
169
|
|
|
125
170
|
```typescript
|
|
126
|
-
import { PgyerUploader } from
|
|
171
|
+
import { PgyerUploader } from "@huoye/app-ship";
|
|
127
172
|
|
|
128
|
-
const uploader = new PgyerUploader()
|
|
173
|
+
const uploader = new PgyerUploader();
|
|
129
174
|
const result = await uploader.upload(
|
|
130
|
-
|
|
131
|
-
{ enable: true, apiKey:
|
|
132
|
-
{ version:
|
|
133
|
-
)
|
|
175
|
+
"./app-release.apk",
|
|
176
|
+
{ enable: true, apiKey: "YOUR_API_KEY" },
|
|
177
|
+
{ version: "1.0.0", buildNumber: "1", changelog: "首次发布" },
|
|
178
|
+
);
|
|
134
179
|
|
|
135
180
|
if (result.success) {
|
|
136
|
-
console.log(
|
|
137
|
-
console.log(
|
|
181
|
+
console.log(`✅ 下载地址: ${result.url}`);
|
|
182
|
+
console.log(`✅ 二维码: ${result.qrCode}`);
|
|
183
|
+
} else {
|
|
184
|
+
console.log(`❌ 失败: ${result.message}`);
|
|
138
185
|
}
|
|
139
186
|
```
|
|
140
187
|
|
|
141
|
-
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
### 3️⃣ VSCode 插件（可视化）
|
|
142
191
|
|
|
143
192
|
安装 **Flu CLI** VSCode 插件，在 IDE 内点击操作即可完成构建和上传。
|
|
144
193
|
|
|
145
|
-
|
|
194
|
+
**功能特点**：
|
|
146
195
|
|
|
147
196
|
- 实时构建 & 上传进度展示
|
|
148
197
|
- 可视化配置面板
|
|
149
198
|
- 自动密钥管理
|
|
150
199
|
- 下载链接 + 二维码展示
|
|
151
200
|
|
|
152
|
-
详见 [VSCode 插件文档](https://gitee.com/flu-cli/flu-cli/tree/
|
|
201
|
+
详见 [VSCode 插件文档](https://gitee.com/flu-cli/flu-cli/tree/master/packages/vscode-extension#readme)。
|
|
202
|
+
|
|
203
|
+
---
|
|
153
204
|
|
|
154
205
|
## 支持平台
|
|
155
206
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
|
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
|
207
|
+
本工具直接调用各平台**官方 API**，所有 API 地址和文档均为平台官方提供。
|
|
208
|
+
|
|
209
|
+
| 平台 | 文件 | 认证 | 官方 API 文档 | 状态 |
|
|
210
|
+
| ---------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
|
|
211
|
+
| 🐧 **蒲公英** | APK, IPA | API Key | [pgyer.com/api](https://www.pgyer.com/doc/view/api_basic) | ✅ 已实测 |
|
|
212
|
+
| 🟥 **华为** | APK, AAB | OAuth2 | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/publish-app-0000001100974822) | ✅ 已实测 |
|
|
213
|
+
| 🔴 **小米** | APK | RSA 签名 | [小米开放平台](https://dev.mi.com/console/doc/detail?pId=1695) | ✅ 已实测 |
|
|
214
|
+
| 🟠 **OPPO** | APK | HMAC-SHA256 | [OPPO 开发者平台](https://open.oppomobile.com/wiki/doc#id=10106) | ✅ 已实测 |
|
|
215
|
+
| 🔵 **vivo** | APK | HMAC + MD5 | [vivo 开放平台](https://dev.vivo.com.cn/openAbility/interface) | ✅ 已实测 |
|
|
216
|
+
| 🐧 **腾讯应用宝** | APK | HMAC-SHA256 | [应用宝平台](https://open.qq.com/doc/?id=11016) | ✅ 已实测 |
|
|
217
|
+
| 🍎 **Apple App Store** | IPA | Apple ID / API | [App Store Connect API](https://developer.apple.com/app-store-connect/api/) | ✅ 已实测 |
|
|
218
|
+
| 🟣 **鸿蒙** | HAP | OAuth2 | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) | ✅ 已实测 |
|
|
219
|
+
| 🍎 **TestFlight** | IPA | Apple API | [TestFlight API](https://developer.apple.com/testflight/testers/) | ⚠️ 开发中 |
|
|
220
|
+
| 🍎 **Ad Hoc** | IPA | 证书 | [Apple 文档](https://developer.apple.com/documentation/xcode/distributing-your-app-for-beta-testing) | ⚠️ 开发中 |
|
|
221
|
+
| 🎮 **Google Play** | APK, AAB | Service Account | [Google Play API](https://developer.android.com/studio/publish) | 🔄 v0.2.0 |
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 详细配置参考
|
|
169
226
|
|
|
170
|
-
|
|
227
|
+
### 完整的 app-ship.yaml 配置
|
|
171
228
|
|
|
172
|
-
|
|
229
|
+
所有 API 地址均来自官方平台，凭证需从各平台官方后台申请。
|
|
173
230
|
|
|
174
231
|
```yaml
|
|
175
|
-
version:
|
|
232
|
+
version: "1.0.0"
|
|
176
233
|
|
|
177
234
|
# 重试策略（可选）
|
|
178
235
|
retry:
|
|
179
|
-
maxRetries: 3
|
|
180
|
-
initialDelayMs: 1000
|
|
181
|
-
backoffMultiplier: 2
|
|
182
|
-
maxDelayMs: 30000
|
|
236
|
+
maxRetries: 3
|
|
237
|
+
initialDelayMs: 1000
|
|
238
|
+
backoffMultiplier: 2
|
|
239
|
+
maxDelayMs: 30000
|
|
183
240
|
|
|
184
241
|
publish:
|
|
185
|
-
# ── 蒲公英 ──
|
|
242
|
+
# ── 蒲公英 (官方 API: https://www.pgyer.com/doc/view/api_basic) ──
|
|
186
243
|
pgyer:
|
|
187
244
|
enable: true
|
|
188
|
-
apiKey:
|
|
189
|
-
description:
|
|
245
|
+
apiKey: "${PGYER_API_KEY}"
|
|
246
|
+
description: "测试版本"
|
|
190
247
|
|
|
191
|
-
# ── 华为
|
|
248
|
+
# ── 华为 (官方 API: https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) ──
|
|
192
249
|
huawei:
|
|
193
250
|
enable: false
|
|
194
251
|
auth:
|
|
195
|
-
clientId:
|
|
196
|
-
clientSecret:
|
|
197
|
-
appId:
|
|
198
|
-
releaseType: draft
|
|
199
|
-
# apiBaseUrl: '' # 可选：指定区域 API
|
|
252
|
+
clientId: "${HUAWEI_CLIENT_ID}"
|
|
253
|
+
clientSecret: "${HUAWEI_CLIENT_SECRET}"
|
|
254
|
+
appId: "YOUR_APP_ID"
|
|
255
|
+
releaseType: draft
|
|
200
256
|
|
|
201
|
-
# ── 小米 ──
|
|
257
|
+
# ── 小米 (官方 API: https://dev.mi.com/console/doc/detail?pId=1695) ──
|
|
202
258
|
xiaomi:
|
|
203
259
|
enable: false
|
|
204
260
|
auth:
|
|
205
|
-
userName:
|
|
206
|
-
privateKey:
|
|
207
|
-
|
|
208
|
-
packageName: 'com.example.app'
|
|
261
|
+
userName: "your@email.com"
|
|
262
|
+
privateKey: "${XIAOMI_KEY}"
|
|
263
|
+
packageName: "com.example.app"
|
|
209
264
|
|
|
210
|
-
# ── OPPO ──
|
|
265
|
+
# ── OPPO (官方 API: https://open.oppomobile.com/wiki/doc#id=10106) ──
|
|
211
266
|
oppo:
|
|
212
267
|
enable: false
|
|
213
268
|
auth:
|
|
214
|
-
clientId:
|
|
215
|
-
clientSecret:
|
|
269
|
+
clientId: "${OPPO_CLIENT_ID}"
|
|
270
|
+
clientSecret: "${OPPO_CLIENT_SECRET}"
|
|
216
271
|
|
|
217
|
-
# ── vivo ──
|
|
272
|
+
# ── vivo (官方 API: https://dev.vivo.com.cn/openAbility/interface) ──
|
|
218
273
|
vivo:
|
|
219
274
|
enable: false
|
|
220
275
|
auth:
|
|
221
|
-
accessKey:
|
|
222
|
-
accessSecret:
|
|
276
|
+
accessKey: "${VIVO_ACCESS_KEY}"
|
|
277
|
+
accessSecret: "${VIVO_ACCESS_SECRET}"
|
|
223
278
|
|
|
224
|
-
# ── 腾讯应用宝 ──
|
|
279
|
+
# ── 腾讯应用宝 (官方 API: https://open.qq.com/doc/?id=11016) ──
|
|
225
280
|
tencent:
|
|
226
281
|
enable: false
|
|
227
282
|
auth:
|
|
228
|
-
userId:
|
|
229
|
-
appId:
|
|
230
|
-
accessSecret:
|
|
283
|
+
userId: "${TENCENT_USER_ID}"
|
|
284
|
+
appId: "${TENCENT_APP_ID}"
|
|
285
|
+
accessSecret: "${TENCENT_SECRET}"
|
|
231
286
|
|
|
232
|
-
# ── 鸿蒙 ──
|
|
287
|
+
# ── 鸿蒙 (官方 API: https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) ──
|
|
233
288
|
harmony:
|
|
234
289
|
enable: false
|
|
235
290
|
auth:
|
|
236
|
-
clientId:
|
|
237
|
-
clientSecret:
|
|
238
|
-
appId:
|
|
291
|
+
clientId: "${HARMONY_CLIENT_ID}"
|
|
292
|
+
clientSecret: "${HARMONY_CLIENT_SECRET}"
|
|
293
|
+
appId: "YOUR_APP_ID"
|
|
239
294
|
|
|
240
|
-
# ── App Store / TestFlight
|
|
295
|
+
# ── App Store / TestFlight (官方 API: https://developer.apple.com/app-store-connect/api/) ──
|
|
241
296
|
app_store:
|
|
242
297
|
enable: false
|
|
243
|
-
mode: app_store
|
|
298
|
+
mode: app_store
|
|
244
299
|
auth:
|
|
245
|
-
appleId:
|
|
246
|
-
appPassword:
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
# apiIssuerId: ''
|
|
250
|
-
# privateKeyPath: './AuthKey.p8'
|
|
251
|
-
|
|
252
|
-
# ── Google Play（计划中）──
|
|
300
|
+
appleId: "${APPLE_ID}"
|
|
301
|
+
appPassword: "${APP_PASSWORD}"
|
|
302
|
+
|
|
303
|
+
# ── Google Play (官方 API: https://developer.android.com/studio/publish) ──
|
|
253
304
|
google_play:
|
|
254
305
|
enable: false
|
|
255
306
|
auth:
|
|
256
|
-
serviceAccountJsonPath:
|
|
257
|
-
packageName:
|
|
258
|
-
track: production
|
|
307
|
+
serviceAccountJsonPath: "./service-account.json"
|
|
308
|
+
packageName: "com.example.app"
|
|
309
|
+
track: production
|
|
259
310
|
```
|
|
260
311
|
|
|
261
|
-
###
|
|
312
|
+
### 环境变量支持
|
|
262
313
|
|
|
263
314
|
配置值支持 `${VAR_NAME}` 语法引用环境变量，避免敏感信息硬编码：
|
|
264
315
|
|
|
@@ -268,185 +319,136 @@ pgyer:
|
|
|
268
319
|
apiKey: ${PGYER_API_KEY} # 运行时自动替换
|
|
269
320
|
```
|
|
270
321
|
|
|
271
|
-
|
|
322
|
+
在 CI/CD 中设置环境变量即可：
|
|
272
323
|
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
│ ├── index.ts # 📦 库入口 — 导出所有公共 API
|
|
277
|
-
│ ├── cli.ts # 🖥️ CLI 入口 — 命令行工具主程序
|
|
278
|
-
│ ├── types.ts # 📐 类型定义 — 所有接口和类型
|
|
279
|
-
│ ├── adapters/ # 🔌 上传适配器层
|
|
280
|
-
│ │ ├── index.ts # 适配器统一导出
|
|
281
|
-
│ │ ├── pgyer_uploader.ts # 蒲公英 — API Key 认证
|
|
282
|
-
│ │ ├── huawei_uploader.ts # 华为 — OAuth2 三步上传
|
|
283
|
-
│ │ ├── xiaomi_uploader.ts # 小米 — RSA 1024 分段加密
|
|
284
|
-
│ │ ├── oppo_uploader.ts # OPPO — HMAC-SHA256 签名
|
|
285
|
-
│ │ ├── vivo_uploader.ts # vivo — HMAC-SHA256 + MD5
|
|
286
|
-
│ │ ├── tencent_uploader.ts # 腾讯应用宝 — COS 直传
|
|
287
|
-
│ │ ├── apple_store_uploader.ts # App Store — Transporter/altool
|
|
288
|
-
│ │ ├── harmony_uploader.ts # 鸿蒙 — 复用华为 AGC API
|
|
289
|
-
│ │ ├── testflight_uploader.ts # TestFlight — 半成品
|
|
290
|
-
│ │ └── adhoc_uploader.ts # Ad Hoc — 半成品
|
|
291
|
-
│ ├── utils/ # 🔧 工具层
|
|
292
|
-
│ │ ├── index.ts # 工具统一导出
|
|
293
|
-
│ │ ├── upload-manager.ts # 上传管理器 — 并发调度 + 智能分发
|
|
294
|
-
│ │ ├── retry-strategy.ts # 重试策略 — 指数退避 + 错误分类
|
|
295
|
-
│ │ ├── apple-jwt-generator.ts # Apple JWT — ES256 签名生成
|
|
296
|
-
│ │ ├── package-parser.ts # 包解析器 — APK/AAB 信息提取
|
|
297
|
-
│ │ └── logger.ts # 日志工具 — 仅内部使用，不对外导出
|
|
298
|
-
│ └── validators/ # ✅ 验证层
|
|
299
|
-
│ ├── index.ts # 验证器统一导出
|
|
300
|
-
│ ├── config_validator.ts # 配置验证 — YAML 加载 + Schema 校验
|
|
301
|
-
│ └── env_validator.ts # 环境变量验证
|
|
302
|
-
├── dist/ # 构建产物
|
|
303
|
-
├── package.json
|
|
304
|
-
├── tsconfig.json
|
|
305
|
-
└── tsup.config.ts
|
|
324
|
+
```bash
|
|
325
|
+
export PGYER_API_KEY="your-actual-key"
|
|
326
|
+
app-ship upload -c app-ship.yaml -f app.apk
|
|
306
327
|
```
|
|
307
328
|
|
|
308
|
-
|
|
329
|
+
---
|
|
309
330
|
|
|
310
|
-
|
|
311
|
-
┌─────────────────────────────────────────────────────┐
|
|
312
|
-
│ 用户界面层 │
|
|
313
|
-
├───────────┬──────────────────┬───────────────────────┤
|
|
314
|
-
│ CLI │ VSCode 插件 │ npm 库集成 │
|
|
315
|
-
│ (cli.ts) │ (另一个包) │ (index.ts) │
|
|
316
|
-
└─────┬─────┴────────┬─────────┴──────────┬────────────┘
|
|
317
|
-
│ │ │
|
|
318
|
-
▼ ▼ ▼
|
|
319
|
-
┌─────────────────────────────────────────────────────┐
|
|
320
|
-
│ 配置管理层 │
|
|
321
|
-
│ ConfigValidator — YAML 解析 + 环境变量替换 + 校验 │
|
|
322
|
-
│ EnvValidator — 环境变量存在性检查 │
|
|
323
|
-
└─────────────────────┬───────────────────────────────┘
|
|
324
|
-
│
|
|
325
|
-
▼
|
|
326
|
-
┌─────────────────────────────────────────────────────┐
|
|
327
|
-
│ 上传管理层 │
|
|
328
|
-
│ UploadManager │
|
|
329
|
-
│ ├── 适配器注册与查找 │
|
|
330
|
-
│ ├── 并发控制 (maxConcurrent) │
|
|
331
|
-
│ ├── 智能分发 (APK→Android, IPA→Apple, HAP→鸿蒙) │
|
|
332
|
-
│ └── 结果聚合 → UploadReport │
|
|
333
|
-
└─────────────────────┬───────────────────────────────┘
|
|
334
|
-
│
|
|
335
|
-
▼
|
|
336
|
-
┌─────────────────────────────────────────────────────┐
|
|
337
|
-
│ 平台适配器层 (IUploader) │
|
|
338
|
-
├────────┬────────┬────────┬────────┬────────┬────────┤
|
|
339
|
-
│ Pgyer │ Huawei │ Xiaomi │ Apple │ Harmony│ ... │
|
|
340
|
-
└────────┴────────┴────────┴────────┴────────┴────────┘
|
|
341
|
-
│
|
|
342
|
-
▼
|
|
343
|
-
┌─────────────────────────────────────────────────────┐
|
|
344
|
-
│ 基础设施层 │
|
|
345
|
-
│ RetryStrategy — 指数退避 + 错误分类 │
|
|
346
|
-
│ AppleJWTGenerator — ES256 JWT 签名 │
|
|
347
|
-
│ Logger — 彩色日志输出 │
|
|
348
|
-
└─────────────────────────────────────────────────────┘
|
|
349
|
-
```
|
|
331
|
+
## 常见问题
|
|
350
332
|
|
|
351
|
-
|
|
333
|
+
### Q: 如何获取各平台的 API Key？
|
|
352
334
|
|
|
353
|
-
|
|
335
|
+
**蒲公英**: 登录 [pgyer.com](https://www.pgyer.com) → 账号设置 → API 信息
|
|
354
336
|
|
|
355
|
-
|
|
337
|
+
**华为**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → 我的项目 → 项目设置 → 密钥管理
|
|
356
338
|
|
|
357
|
-
|
|
339
|
+
**小米**: [小米开放平台](https://dev.mi.com/console/) → 应用管理 → 应用详情 → 上传接口
|
|
358
340
|
|
|
359
|
-
|
|
341
|
+
**OPPO/vivo/腾讯**: 对应开发者平台 → 应用管理 → API 管理
|
|
360
342
|
|
|
361
|
-
|
|
362
|
-
import { IUploader, UploadResult, AppMetadata } from '../types.js'
|
|
343
|
+
**Apple**: [App Store Connect](https://appstoreconnect.apple.com) → 用户和访问权限 → API 密钥
|
|
363
344
|
|
|
364
|
-
|
|
365
|
-
name = 'my_platform'
|
|
345
|
+
---
|
|
366
346
|
|
|
367
|
-
|
|
368
|
-
validateConfig(config: any): boolean {
|
|
369
|
-
return config?.enable && config?.auth?.apiKey
|
|
370
|
-
}
|
|
347
|
+
### Q: 上传失败如何排查？
|
|
371
348
|
|
|
372
|
-
|
|
373
|
-
canHandle(filePath: string): boolean {
|
|
374
|
-
return filePath.endsWith('.apk')
|
|
375
|
-
}
|
|
349
|
+
1. 使用 `--verbose` 参数查看详细日志：
|
|
376
350
|
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
// ... 你的上传逻辑
|
|
381
|
-
return {
|
|
382
|
-
platform: this.name,
|
|
383
|
-
success: true,
|
|
384
|
-
message: '上传成功',
|
|
385
|
-
url: 'https://...',
|
|
386
|
-
}
|
|
387
|
-
} catch (error: any) {
|
|
388
|
-
return {
|
|
389
|
-
platform: this.name,
|
|
390
|
-
success: false,
|
|
391
|
-
message: error.message || '上传失败',
|
|
392
|
-
error,
|
|
393
|
-
}
|
|
394
|
-
}
|
|
395
|
-
}
|
|
396
|
-
}
|
|
397
|
-
```
|
|
351
|
+
```bash
|
|
352
|
+
app-ship upload -c app-ship.yaml -f app.apk --verbose
|
|
353
|
+
```
|
|
398
354
|
|
|
399
|
-
|
|
355
|
+
2. 检查以下几点：
|
|
356
|
+
- 网络连接正常
|
|
357
|
+
- 各平台服务状态正常
|
|
358
|
+
- API Key 和权限配置正确
|
|
359
|
+
- 应用包格式是否正确
|
|
400
360
|
|
|
401
|
-
|
|
361
|
+
3. 查看 [Issues](https://gitee.com/flu-cli/flu-cli/issues) 是否有类似问题
|
|
402
362
|
|
|
403
|
-
|
|
404
|
-
export * from './my_platform_uploader.js'
|
|
405
|
-
```
|
|
363
|
+
---
|
|
406
364
|
|
|
407
|
-
|
|
365
|
+
### Q: 支持 Windows / Mac 吗？
|
|
408
366
|
|
|
409
|
-
|
|
410
|
-
this.registerUploader('my_platform', new MyPlatformUploader())
|
|
411
|
-
```
|
|
367
|
+
支持！本工具是跨平台的，可在以下环境运行：
|
|
412
368
|
|
|
413
|
-
|
|
369
|
+
- Windows 10+
|
|
370
|
+
- macOS 10.15+
|
|
371
|
+
- Linux (Ubuntu 18+, Fedora, etc.)
|
|
414
372
|
|
|
415
|
-
|
|
373
|
+
---
|
|
416
374
|
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
375
|
+
### Q: 可以在 CI/CD 中使用吗？
|
|
376
|
+
|
|
377
|
+
当然可以！使用环境变量存储凭证：
|
|
378
|
+
|
|
379
|
+
**GitHub Actions 示例**：
|
|
380
|
+
|
|
381
|
+
```yaml
|
|
382
|
+
- name: Upload App
|
|
383
|
+
run: app-ship upload -c app-ship.yaml -f app.apk
|
|
384
|
+
env:
|
|
385
|
+
PGYER_API_KEY: ${{ secrets.PGYER_API_KEY }}
|
|
386
|
+
HUAWEI_CLIENT_ID: ${{ secrets.HUAWEI_CLIENT_ID }}
|
|
387
|
+
# ... 其他平台凭证
|
|
424
388
|
```
|
|
425
389
|
|
|
426
|
-
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## 安全与隐私
|
|
393
|
+
|
|
394
|
+
### 🔐 密钥管理
|
|
395
|
+
|
|
396
|
+
- **用户掌控**：所有凭证仅保存在本地 `app-ship.yaml`，不上传到任何服务器
|
|
397
|
+
- **本地处理**：所有认证和签名操作都在你的机器本地执行
|
|
398
|
+
- **官方渠道**：直接调用各平台官方 API，无第三方转接
|
|
399
|
+
|
|
400
|
+
### 🛡️ 最佳实践
|
|
401
|
+
|
|
402
|
+
1. **保护配置文件** - 将 `app-ship.yaml` 加入 `.gitignore`：
|
|
403
|
+
|
|
404
|
+
```bash
|
|
405
|
+
echo "app-ship.yaml" >> .gitignore
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
2. **在 CI/CD 中使用环境变量** - 不要提交凭证到版本控制
|
|
409
|
+
|
|
410
|
+
3. **定期轮换凭证** - 按各平台建议定期更新 API Key
|
|
411
|
+
|
|
412
|
+
4. **权限最小化** - 为 API Key 设置尽可能细粒度的权限
|
|
413
|
+
|
|
414
|
+
### 📜 法律声明
|
|
415
|
+
|
|
416
|
+
使用本工具时，你同意：
|
|
417
|
+
|
|
418
|
+
- 遵守各平台的服务协议和 API 使用政策
|
|
419
|
+
- 合法获取并妥善保管凭证和密钥
|
|
420
|
+
- 自行承担因不当使用造成的一切后果
|
|
427
421
|
|
|
428
|
-
|
|
422
|
+
本工具作者不对违规使用或产生的损失承担任何责任。
|
|
429
423
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
| `UploadConfig` | types.ts | YAML 配置文件的完整类型定义 |
|
|
434
|
-
| `AppMetadata` | types.ts | 上传时附带的应用元数据 |
|
|
435
|
-
| `UploadResult` | types.ts | 每个平台上传后的统一返回格式 |
|
|
436
|
-
| `BuildResult` | types.ts | 构建结果（Android/iOS 构建器使用） |
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## 开发指南
|
|
437
427
|
|
|
438
|
-
###
|
|
428
|
+
### 项目结构
|
|
439
429
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
430
|
+
```
|
|
431
|
+
packages/app-ship/
|
|
432
|
+
├── src/
|
|
433
|
+
│ ├── index.ts # 📦 库入口 — 导出所有公共 API
|
|
434
|
+
│ ├── cli.ts # 🖥️ CLI 入口 — 命令行工具主程序
|
|
435
|
+
│ ├── types.ts # 📐 类型定义 — 所有接口和类型
|
|
436
|
+
│ ├── adapters/ # 🔌 上传适配器层
|
|
437
|
+
│ │ ├── pgyer_uploader.ts
|
|
438
|
+
│ │ ├── huawei_uploader.ts
|
|
439
|
+
│ │ ├── xiaomi_uploader.ts
|
|
440
|
+
│ │ └── ...
|
|
441
|
+
│ ├── utils/ # 🔧 工具层
|
|
442
|
+
│ │ ├── upload-manager.ts # 并发调度 + 智能分发
|
|
443
|
+
│ │ ├── retry-strategy.ts # 指数退避 + 错误分类
|
|
444
|
+
│ │ └── ...
|
|
445
|
+
│ └── validators/ # ✅ 验证层
|
|
446
|
+
│ ├── config_validator.ts
|
|
447
|
+
│ └── env_validator.ts
|
|
448
|
+
├── dist/
|
|
449
|
+
├── package.json
|
|
450
|
+
└── tsconfig.json
|
|
451
|
+
```
|
|
450
452
|
|
|
451
453
|
### 本地开发
|
|
452
454
|
|
|
@@ -455,44 +457,58 @@ my_platform?: {
|
|
|
455
457
|
npm install
|
|
456
458
|
|
|
457
459
|
# 构建
|
|
458
|
-
npm run build
|
|
460
|
+
npm run build
|
|
459
461
|
|
|
460
462
|
# 开发模式（监听文件变化）
|
|
461
463
|
npm run dev
|
|
462
464
|
```
|
|
463
465
|
|
|
464
|
-
|
|
466
|
+
### 新增平台支持（3 步）
|
|
465
467
|
|
|
466
|
-
|
|
468
|
+
1. **实现 `IUploader` 接口**（在 `src/adapters/` 下）
|
|
469
|
+
2. **在 `src/adapters/index.ts` 导出**
|
|
470
|
+
3. **在 `src/utils/upload-manager.ts` 注册**
|
|
467
471
|
|
|
468
|
-
|
|
469
|
-
- **华为**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → 我的项目 → 项目设置 → 密钥管理
|
|
470
|
-
- **小米**: [小米开放平台](https://dev.mi.com/console/) → 应用管理 → 应用详情 → 上传接口
|
|
471
|
-
- **OPPO/vivo/腾讯**: 对应开发者平台 → 应用管理 → API 管理
|
|
472
|
+
详见源码注释。
|
|
472
473
|
|
|
473
|
-
|
|
474
|
+
---
|
|
474
475
|
|
|
475
|
-
|
|
476
|
+
## 目录架构
|
|
476
477
|
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
|
|
478
|
+
```
|
|
479
|
+
┌─────────────────────────────────┐
|
|
480
|
+
│ 用户界面层 │
|
|
481
|
+
├──────┬─────────────┬─────────────┤
|
|
482
|
+
│ CLI │ VSCode 插件 │ npm 库 │
|
|
483
|
+
└──┬───┴──────┬──────┴──────┬──────┘
|
|
484
|
+
│ │ │
|
|
485
|
+
▼ ▼ ▼
|
|
486
|
+
┌─────────────────────────────────┐
|
|
487
|
+
│ 配置管理 & 验证 │
|
|
488
|
+
└──────────────┬──────────────────┘
|
|
489
|
+
▼
|
|
490
|
+
┌─────────────────────────────────┐
|
|
491
|
+
│ 上传管理（并发、智能分发） │
|
|
492
|
+
└──────────────┬──────────────────┘
|
|
493
|
+
▼
|
|
494
|
+
┌─────────────────────────────────┐
|
|
495
|
+
│ 平台适配器（8+ 个平台） │
|
|
496
|
+
└──────────────┬──────────────────┘
|
|
497
|
+
▼
|
|
498
|
+
┌─────────────────────────────────┐
|
|
499
|
+
│ 基础设施（重试、JWT、日志） │
|
|
500
|
+
└─────────────────────────────────┘
|
|
480
501
|
```
|
|
481
502
|
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
1. 使用 `--verbose` 参数查看详细日志
|
|
485
|
-
2. 检查网络连接和各平台服务状态
|
|
486
|
-
3. 确认 API Key 和权限配置正确
|
|
487
|
-
4. 查看 [Issues](https://gitee.com/flu-cli/flu-cli/issues) 是否有类似问题
|
|
503
|
+
---
|
|
488
504
|
|
|
489
|
-
##
|
|
505
|
+
## 社区与支持
|
|
490
506
|
|
|
491
507
|
扫描下方二维码或搜索公众号**火叶**关注我们
|
|
492
508
|
|
|
493
|
-
|
|
|
494
|
-
|
|
|
495
|
-
| <img src="https://gitee.com/flu-cli/flu-cli/raw/
|
|
509
|
+
| 关注公众号 | 加作者微信入群 | 赞赏支持 |
|
|
510
|
+
| :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: |
|
|
511
|
+
| <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) |
|
|
496
512
|
|
|
497
513
|
> 💡 你也可以点击插件详情页顶部的 **Sponsor** 按钮来支持本项目。
|
|
498
514
|
|