Fastlane 上传应用

安装和配置蒲公英 Fastlane 插件，把 Fastlane 打包生成的 Android、iOS 和鸿蒙安装包自动上传到蒲公英。

Fastlane 是面向 iOS 与 Android 开发者的自动化构建工具，可将打包、签名、测试、发布等环节串联为完整的工作流。蒲公英官方 Fastlane 插件 fastlane-plugin-pgyer 可以在打包后把 .ipa、.apk 和鸿蒙 .hap 安装包上传到蒲公英，并返回下载页地址和二维码。

如需选择 API、CLI、CI/CD 插件、MCP 或 Agent Skill，请先查看自动上传 App 与 CI/CD 集成指南。

前置要求

macOS 或 Linux 系统。
已安装 Ruby、Bundler 和 Fastlane，可参考 Fastlane 官方安装指南。
蒲公英 API Key：可以在 API 信息页面查看。

安装插件

在项目目录执行：

fastlane add_plugin pgyer

已经安装过插件的项目，执行 fastlane update_plugins 升级到最新版本。

保存 API Key

建议把 API Key 保存在环境变量 PGYER_API_KEY 中（在 CI 中保存为 Secret），不要写进 Fastfile：

export PGYER_API_KEY=您的API Key

也可以在 lane 中通过 pgyer(api_key: "...") 传入。

配置 lane

在 fastlane/Fastfile 中，在打包指令之后加入 pgyer。插件会自动使用同一个 lane 中 gym 或 gradle 生成的安装包，也可以用 ipa、apk 或 hap 参数指定文件。

lane :beta do
  gradle(task: "assembleRelease")
  pgyer(update_description: "修复登录崩溃")
end

lane :beta do
  build_app(export_method: "ad-hoc")
  pgyer(update_description: "修复登录崩溃")
end

先用 DevEco Studio 或 hvigorw assembleHap 打包并签名，再上传 .hap 文件：

lane :beta_harmony do
  pgyer(
    hap: "entry/build/default/outputs/default/entry-default-signed.hap",
    update_description: "修复登录崩溃"
  )
end

打包并上传

在项目目录执行：

fastlane beta

上传完成后，输出类似：

Build file: ./app/build/outputs/apk/release/app-release.apk (android)
Uploading app-release.apk (35.2 MB)...
Upload finished. Waiting for PGYER to process the build...
Published PGYER Demo 1.0.0 (build 1)
Download page: https://www.pgyer.com/pgyerdemo
QR code: https://www.pgyer.com/app/qrcodeHistory/...

常用参数

参数	环境变量	说明
`api_key`	`PGYER_API_KEY`	必填，蒲公英 API Key
`apk`、`ipa`、`hap`	`PGYER_APK`、`PGYER_IPA`、`PGYER_HAP`	要上传的安装包，最多设置一个。不设置时使用同一个 lane 中 `gym` 或 `gradle` 生成的安装包
`update_description`	`PGYER_UPDATE_DESCRIPTION`	本次版本的更新说明
`description`	`PGYER_DESCRIPTION`	应用描述
`install_type`	`PGYER_INSTALL_TYPE`	安装方式：`1` 公开，`2` 密码，`3` 邀请。不设置时沿用上一个版本的设置；只设置 `password` 时为密码安装
`password`	`PGYER_PASSWORD`	安装密码
`install_start_date`、`install_end_date`	`PGYER_INSTALL_START_DATE`、`PGYER_INSTALL_END_DATE`	安装有效期，例如 `2026-01-01`，需要同时设置
`channel`	`PGYER_SPECIFIED_CHANNEL`	要更新的渠道短链接
`user_download_file_name`	`PGYER_USER_DOWNLOAD_FILE_NAME`	下载时的文件名，仅支持英文字母、数字和常用符号，默认使用上传文件的文件名
`oversea`	`PGYER_OVERSEA`	`true` 使用海外加速上传，`false` 使用国内上传；不设置时按 IP 自动判断
`processing_timeout`	`PGYER_PROCESSING_TIMEOUT`	上传后等待蒲公英处理完成的秒数，默认 `600`

执行 fastlane action pgyer 可以查看全部参数，也可以参考插件说明。

使用上传结果

pgyer 返回蒲公英的版本信息，其中 appPgyerURL 是下载页地址，appQRCodeURL 是二维码图片地址。同样的值也保存在 lane_context 的 PGYER_DOWNLOAD_URL 和 PGYER_QRCODE_URL 中，可以在后续步骤中使用，例如发送通知：

lane :beta do
  build_app(export_method: "ad-hoc")
  result = pgyer(update_description: "修复登录崩溃")
  slack(message: "新的测试版本：#{result['appPgyerURL']}")
end

从旧版本升级

0.5.0 起插件有以下变化：

不设置 install_type 时沿用上一个版本的安装方式。旧版本每次上传都会改为公开安装；如需公开安装，请设置 install_type: "1"。
设置了 apk、ipa 或 hap 时，优先上传该文件，安装包类型按文件扩展名判断。
等待蒲公英处理最多 processing_timeout 秒，不再无限等待。

错误排查

现象	处理方法
`Error loading plugin 'fastlane-plugin-pgyer'` 或 `Unable to activate faraday_middleware`	0.3.x 版本无法在 Fastlane 2.238.0 及以上版本加载，执行 `fastlane update_plugins` 升级插件
API Key 错误、未完成实名认证、存储空间已满等 API 错误	日志会显示蒲公英的错误码和处理建议，按提示处理
`PGYER is still processing the build after 600 seconds`	上传已经完成，版本稍后可能仍会出现在应用列表中；安装包较大时可以调大 `processing_timeout`
`None of the PGYER API servers could be reached`	插件会依次尝试 `www.pgyer.com`、`www.xcxwo.com` 和 `www.pgyerapp.com`。请检查网络和代理（支持 `HTTPS_PROXY`）；DNS 被拦截时可以设置 `doh: true`
上传了错误的安装包	用 `apk`、`ipa` 或 `hap` 参数明确指定文件

Fastlane 上传应用

本页目录