常见问题 (FAQ)
构建与发布相关
配置相关
Q: flu_release.yaml 放在哪里？
放在 Flutter 项目的 根目录（与 pubspec.yaml 同级）：
your-flutter-project/
├── lib/
├── pubspec.yaml
└── flu_release.yaml ← 这里Q: 如何创建初始配置文件？
运行以下命令生成模板配置：
bash
app-ship init或参考 配置参考 手动创建。
Q: 环境变量 ${VAR_NAME} 没有被替换？
请检查：
- 环境变量是否已正确设置：
echo $VAR_NAME - 变量名是否拼写一致（区分大小写）
- 如果在 VSCode 中运行，可能需要重启 VSCode 使新的环境变量生效
- 配置文件中的语法是否正确：
'${VAR_NAME}'（带单引号）
Q: 可以同时启用多个平台吗？
可以。app-ship 使用 并行上传 机制（Promise.allSettled），多个平台同时上传，互不影响。某个平台失败不会中断其他平台的上传。
yaml
publish:
pgyer:
enable: true # ✅ 同时启用
# ...
huawei:
enable: true # ✅ 同时启用
# ...
xiaomi:
enable: false # ❌ 禁用
# ...构建相关
Q: 如何只构建不上传？
在 VSCode 发布中心选择「仅构建」模式即可。
Q: 如何只上传不构建？
bash
app-ship upload -f ./path/to/app.apk或在 VSCode 发布中心选择「仅上传」模式，手动添加安装包文件。
Q: 构建失败怎么办？
请检查：
- Flutter 环境是否正常：
flutter doctor - 项目是否可以正常构建：
flutter build apk - 如果使用了
flavor，确保 flavor 名称正确 - iOS 构建需要 macOS + Xcode 环境
上传相关
Q: 上传超时怎么办？
app-ship 内置了 指数退避重试 机制，默认最多重试 3 次。如果仍然超时：
检查网络连接
增加重试次数和等待时间：
yamlretry: maxRetries: 5 # 增加到 5 次 initialDelayMs: 2000 # 首次等待 2s maxDelayMs: 60000 # 最大等待 60s部分平台对大文件上传有限制，考虑使用
flutter build apk --split-per-abi减小包体积
Q: 多个平台上传，部分成功部分失败？
这是正常情况。app-ship 使用 Promise.allSettled 并行上传，每个平台独立执行，互不影响。
- 成功的平台会正常显示下载链接
- 失败的平台会显示具体错误原因
- 你可以修复失败平台的配置后重新运行（使用
-f指定文件避免重复构建）
Q: 提示 "认证失败" / "permission denied"？
请逐一检查：
- 凭证是否正确：复制凭证时是否有多余空格或换行
- 凭证是否过期：部分平台的 Token 有有效期限制
- 权限是否足够：例如华为需要「Publishing API」权限
- 环境变量是否生效：确认运行时环境中有对应的环境变量
Q: 上传到蒲公英后二维码无法打开？
可能原因：
- 蒲公英免费版有下载次数限制
- 应用设置了密码保护
- 蒲公英账号额度已用完
VSCode 发布中心相关
Q: 在 VSCode 中找不到 "Publish Center" 命令？
请确认：
- 已安装 Flu CLI VSCode 扩展
- 扩展版本为最新版
- 当前打开的工作区是一个 Flutter 项目
Q: VSCode 中输入的密钥会被保存吗？
在 VSCode 发布中心的配置面板中输入的密钥 仅在当前会话中有效，关闭后不会保存到本地。如需持久化，请写入 flu_release.yaml（建议使用环境变量引用）。
平台特定坑点 (Gotchas)
app-ship 已经在底层处理了大部分平台的"坑"，但了解它们有助于你更好地排查问题：
华为 AppGallery
- 字段名拼写错误：华为部分接口返回的字段名有拼写错误（如
fileDestUlr少了字母），app-ship 已做 fallback 处理。 - Token 字段不统一：认证响应可能返回
access_token或token，系统会自动检查两者。 - 状态限制：如果应用状态不允许操作（如正在审核中），接口可能返回 404，此时需登录后台手动操作。
小米应用商店
- RSA 加密限制：小米使用 1024-bit RSA 加密，单次加密上限为 117 字节。对于长文本，app-ship 会自动进行分段加密。
- 公钥格式：支持 X.509 PEM、DER (.cer) 和原始 Base64 格式的公钥。
- 不可撤回：小米 API 没有"草稿"状态，上传成功后即进入提审流程。
OPPO 开放平台
- CDN 域名替换：上传返回的 CDN 域名（如
storedl1）在提交时需要替换为正式域名（storedl），系统已自动处理。 - 参数格式严苛：
apk_url必须是包含 URL、MD5 和 CPU 架构代码的 JSON 数组格式。
vivo 开发者平台
- 混合请求类型：上传 APK 使用
multipart/form-data，但提交版本信息使用application/x-www-form-urlencoded。 - 签名计算：签名仅针对普通参数计算，不包含文件内容。
腾讯应用宝
- 30MB 网关限制：应用宝 API 网关有 30MB 限制。对于超过 30MB 的包，app-ship 会自动切换到 COS 直传模式。
- 架构判定：系统会自动判定 32 位和 64 位架构，并填充对应的
apk64_file或apk32_file字段。
Apple App Store
- 工具优先级：系统优先使用 Transporter 命令行工具，如果未安装则回退到
altool。 - 环境变量：在 macOS 上，
altool可能需要通过bash -l -c启动以正确加载 Xcode 路径。
其他
Q: flu_release.yaml 应该提交到 Git 吗？
视情况而定：
- 如果配置中 所有敏感信息都使用环境变量引用，可以安全提交
- 如果包含 明文密钥，绝对不要 提交
推荐做法：
yaml
# flu_release.yaml — 使用环境变量，可安全提交
publish:
pgyer:
enable: true
apiKey: '${PGYER_API_KEY}'Q: 支持 Google Play 吗？
Google Play 支持目前在开发规划中，尚未实现。关注项目更新获取最新进展。
Q: 支持 CI/CD 集成吗？
支持。app-ship 是命令行工具，可以在任何 CI/CD 环境中运行：
bash
# CI/CD 示例
npm install -g @huoye/app-ship
app-ship upload -f ./app-release.apk --changelog "CI Build #${BUILD_NUMBER}"确保在 CI 环境中设置好所有需要的环境变量即可。