部署

部署移动应用是一个复杂的过程——而且每个平台都不同！

有更简单的方法

管理证书、配置文件、密钥库以及协调团队间的部署可能既令人沮丧又耗时。

Bifrost 为你处理所有这些复杂性。

每个应用只需设置一次凭据 - 无需在本地管理证书和配置文件
团队协作 - 轻松与团队共享应用并管理访问权限
自动部署 - 无需手动构建即可自动推送更新
空中更新 - 无需应用商店审批即可即时向用户部署更改
低月费 - 简单、实惠的定价

一般来说，你需要：

发布：为每个平台创建_发布构建_。
测试：在真实设备上测试此构建。
打包：签名并将此构建分发到商店。
提交审核：通过每个商店的提交流程来审核你的应用。
发布：将新版本发布到商店和你的用户。

在商店中创建全新应用时，最初会更耗时，因为你需要在每个商店设置列表并创建签名凭据。

如果你以前从未做过，请留出几个小时的时间，以便专注于正确处理事情并了解你需要的一切。

不要匆忙完成应用商店流程！有些合规项目如果处理不当，要么会阻止你发布应用，要么无法在你想要发布的地区发布，或者在提交审核时立即被拒绝。

一旦你发布了应用的第一个版本，通常会更容易，在完成 2 或 3 个应用后，你会很快完成这个过程！

需要帮助？

本页面旨在帮助你_配置和使用 NativePHP_ 来准备发布应用；它不是关于商店的指南。你应该查阅 App Store Connect 帮助和 Play Console 帮助文档，以获取有关如何准备应用提交和列表的详细和最新指导。

如果你需要更多实际支持，我们很乐意与我们的合作伙伴合作，支持他们发布应用。

发布

要准备发布应用，你应该将版本号设置为以前未使用过的新版本号，并增加构建编号：

dotenv

NATIVEPHP_APP_VERSION=1.2.3
NATIVEPHP_APP_VERSION_CODE=48

版本控制

你可以完全自由地决定如何为应用程序设置版本。你可以使用语义版本控制、代号、基于日期的版本或任何适合你的项目、团队或业务的方案。

请记住，你的应用版本通常是面向公众的（例如在商店列表和设备上的设置和更新屏幕中），如果客户需要联系你寻求帮助和支持，它们可以作为有用的参考。

版本号通过 .env 中的 NATIVEPHP_APP_VERSION 键管理。

构建编号

Google Play Store 和 Apple App Store 都要求你的应用的构建编号在每次提交发布时递增。

构建编号通过 .env 中的 NATIVEPHP_APP_VERSION_CODE 键管理。

运行 `release` 构建

然后运行发布构建：

shell

php artisan native:run --build=release

这将使用各种优化来构建你的应用程序，减少其整体大小并提高性能，例如删除调试代码和不必要的功能（即 Composer 开发依赖项）。

你应该在真实设备上测试此构建。 一旦你确认一切按预期工作，你就可以将其提交到商店进行审批和分发。

打包应用

native:package 命令创建已签名、可用于生产的应用，以分发到 App Store 和 Play Store。此命令处理代码签名、构建发布产物和准备提交文件的所有复杂性。

开始之前

在打包应用进行分发之前，请确保：

你的应用在两个平台上都已完全开发和测试
你在 nativephp.php 配置中配置了有效的 bundle ID 和 app ID
对于 Android：你有一个带有有效密钥别名的签名密钥库
对于 iOS：你有来自 Apple Developer 的必要签名证书和配置文件
所有配置都已完成（参见配置指南）

Android 打包

创建 Android 签名凭据

NativePHP 提供了一个便捷的命令来生成 Android 所需的所有签名凭据：

bash

php artisan native:credentials android

此命令将：

生成新的 JKS 密钥库文件
创建所有必要的签名密钥
自动将凭据添加到你的 .env 文件
将密钥库添加到 .gitignore 以保持安全

