用于版本更新的 Capacitor CLI 命令

Capacitor CLI 简化了 应用更新 适用于 iOS 和 Android。以下是你需要了解的：

• 为什么要更新？ 保持安全、提升性能，并确保兼容最新的移动操作系统版本。
• 核心命令： 使用 npm install @capacitor/cli@latest 更新 Capacitor CLI， npx cap migrate 应用更改，并 npx cap sync 改为 完成更新.
• 平台特定步骤： 更新 iOS 时使用 CocoaPods (pod install) 以及 Xcode 的 Mac 设置。对于 Android，请调整 Gradle 配置并验证 Java 版本。
• 使用 Capgo 用于 Live Updates： 无需等待应用商店审核延迟，即可即时部署变更，并支持回滚和实时分析等功能。

保持更新可确保您的应用高效且易用。请按上述步骤操作，以确保流程顺畅。

如何将您的 Ionic App 迁移至 Capacitor 3

更新前须知

更新前花点时间做准备，能帮你避免后续的各种麻烦。做好基础工作有助于规避常见陷阱，确保一切顺利运行。以下是你在期间需要重点关注的内容，以将风险降至最低： 更新流程的重要性.

检查系统要求

首先，确保你的开发环境满足 Capacitor 的要求。版本 6 和 7 有特定的软件需求 [1].

你需要检查以下内容：

• Node.js：检查你的 Node.js 版本是否兼容。
• 特定平台工具:
  • 对于 iOS 开发，请确保已安装最新版本的 Xcode。
  • 对于 Android，请确认 Android Studio 中的错误日志 是最新版本。

阅读更新说明

更新说明是了解变更可能如何影响项目的指南。请花时间查看以下内容：

• 官方文档：查看 Capacitor 的 changelog 和迁移指南。
• 破坏性变更：密切关注标有“Breaking Changes”的章节。这些部分通常会标出可能打乱你工作流的关键更新。
• 插件兼容性：再次确认项目中的所有 Capacitor 插件都受新版本支持。

CLI 更新命令

这些命令可以帮助你更新应用，同时确保各项功能持续平稳运行。

更新 Capacitor CLI

若要使用最新功能，请更新你的 Capacitor CLI。打开终端并运行：

npm install -g @capacitor/cli@latest

安装完成后，检查 CLI 版本即可确认更新：

npx cap --version

运行迁移命令

在项目目录中，执行以下命令来更新核心及平台专用的 Capacitor 包：

# Update core Capacitor packages
npm install @capacitor/core@latest
npm install @capacitor/cli@latest

# Update platform-specific packages
npm install @capacitor/ios@latest
npm install @capacitor/android@latest

# Run the migration command
npx cap migrate

本指南中介绍的 npx cap migrate 该命令会：

• 更新应用的配置
• 同步依赖项
• 应用必要的项目变更
• 验证插件的兼容性

如果有些更新无法自动处理，你可能需要手动完成。

完成手动步骤

要让项目与更新后的平台同步，请运行：

npx cap sync

如需更多自动化，可以运行以下命令集成 Capgo 的 CLI 工具：

npx @capgo/cli init

最后，为每个平台构建应用，以验证更新：

# For iOS
npx cap open ios

# For Android
npx cap open android

如果在更新过程中遇到问题，CLI 会提供详细的错误信息以协助排查。请务必查看构建输出，留意任何需要关注的警告或错误。

平台更新

核心更新完成后，下一步是微调 iOS 和 Android 项目的平台配置。

iOS 更新步骤

要开始处理 iOS 项目，请在 Xcode 中打开它并按照以下步骤操作：

• 更新 CocoaPods 依赖
  首先用 CocoaPods 刷新依赖。进入 iOS 项目目录并运行以下命令：

  cd ios/App
  pod install

• 配置 Xcode 设置
  请确保更新以下 Xcode 设置，以保证运行顺畅并符合合规要求：

  设置	需要操作	用途
  部署目标	设置最低 iOS 版本	确保兼容性
  Build Settings 中调高部署目标	更新签名身份	满足 App Store 要求
  资源目录	验证图标和启动图资源	保持视觉一致性

