您已经完成了应用程序。它在浏览器中运行得很好，UI感觉良好，核心流程稳定。然后部署出现了，转变了一个简单的Ionic项目为三个不同的发布轨道，每个轨道都有自己的工具、签名规则、审查流程和更新策略。
这就是人们经常浪费时间的地方。不是在编写功能，而是在缝合native构建、web托管、发布自动化和发布后修复的过程，人们可以重复这个过程而不必猜测。 Ionic 应用程序部署 当您停止将 iOS、Android 和 PWA 交付视为单独的项目，而是将它们视为一个具有不同输出的发布系统时，Ionic 应用程序部署才会发挥最佳作用。
目录
- 您的 Ionic 应用程序已完成，现在该怎么办?
- 为生产做好准备
- 原生部署 iOS 和 Android
- 在 Ionic 应用程序中部署 PWA
- 使用 CI/CD pipeline 自动构建
- 使用 Capgo 立即推送更新
- 常见的部署问题和最佳实践
您的Ionic应用已构建，接下来要做什么
大多数开发人员都会遇到同样的问题。 ionic serve 它看起来很棒，API 本地调用正常，应用感觉完成了。但是，它并没有完成。它只是浏览器测试过，未签名，且与App Store审查、Play签名和生产Web托管的约束隔离。
生产部署会改变您问的问题。您不再问应用是否渲染，而是问 是否可以重现打包是否同步了原生项目
是否将环境变量分离得干净
以及您是否可以在发布后修复非原生bug而不导致商店重新提交混乱。
- 这种转变很重要，因为Ionic位于混合车道上。您的应用有一个Web层，但原生壳仍然决定如何安装、签名、审查和更新应用。那些把部署作为一个后thought的团队通常会遇到配置漂移、陈旧的原生项目和脆弱的手动发布步骤。那些做得好的团队定义了一个通用的发布路径，并且使每个平台特定的步骤明确。 所以 Capacitor 配置、应用标识符、图标、环境变量和生产构建保持一致。
- 创建原生发布文件 使用平台工具而不是仅仅使用 Ionic 命令来为 Android 和 iOS 创建发布文件。
- 为需要立即在浏览器中访问的用户提供 PWA 构建。 自动化日常任务
- 以免构建依赖于开发人员记住清单。 计划发布后更新
- 以免 web 资产修复等待应用商店审查时它们不需要等待。 如果您的当前应用仍然感觉像“一个在手机壳中打开的网页应用”，那么先修复这个问题。转换指南是这个过程中的一个有用的参考，指向了使用 __CAPGO_KEEP_0__ 将网页应用转换为移动应用的指南。
您的第一个成功的商店提交通常来自于 discipline，而不是聪明才智。 Capacitor.
__CAPGO_KEEP_0__
准备您的项目
在生成任何构建之前，应将项目视为发布候选版本。最常见的部署问题来自于本地开发中无关紧要的小问题，在生产环境中却会产生重大后果。
从环境检查开始
首先运行基本检查：
ionic doctor
npm ci
npx cap doctorionic doctor 可以捕捉到常见CLI和环境问题。 npm ci 比 npm install 更适合发布工作，因为它从锁文件中安装，准确地与提交的内容一致。 npx cap doctor 可以帮助在Xcode或Android Studio中出现的插件和平台不匹配问题变得更容易识别。
尽可能使用清洁状态的发布构建。 如果应用程序只有在本地修复、删除文件夹或手动编辑本机文件后才能编译，那么您的部署过程还没有稳定。
每次都值得做的几个检查：
- 验证应用程序ID. Changing
appId. 可能会导致存储和签名混淆。 - 确认插件状态. 本地插件更改通常需要重新同步，偶尔需要重新打开平台。
- 查看环境注入. API 的端点、密钥和特性标志应来自环境特定的配置，而不是内联常量。
了解 __CAPGO_KEEP_0__ 应用程序在开发和生产环境之间的差异的深入分析 development vs production differences in Capacitor apps 锁定 __CAPGO_KEEP_0__ 配置
Lock down Capacitor config
并像生产基础设施一样审查它，而不是应用程序元数据。 capacitor.config.ts Open
A典型的文件看起来像这样:
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'My App',
webDir: 'www',
bundledWebRuntime: false,
};
export default config;立即关注的三个字段是:
| 设置 | 为什么它很重要 | 常见的错误 |
|---|---|---|
| appId | 用于商店和签名的原生包标识符 | 从一个启动项目中遗留一个占位符 |
| appName | 原生外壳中的用户可见应用名称 | 使用开发标签并忘记更改它 |
| webDir | 目录Capacitor复制到本机项目中 | 将输出文件夹设置为Capacitor所期望的位置 |
如果您在开发期间使用本地开发服务器，请确保生产配置不指向本机构建。这种错误会导致大量“在开发中工作，发布时显示空白屏幕”的事件。
实践规则： 如果发布构建依赖于一个活跃的本地服务器设置，那么它就不是一个发布构建。
生成资产一次
不要手动调整图标和启动屏幕大小。使用一个高质量的源资产，并从中生成各个平台的输出。
在当前Capacitor工作流程中，许多团队通过CLI生态系统使用官方资产工具。具体的包可能会根据栈版本而不同，但原则是一样的：在版本控制下保留一个标准图标和一个标准启动屏幕源文件，生成输出，然后在Xcode和Android Studio中查看结果并提交。
这可以避免一个熟悉的故障模式：PWA图标是最新的，但Android仍然使用一个旧的前景资产，iOS则显示一个过时的启动图像，因为一个文件夹从未被刷新。
一个稳定的生产流程还包括：
- 在生产模式下构建Web资产。
- 同步本机项目。
- 打开每个本机IDE并手动检查应用名称、图标、权限和签名设置。
- 在打包任何应用之前，测试在物理设备上。
iOS 和 Android 的本机部署
本机部署是 Ionic 应用从“仅 web”转变为遵守平台规则的地方。Web 包可能会共享，但一旦签名、打包和商店要求进入流程，Android 和 iOS 就会迅速分叉。
先构建 web 层
始终在处理本机打包之前生成最新的 web 资产：
ionic build
npx cap sync一些团队仍然说 ionic build --prod 出于习惯。现代项目中，生产行为的确切依赖于您的框架工具，但原则保持不变：生成优化的发布构建，然后将其同步到本机平台。
同步后，直接打开本机项目：
npx cap open android
npx cap open ios此时也是检查 Android 配置Capacitor应用 如果您的项目仍然有不稳定的本机配置。
Android发布工作流程
Android的发布路径通常比iOS更可预测，但当签名设置不当时，它仍会出现问题。
生成一个上传密钥库，并安全地存储它：
keytool -genkeypair -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload将密钥库文件、别名和密码存储在安全的机密存储中。不要将它们提交。不要将它们留在团队聊天中。不要假设有人已经保存了它们。
然后将签名配置到Gradle中。团队要么在文件中配置此设置，要么使用Android Studio的签名UI，具体取决于他们想要脚本化多少部分过程。典型的设置包括一个块和一个指向它的发布构建类型。 build.gradle 您通常要为Play Store提交的Android发布artifact使用的不是调试APK，而是 signingConfigs AAB
。在Android Studio中，使用菜单路径生成签名包，选择发布变体，并导出应用包。如果您更喜欢命令行构建，Gradle也可以处理签名配置后的事务。 常见的Android陷阱以熟悉的方式出现：Android发布工作流程
Android的发布路径通常比iOS更可预测，但当签名设置不当时，它仍会出现问题。
- 错误的keystore密码 会产生看起来比实际更为戏剧性的签名失败。
- 调试签名残留 会创建可以在本地安装但不适合发布到商店的构建。
- 插件失同步 发生在某人改变了一个本机插件依赖并跳过
npx cap sync. - 如果Play Console应用程序入口创建了一个不同的标识符，会导致问题。 一个有效的模式是：提交web __CAPGO_KEEP_0__, 构建web层，同步本机，根据本机项目构建发布包，存档生成的包旁边的exact commit hash。
A pattern that works well is this: commit web code, build the web layer, sync native, build release artifact from the native project, and archive the exact commit hash alongside the generated bundle.
iOS更为严格，部署问题主要来自签名身份混淆而不是__CAPGO_KEEP_0__问题。
iOS is stricter, and most deployment trouble comes from signing identity confusion rather than code problems.
iOS发布流程 签名 & 能力. 确保选择的团队正确，应用程序标识符与您打算发布的应用程序记录匹配，并且自动签名要么正常工作，要么故意用手动配置替换。
您通常会处理这些移动部分：
| 项目 | 它做什么 | 人们会在哪里栽跟头 |
|---|---|---|
| 应用程序标识符 | 将应用程序与 App Store 记录和配置绑定 | 它与 Apple 期望的不符 |
| 证书 | 识别签名者 | 安装的证书或已过期 |
| 配置文件 | 授权特定应用程序和上下文的构建 | 配置文件与应用程序 ID 或团队不匹配 |
对于本地发布工作，使用 Xcode 构建应用程序，选择物理设备或通用 iOS 设备目标，然后选择 存档. 构建存档完成后，请使用组织器窗口验证并将其分发到 App Store Connect。
如果 Xcode 说签名是破坏的，请在更改任何内容之前阅读准确的包 ID、团队和配置文件名称。随机重新生成证书往往会使问题更糟。
如果您没有 Mac，您仍然需要 macOS 环境来产生真正的 iOS 发布 artifact。实际上，团队通过使用本地 Mac、租用的云 Mac 或运行 macOS 构建的移动 CI/CD 服务来解决这个问题。
本教程是您第一次存档和提交之前的有用入门教程:
还有一个难得的教训：如果您可以避免的话，请不要随意编辑生成的本机文件。将可重复的配置放在正确的项目设置、插件配置或构建脚本中。没有人文档的手动编辑是为什么一次发布成功，下一次发布失败的原因。
部署 Ionic 应用程序作为 PWA
PWA 路径为您的 Ionic 应用程序提供了最快的路线到用户。没有商店审查。没有签名仪式。没有安装摩擦对于只需要从浏览器立即访问的人们。
即使原生应用仍然是主要渠道，这种速度也很有用。许多团队将PWA作为内部工具、预登录体验、管理员面板或市场的并行分发平台，避免了安装商店时的不必要阻力。
为 web 设计
您的 PWA 从生产 web 构建开始：
ionic build重要的是不是命令本身，而是确保输出是优化的，指向生产服务，并包含您打算交付的最终资产和清单。
在部署之前检查这些文件：
index.html应指向正确的编译资产。manifest.webmanifest应包含您想要的生产名称、图标和显示设置。- 服务工作人员文件 应仅存在于您打算使用离线缓存的情况下。
- 环境输出 应指向实时端点，而不是本地或测试服务。
谨慎启用离线行为
如果您的Ionic堆栈使用Angular，Angular服务工作者是实现离线支持和缓存的常用路径。它很强大，但也容易配置错误。
过度缓存会导致用户卡在过时的数据上，缓存太少时，应用程序在连接不稳定时不会感到坚韧。正确的设置取决于应用程序。一个面向营销的外壳可以缓存大量数据，而一个包含快速变化的操作数据的仪表板则需要更为保守的策略。
将离线支持视为产品决策，而不是简单的选项。某些屏幕应该缓存，而某些屏幕应该始终获取最新的数据。
测试真实场景，而不是仅仅依赖Lighthouse-style的假设。打开应用程序一次，断开设备，重新启动它，然后检查仍然有效的内容。然后重新连接并确认服务工作者更新而不会将用户困在陈旧的UI上。
根据工作流程选择托管
对于Ionic PWA，静态托管平台通常足够。团队通常会选择Netlify、Vercel和Firebase Hosting等选项。
这是实用的权衡视图：
| 平台 | 最佳匹配 | 注意 |
|---|---|---|
| Netlify | 简单静态部署和预览 | 需要明确的审查行为 |
| Vercel | 使用基于 Git 的工作流程的前端团队 | 某些应用程序路由设置需要调整 |
| Firebase Hosting | 使用 Firebase 服务的团队 | 如果 Firebase 做得太多，项目结构会变得混乱 |
在任何一个中，直观的部署流程看起来都类似：连接存储库，设置构建命令，设置输出目录，添加环境变量，并验证重写规则，以便在刷新时不破坏客户端路由。
对于使用路由器导航的 Ionic 应用程序，托管设置必须将未匹配的路径发送回应用程序入口点。如果没有配置重写规则，主页正常工作，深度链接失败。这是 PWA 部署错误中最常见的一个。
使用 CI/CD Pipelines 自动构建
手动发布工作一次是可以接受的。之后，它就变成了一个负担。有人忘记了同步步骤，某人从脏分支中构建，某人使用了错误的配置签名，突然生成的工件就不能被信任。
CI/CD 修复了这一问题，通过将发布序列转换为 code。而不是依赖于记忆，你定义了每次应用程序如何构建、同步、测试和打包的确切步骤。
管道中应该包含什么
对于 Ionic 项目，一个有用的管道通常会按照以下顺序执行这些任务:
- 从锁文件中安装依赖项。
- 构建 Web 应用。
- 同步 Capacitor 平台。
- 运行测试或至少进行基本验证。
- 为目标平台生成原生 artifact。
- 存储或发布构建输出。
这条流程也是良好基础设施习惯的重要地方。如果您的构建运行器、 artifact 存储或部署步骤感到脆弱，这篇关于 小型企业云优化的必读指南 是值得一读的，因为相同的运营纪律也适用于移动交付管道。
A practical GitHub Actions 形式
GitHub Actions 是一个很好的默认值，因为许多 Ionic 团队已经在 code 上托管 GitHub。以下工作流程展示了 Android 发布构建的整体形状。
name: Android Release Build
on:
push:
branches:
- main
jobs:
build-android:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Build web assets
run: npm run build
- name: Sync Capacitor
run: npx cap sync android
- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 17
- name: Build Android bundle
run: cd android && ./gradlew bundleRelease这不会单独签署一个发布版，除非您还提供.keystore 文件和 Gradle 签名配置。这种设计是有意的。签名应该与公共工作流文件分开。
如果您想实现一个专注于移动端的实施路径，这篇关于 设置 CI/CD 流程的 Capacitor 应用程序 的文章是直接相关的。
机密信息和签名卫生
移动端 CI/CD 中最困难的部分不是编写 YAML 文件。它是处理机密信息而不导致未来的意外事件。
使用以下机密信息：
- Keystore 密码
- 密钥别名
- 编码的.keystore 文件
- API tokens used during release
- 环境特定构建值
在 Android 中，一个常见的模式是将 keystore 进行 base64 编码，存储编码后的字符串到一个秘密中，在工作流中重构它，并指向 Gradle 重构的文件。同样的原则适用于任何签名材料：在构建时注入它，永远不要将其存储在仓库中。
CI/CD 应该消除人类错误，而不是集中化隐匿的部落知识。如果只有一个开发者理解了发布秘密如何组合在一起，管道仍然脆弱。
一个实用的建议：将验证从发布中分离出来。让 pull 请求运行安装、lint、测试和 web 构建。让一个受保护的 branch 或手动批准门控触发签名的生产 artifact。这样可以保持你的管道在正常开发中快速，而在实际发布时受控。
通过 Capgo 快速发布更新
存储的发布是原生 code 变化、权限变化和任何修改应用二进制文件的必要项。它们不是一个好的载体来处理每个文本修复、样式修正或 JavaScript bug，它们完全存在于 web 层。
这就是为什么 OTA 更新 在 Ionic 和 Capacitor 项目中很重要。它们让团队能够在不等待商店审查的情况下将更新的 web 资产发送到安装的应用程序，只要改变保持在原生壳已经支持的范围内。
OTA 更新应该处理什么
使用 OTA 更新的变化包括:
- JavaScript 逻辑修复 不需要新原生插件的修复。
- CSS 调整 修复布局问题或更新品牌。
- 复制更改 例如文字、标签和法律文本。
- 静态资产交换 应用程序已经知道如何加载它们。
不要将其用作绕过平台规则的工作-around。 如果您添加了新原生依赖项、更改了权限或改变了商店审查的二进制文件必须包含的内容，请发布正常的商店版本。
这个界限很重要，因为 OTA 的整个目的就是速度与控制，而不是recklessly绕过平台规则。
在第一次事件之前设置通道
最好的OTA工作流程使用 频道. 一个生产频道向用户提供稳定的更新。一个测试或beta频道首先接收更新，以便内部测试人员可以在真实安装的应用程序中验证它们。
这个模式有助于您避免最糟糕的OTA错误，即因为修复似乎紧急而直接推送给所有人。紧急修复仍然需要引导。
一个典型的设置从插件安装和应用程序初始化开始，按照平台的文档，然后根据环境分配频道。关于 应用商店安全的OTA更新 的文章是一个正确设置边界的参考点。
推送小修复而不触摸本机code
一旦更新器被集成，实用的工作流程就变得简单了。构建更新的Web资产，发布它们到意向频道，然后让应用程序在启动时根据您的更新策略获取和应用它们。
一个真实的例子是一个手机布局回归的热修复:
- 调整Ionic应用程序中的CSS。
- 运行生产Web构建。
- 将生成的捆绑包发布到测试频道。
- 在已安装的构建上进行测试。
- 将相同的修复推送到生产环境。
这种方法会改变事故响应方式。没有OTA，一个坏的Web层bug会让你等待商店的审查和用户的新二进制文件的采用。有了OTA，你可以修复受影响的文件，发送它们给正确的受众，监控在控制下的发布过程。
快速更新只有在你能安全地将它们发送给目标受众并在需要时回滚它们时才有用。
能从OTA中受益最多的团队不是那些莽撞的团队。他们是那些有明确的发布边界、命名的频道和习惯将Web层修复作为一个独立的流程，而不是native发布流程的团队。
常见的部署问题和最佳实践
大多数部署问题都不是独特的。它们在团队之间重复出现，因为在截止日期压力下，同样的错误不断发生。
反复出现的故障
Android签名错误通常是因为使用了错误的密码、错误的别名或错误的keystore文件。发生这种情况时，不要盲目地轮换凭据。首先验证文件、别名和密钥值。
iOS构建失败通常是因为捆绑标识符、团队选择、证书和配置文件不匹配。Xcode的错误消息可能看起来很密集，但不匹配通常是字面上的。其中一个值与其他值不一致。
安装后出现的空白屏幕是另一个经典问题。常见原因包括：
- 生产环境应用指向开发服务器 而不是打包资产
- Web 资产未重建 在
npx cap sync - 前提是 插件更改未同步
- 到本机项目 运行时环境变量值缺失
在实际发布构建中
发布习惯防止重复工作
最佳实践虽然枯燥，但它们有效
保持环境配置的唯一来源。从干净分支构建。标记发布提交。将签名材料存储在外部仓库中。测试安装的构建在真实设备上，而不是仅在模拟器和浏览器标签中。提前准备商店元数据，以便部署不会因截图、隐私答案或缺失副本而卡顿。
如果您的团队部署了Capacitor应用，并且想找到一种更安全的方式来在发布后修复Web层修复， Capgo 它为您提供了一个结构化的OTA工作流程，包括频道、受控的发布和回滚支持，使您可以在不将每个小修复转换为另一个应用商店提交的情况下，发布JavaScript、CSS、复制和资产更新。