凭据将保存在 nativephp/credentials/android/ 目录中，并自动配置以供 package 命令使用。

必需的签名凭据

要构建已签名的 Android 应用，你需要四条信息：

凭据	选项	环境变量	描述
密钥库文件	`--keystore`	`ANDROID_KEYSTORE_FILE`	`.keystore` 文件的路径
密钥库密码	`--keystore-password`	`ANDROID_KEYSTORE_PASSWORD`	密钥库的密码
密钥别名	`--key-alias`	`ANDROID_KEY_ALIAS`	密钥库中密钥的名称
密钥密码	`--key-password`	`ANDROID_KEY_PASSWORD`	特定密钥的密码

构建发布 APK

APK（Android Package）是一个单一的二进制文件，适合直接分发或在特定设备上测试：

bash

php artisan native:package android \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword

构建过程准备你的 Android 项目，编译代码，并使用你的证书签名 APK。完成后，输出目录会自动打开，显示你签名的 app-release.apk 文件。

构建 Android App Bundle (AAB)

AAB（Android App Bundle）是通过 Play Store 分发所必需的。它是一种优化格式，Play Store 使用它自动生成特定于设备的 APK：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword

这将创建一个已签名的 app-release.aab 文件，准备提交到 Play Store。

使用环境变量

你可以将凭据存储在 .env 文件中，而不是作为命令选项传递：

env

ANDROID_KEYSTORE_FILE=/path/to/my-app.keystore
ANDROID_KEYSTORE_PASSWORD=mykeystorepassword
ANDROID_KEY_ALIAS=my-app-key
ANDROID_KEY_PASSWORD=mykeypassword

然后只需运行：

bash

php artisan native:package android --build-type=bundle

上传到 Play Store

如果你有一个具有 Play Console 访问权限的 Google 服务账号，你可以直接从命令上传：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --upload-to-play-store \
  --play-store-track=internal \
  --google-service-key=/path/to/service-account-key.json

--play-store-track 选项控制构建发布的位置：

internal - 内部测试（默认，最快审核）
alpha - 封闭 Alpha 测试
beta - 封闭 Beta 测试
production - 生产发布

测试 Play Store 上传

如果你已经有一个 AAB 文件并想在不重新构建的情况下测试上传，使用 --test-push：

bash

php artisan native:package android \
  --test-push=/path/to/app-release.aab \
  --upload-to-play-store \
  --play-store-track=internal \
  --google-service-key=/path/to/service-account-key.json

这将跳过整个构建过程，只处理上传。

跳过构建准备

对于未更改原生代码的增量构建，你可以跳过准备阶段：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --skip-prepare

iOS 打包

必需的签名凭据

iOS 应用需要来自 Apple Developer 的多个凭据：

凭据	选项	环境变量	描述
API 密钥文件	`--api-key-path`	`APP_STORE_API_KEY_PATH`	来自 App Store Connect 的 `.p8` 文件路径
API 密钥 ID	`--api-key-id`	`APP_STORE_API_KEY_ID`	来自 App Store Connect 的密钥 ID
API 发行者 ID	`--api-issuer-id`	`APP_STORE_API_ISSUER_ID`	来自 App Store Connect 的发行者 ID
证书	`--certificate-path`	`IOS_DISTRIBUTION_CERTIFICATE_PATH`	分发证书（`.p12` 或 `.cer`）
证书密码	`--certificate-password`	`IOS_DISTRIBUTION_CERTIFICATE_PASSWORD`	证书的密码
配置文件	`--provisioning-profile-path`	`IOS_DISTRIBUTION_PROVISIONING_PROFILE_PATH`	配置文件（`.mobileprovision`）
团队 ID	`--team-id`	`IOS_TEAM_ID`	Apple 开发者团队 ID

设置 App Store Connect API

要从命令行直接上传到 App Store，你需要一个 API 密钥：