• 清理构建
  清理缓存文件并执行 clean build，以避免残留问题带来的干扰：

  # Clean the build folder
  xcodebuild clean
  # Build the project
  xcodebuild build

iOS 更新完成后，即可开始处理 Android 项目。

Android 更新步骤

对于 Android，请在 Android Studio 中打开项目并执行以下步骤：

• 更新 Gradle 配置
  打开你的 build.gradle 文件，并确认这些设置已正确配置：

  android {
      compileSdkVersion 33
      defaultConfig {
          minSdkVersion 22
          targetSdkVersion 33
      }
  }

• 同步项目文件
  将项目与 Gradle 文件同步，确保所有依赖项都是最新版本。此步骤可能还涉及更新 SDK 工具并解决任何冲突。

• 验证 Java 版本
  检查您使用的 Java 版本是否正确，这对于与 Gradle 和 Android 特性的兼容性至关重要：

  # Check the current Java version
  ./gradlew --version

请务必密切关注您的 Gradle 配置。某些更新可能需要更高版本的 Gradle，以更有效地支持最新的 Android 特性。

结合 Live Updates Capgo

平台配置完成后，你可以用 Capgo 立即发布变更，无需等待应用商店审核。这一步通过启用实时部署能力，进一步增强了平台更新。

配置 Capgo

开始使用 Capgo 很简单，只需一条命令即可初始化：

npx @capgo/cli init

该功能简化了更新流程，让你的 App 无需经历传统审核周期的延迟即可保持最新。Capgo 兼容 Capacitor 8，是你现有架构的灵活选择。

更新安全特性

Capgo 优先保障更新的安全与可靠，在 24 小时内实现了 95% 的采用率，全球成功率达 82% [1]。其中包括几项关键安全特性：

• 回滚能力：若出现任何问题，可快速回滚至之前的版本。
• 错误追踪: 在问题影响用户之前识别并解决。
• 基于 Channel 的分发: 通过 Beta 组测试更新 再大规模发布。

CI/CD 集成

安全措施到位后，您可以将 Capgo 集成到现有的 CI/CD 工作流中，实现顺畅高效的部署。对于该工作流中的 Native Build，Capgo 方案起售价为 $12/月，包含 OTA 更新及每月约 15 次 Native Build。超出部分的构建时长将通过积分按分钟计费。

以下是部署命令示例：

npx @capgo/cli deploy --channel production

Capgo 支持多种 CI/CD 平台，包括：

• GitHub 操作
• GitLab CI
• Jenkins
• 自定义 pipeline 配置

修复常见问题

Capacitor 更新 有时会引发问题，影响应用的稳定性。以下介绍如何有效解决这些常见问题。

解决包冲突

首先检查你的 Capacitor 包是否存在版本不匹配。使用以下命令：

npm ls @capacitor/core

查看输出结果，确保 @capacitor/core, @capacitor/ios，以及 @capacitor/android 在您的 package.json 文件。如果发现任何冲突，请更新或移除有问题的包，以稳定你的环境。

解决这些问题后，请再次确认所有已安装插件都与更新后的 Capacitor 版本兼容。

检查插件支持

在更新前，请确保你的插件已准备好与最新的 Capacitor 版本配合使用。使用以下命令管理和验证插件兼容性：

如果你使用的是 live update 这类工具 Capgo，请确认你的插件支持动态更新。这有助于避免运行时冲突，并让性能更流畅。

解决 Build 错误

Build 错误会因平台而异，以下是各平台的修复方法：

iOS 端：

使用以下命令清理 build 文件夹：

xcodebuild clean -workspace ios/App/App.xcworkspace -scheme App

针对 Android：

运行以下命令清除 Gradle 缓存：

cd android && ./gradlew clean

如果清理后错误仍未解决，可能需要重新添加受影响的平台。操作如下：