登录 App Store Connect
导航到 Users & Access → Keys
点击"+"按钮创建一个具有"Developer"访问权限的新密钥
立即下载 .p8 文件（之后无法再次下载）
记下页面上显示的密钥 ID 和发行者 ID

导出方法

--export-method 选项控制应用的打包方式：

app-store - 用于 App Store 分发（默认）
ad-hoc - 用于分发到特定的注册设备
enterprise - 用于企业分发（需要企业计划）
development - 用于开发和测试

为 App Store 构建

构建准备提交到 App Store 的生产应用：

bash

php artisan native:package ios \
  --export-method=app-store \
  --api-key-path=/path/to/api-key.p8 \
  --api-key-id=ABC123DEF \
  --api-issuer-id=01234567-89ab-cdef-0123-456789abcdef \
  --certificate-path=/path/to/distribution.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/profile.mobileprovision \
  --team-id=ABC1234567

为 Ad-Hoc 分发构建

用于分发到特定设备而不通过 App Store：

bash

php artisan native:package ios \
  --export-method=ad-hoc \
  --certificate-path=/path/to/distribution.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/ad-hoc-profile.mobileprovision

为开发构建

用于在自己的设备上测试：

bash

php artisan native:package ios \
  --export-method=development \
  --certificate-path=/path/to/development.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/development-profile.mobileprovision

使用环境变量

将你的 iOS 凭据存储在 .env 中：

env

APP_STORE_API_KEY_PATH=/path/to/api-key.p8
APP_STORE_API_KEY_ID=ABC123DEF
APP_STORE_API_ISSUER_ID=01234567-89ab-cdef-0123-456789abcdef
IOS_DISTRIBUTION_CERTIFICATE_PATH=/path/to/distribution.p12
IOS_DISTRIBUTION_CERTIFICATE_PASSWORD=certificatepassword
IOS_DISTRIBUTION_PROVISIONING_PROFILE_PATH=/path/to/profile.mobileprovision
IOS_TEAM_ID=ABC1234567

然后构建：

bash

php artisan native:package ios --export-method=app-store

上传到 App Store Connect

构建后自动上传：

bash

php artisan native:package ios \
  --export-method=app-store \
  --api-key-path=/path/to/api-key.p8 \
  --api-key-id=ABC123DEF \
  --api-issuer-id=01234567-89ab-cdef-0123-456789abcdef \
  --certificate-path=/path/to/distribution.p12 \
  --certificate-password=certificatepassword \
  --provisioning-profile-path=/path/to/profile.mobileprovision \
  --team-id=ABC1234567 \
  --upload-to-app-store

上传使用 App Store Connect API，因此只有在使用 --upload-to-app-store 时才需要 API 凭据。

验证配置文件

在构建之前，你可以验证配置文件以检查推送通知支持和授权：

bash

php artisan native:package ios \
  --validate-profile \
  --provisioning-profile-path=/path/to/profile.mobileprovision

这将提取并显示：

配置文件名称
配置文件中配置的所有授权
推送通知支持状态
关联域
APS 环境匹配

测试 App Store 上传

测试上传现有 IPA 而不重新构建：

bash

php artisan native:package ios \
  --test-upload \
  --api-key-path=/path/to/api-key.p8 \
  --api-key-id=ABC123DEF \
  --api-issuer-id=01234567-89ab-cdef-0123-456789abcdef

清除 Xcode 缓存

如果遇到构建问题，清除 Xcode 和 Swift Package Manager 缓存：

bash

php artisan native:package ios \
  --export-method=app-store \
  --clean-caches

强制完全重建

强制完全重建并创建新归档：

bash

php artisan native:package ios \
  --export-method=app-store \
  --rebuild

仅验证不导出

验证归档而不创建 IPA：

bash

php artisan native:package ios \
  --validate-only

版本管理

构建编号和版本代码

native:version 命令处理版本管理。当使用有效的 Google 服务凭据为 Play Store 构建 AAB 时，NativePHP 会自动检查 Play Store 的最新构建编号并递增它。

从 Play Store 自动递增

使用 Play Store 访问权限构建 bundle 时：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --google-service-key=/path/to/service-account-key.json

该命令会自动查询 Play Store 以找到你最新发布的构建编号并递增它。

版本号跳跃

如果你需要跳过版本号或向前跳跃：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --jump-by=10

这将在通常使用的版本代码上加 10。

提示和故障排除

常见 Android 问题

密钥库相关错误：

验证密钥库文件是否存在以及路径是否正确
检查密钥库密码是否正确
使用以下命令确认密钥库中是否存在密钥别名：keytool -list -v -keystore /path/to/keystore
验证密钥密码是否匹配

构建失败：

确保你已安装最新的 Android SDK 和构建工具
检查 nativephp/android 目录是否存在并已正确初始化
如果你修改了原生代码，不要使用 --skip-prepare

Play Store 上传失败：

验证 Google 服务账号是否有权访问 Play Console 中的应用
确保服务账号密钥文件有效且可读
检查你的 bundle ID 是否与 Play Console 应用 ID 匹配

自定义输出目录

默认情况下，构建输出会在系统的文件管理器中打开。要将产物复制到自定义位置：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --output=/path/to/custom/directory

在非交互式环境中构建

对于 CI/CD 管道或自动构建，禁用 TTY 模式：

bash

php artisan native:package android \
  --build-type=bundle \
  --keystore=/path/to/my-app.keystore \
  --keystore-password=mykeystorepassword \
  --key-alias=my-app-key \
  --key-password=mykeypassword \
  --no-tty

产物位置

完成后，签名产物位于：

Android：

APK（release）：nativephp/android/app/build/outputs/apk/release/app-release.apk
AAB（bundle）：nativephp/android/app/build/outputs/bundle/release/app-release.aab

iOS：

IPA：在 Xcode 的构建输出目录中生成

部署 ​

发布 ​

版本控制 ​

构建编号 ​

运行 release 构建 ​

打包应用 ​

开始之前 ​

Android 打包 ​

创建 Android 签名凭据 ​

必需的签名凭据 ​

构建发布 APK ​

构建 Android App Bundle (AAB) ​

使用环境变量 ​

上传到 Play Store ​

测试 Play Store 上传 ​

跳过构建准备 ​

iOS 打包 ​

必需的签名凭据 ​

设置 App Store Connect API ​

导出方法 ​

为 App Store 构建 ​

为 Ad-Hoc 分发构建 ​

为开发构建 ​

使用环境变量 ​

上传到 App Store Connect ​

验证配置文件 ​

测试 App Store 上传 ​

清除 Xcode 缓存 ​

强制完全重建 ​

仅验证不导出 ​

版本管理 ​

构建编号和版本代码 ​

从 Play Store 自动递增 ​

版本号跳跃 ​

提示和故障排除 ​

常见 Android 问题 ​

自定义输出目录 ​

在非交互式环境中构建 ​

产物位置 ​

部署

发布

版本控制

构建编号

运行 `release` 构建

打包应用

开始之前

Android 打包

创建 Android 签名凭据

必需的签名凭据

构建发布 APK

构建 Android App Bundle (AAB)

使用环境变量

上传到 Play Store

测试 Play Store 上传

跳过构建准备

iOS 打包

必需的签名凭据

设置 App Store Connect API

导出方法

为 App Store 构建

为 Ad-Hoc 分发构建

为开发构建

使用环境变量

上传到 App Store Connect

验证配置文件

测试 App Store 上传

清除 Xcode 缓存

强制完全重建

仅验证不导出

版本管理

构建编号和版本代码

从 Play Store 自动递增

版本号跳跃

提示和故障排除

常见 Android 问题

自定义输出目录

在非交互式环境中构建

产物位置