npx cap rm ios
npx cap rm android
npx cap add ios
npx cap add android

最后，如果你使用 Capgo 做 Live Updates，请再确认一下你的 build 配置是否满足平台要求，以避免后续问题。

总结

本节重点介绍 更新管理 在 Capacitor 中的关键步骤和工具，并强调如何有效利用 Capacitor CLI 命令 可确保应用开发流程顺畅。文中讨论的工具和策略旨在简化更新，同时降低潜在风险。

前面我们提到，Capgo 支持 1.7K 个生产环境应用，并取得了令人瞩目的 82% 更新成功率 [1]。其即时更新功能可让 95% 的用户在 24 小时内完成更新 [1]，充分展示了其高效性。

以下是 Capgo 的性能指标概览：

“我们采用敏捷开发，@Capgo 对于向用户持续交付至关重要！” —— Rodrigo Mantica [1]

现代更新工具带来多项显著优势：

• 端到端加密 用于安全交付更新
• 增量更新，只下载修改过的组件，从而节省带宽
• 一键回滚 用于在出现问题时快速恢复
• 实时分析 用于监控更新性能和用户参与度

这些功能为高效管理 版本更新 提供了强大的框架。

无论您是在开发小型应用，还是在扩展更大规模的部署，将 Capacitor CLI 与高级更新工具结合，都能在当今快速迭代的开发环境中确保可靠、高效的版本控制。

常见问题

::: 常见问题

使用 Capacitor CLI 更新我的应用时，可能会遇到哪些挑战？又该如何应对？

在使用 Capacitor CLI 更新你的应用时，可能会遇到一些小问题。常见的挑战包括： 依赖冲突, 插件中的 breaking changes，或 特定平台的配置问题。这些问题通常源于 Capacitor 版本之间的差异，或第三方插件的更新。

你可以这样应对这些挑战：

• 查看 Release Notes 针对你要升级到的新版本。留意 breaking changes 或任何需要做的调整。
• 在 staging 环境中测试更新 在将它们发布到生产环境之前。这能帮你在问题影响用户之前发现并修复它们。
• 定期更新依赖项和插件，以降低兼容性问题的风险。

想要更流畅的更新体验，可以试试这些工具： Capgo。该工具让你无需应用商店审核，就能直接向用户推送修复和新功能。这是让应用保持最新、同时尽量减少停机时间的绝佳方式。 :::

::: 常见问题

Capgo 如何简化应用更新？它有哪些亮点功能？

Capgo 简化了开发者交付 应用更新 的方式，让他们能够直接向用户推送改动、修复和新功能，无需应用商店审核。这样一来，用户几分钟内就能用上最新更新，体验更流畅、更高效。

让 Capgo 脱颖而出的地方：

• 端到端加密 确保您的更新始终安全。
• CI/CD 集成 帮助保持精简顺畅的工作流。
• 针对特定用户的更新 实现精准的定向发布。
• 灵活的组织管理 支持各种规模的团队。

Capgo 完全开源，并符合 Apple 和 Android 标准，为以下场景提供可靠的解决方案： 实时 App 更新. :::

::: 常见问题

在更新之前，我该如何检查我的插件是否兼容最新版本的 Capacitor？

在升级到最新版本的 Capacitor 之前，务必仔细检查您的插件是否已做好更新准备。首先，深入查看插件的文档或代码仓库，确认是否存在特定版本的要求或更新。大多数插件都会明确标出它们支持哪些 Capacitor 版本，这一步可以帮您避免不必要的麻烦。

你还可以在受控环境中，用更新后的 Capacitor 版本测试你的应用。这样就能在更新正式上线生产环境前，发现并修复任何兼容性问题。像这样的工具 Capgo 在这里能派上大用场，让你无需应用商店审核即可直接推送更新。这意味着你可以在遵守平台规范的同时，快速解决插件相关问题。 :::

继续阅读 Capacitor CLI 版本更新命令

如果你正在使用 用于版本更新的 Capacitor CLI 命令 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。