CLI 入门指南

快速入门概览

Capgo CLI 提供交互式入门指南，为您的 Capacitor 应用配置 Live Update。您将：

1. ✅ 在 Capgo 中注册您的应用
2. 🔌 安装并配置 updater 插件
3. 🚀 部署您的第一个 live update
4. 📱 在设备上测试更新

预计耗时： 10-20 分钟（取决于您的网速和 build 时间）

提示

入门流程支持随时中断并恢复 —— 您可以随时退出，稍后从上次中断的地方继续。

开始入门指南

使用您的 API 密钥运行 onboarding 命令：

npx @capgo/cli@latest init [APIKEY]

您将看到欢迎信息：

Capgo onboarding 🛫

Onboarding 过程中会发生什么

CLI 将引导您完成 13 个交互式步骤：

配置阶段 (步骤 1-6)：

• 检查您的开发环境 (Xcode/Android Studio)
• 将您的应用添加到 Capgo 并创建生产环境 channel
• 安装 @capgo/capacitor-updater plugin
• 在应用中注入必要的 code
• （可选）启用端到端加密
• 选择测试平台 (iOS 或 Android)

测试阶段 (步骤 7-12):

• 构建应用并在真机/模拟器上运行
• 进行可见的 code 变更 (自动或手动)
• 将更新后的 bundle upload 至 Capgo
• 实时查看设备上出现的 live update

完成 (步骤 13):

• 您的应用已准备好进行 Live Update! 🎉

13 步入门指南

第 1 步：检查前置条件

CLI 会检查您的开发环境，以确保您已安装必要的工具。

检查项目：

• Xcode （仅限 macOS）- 用于 iOS 开发
• Android SDK - 用于 Android 开发

可能的结果：

✅ 两个环境均已找到：

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ 未找到环境：

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

可能会问到的问题：

注意

如果未检测到开发环境，系统会询问你是否继续。建议在继续之前至少安装一个平台。

第 2 步：添加您的 App

CLI 将引导你登录 Capgo 并将你的 App 添加到账户中。

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

如果您的 App ID 已被占用：

CLI 将会提供以下建议：

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

您可以选择建议的 ID 或输入自定义 App ID。

注意

App ID 必须遵循反向域名格式（例如， com.example.myapp)

步骤 3：创建生产环境 Channel

Channel 可以让您管理应用的不同更新流。

❓ Create default channel production for {appId} in Capgo?

提示

别担心！ 这仅用于 onboarding 期间的本地测试。创建“production”频道并不意味着您的更新会立即推送给用户。您可以完全控制更新的部署时机。请选择 是 除非您有特定的频道需求。

如果您选择“是”：

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

将创建一个 production 频道并将其设为默认值。这是大多数用户的推荐选项。

如果您选择“否”：

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

您稍后需要手动创建并配置频道。或者，您可以：

• 在您的 capacitor.config.ts 文件中设置频道
• 使用 JavaScript setChannel() 方法动态设置 channel
• 稍后可通过 Capgo Web 控制台配置 channel

第 4 步：安装 Updater Plugin

CLI 将安装 @capgo/capacitor-updater 与您的 Capacitor 版本兼容的 plugin。

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

版本兼容性：

• Capacitor 5：安装 @capgo/capacitor-updater v5
• Capacitor 6：安装 @capgo/capacitor-updater v6
• Capacitor 7：安装 @capgo/capacitor-updater v7
• Capacitor 8+：安装最新版本

注意

Capgo 仅支持 Capacitor v5 及以上版本。如果您使用的是旧版本，需要先进行升级。

即时更新选项：

安装完成后，系统会提示您：

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

提示

什么是 instant updates？ 启用 instant updates 后，您的 App 在进入后台并重新打开时会立即应用更新。由于 Capgo 可以在 300ms 内在全球范围内分发更新，因此这一过程非常顺畅。如果不使用它（标准模式），更新将在后台下载并在下次重启 App 时应用。instant updates 非常适合在开发期间进行快速迭代，以及在生产环境中修复紧急 Bug。

如果您选择“是”：

• 更新将被配置为在 App 进入后台并重新打开时立即应用
• autoUpdate: 'always' 和 autoSplashscreen: true 将被添加到您的配置中
• @capacitor/splash-screen 如果缺失将会被安装，并带有 launchAutoHide: false
• 您的 capacitor.config.ts 将自动更新
• 增量更新 保持启用。即时应用（always, atInstall, onLaunch）应继续使用 npx @capgo/cli@latest bundle upload --delta 这样只会下载变更的文件，用户无需等待完整 zip 包下载

如果选择“否”：

• 更新将采用标准行为（后台下载，下次重启时生效）
• 您之后随时可以通过修改您的配置来启用即时更新 capacitor.config.ts

第 5 步：添加集成 Code

CLI 会自动将所需的 code 注入到您的主应用文件中。

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

新增内容：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

项目类型检测：

• Nuxt.js：创建 plugins/capacitorUpdater.client.ts
• 其他框架：添加到主入口文件

提示

如果自动注入失败，你可以手动将 code 添加到应用主文件中：

针对 Nuxt.js： 创建 plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

针对其他框架： 添加到你的主入口文件（例如： main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

请将此 code 放在 import 语句之后、应用初始化之前。更多详情请参阅 添加 App 指南.

步骤 6：设置加密（可选）

端到端加密为你的更新提供了额外的安全保障。

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

注意

加密功能仅适用于 Capacitor v6 及更高版本。

如果您启用加密，CLI 将：

1. 生成加密密钥
2. 提示同步您的 Capacitor 配置

步骤 7：选择平台

在 onboarding 期间选择要测试的平台。

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

提示

这仅影响 onboarding 流程。您的最终 App 将支持所有平台。

第 8 步：构建项目

CLI 将构建您的应用并将其与 Capacitor 同步。

❓ Automatic build {appId} with "npm run build"?

具体流程：

1. 检测项目类型
2. 运行 build 脚本
3. 执行中 npx cap sync {platform}

如果缺少 build 脚本：

系统会询问您是要跳过构建，还是为您的项目添加一个 build 脚本 package.json.

第 9 步：在设备上运行

在真机或模拟器上测试应用的初始版本。

❓ Run {appId} on {PLATFORM} device now to test the initial version?

如果你选择 是:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

步骤 10：进行测试更改

现在可以通过进行一项可见的更改来测试 Capgo 的更新系统了。

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

自动模式： CLI 会自动修改你的文件，以添加一个可见的测试横幅或更改。

手动模式： 你可以进行自定义修改（例如：更改文本、颜色或添加元素）。

版本管理：

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

包含修改内容的 Build：

❓ Build {appId} with changes before uploading?

提示

如果你需要在另一个终端手动进行 build，请选择“No”并自行构建，完成后继续。

第 11 步：Upload Bundle

将更新后的 app bundle upload 到 Capgo。

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

CLI 正在运行：

npx @capgo/cli@latest bundle upload

提示

支持即时更新的增量更新： 如果你在第 4 步启用了 instant updates，CLI 会自动询问是否启用 delta updates。Delta updates 仅发送版本间发生变化的文件，而不是整个 bundle。由于更新时通常只有少量文件变动，这会让下载速度大幅提升。请选择 是 以获得最佳的 instant updates 体验。

Delta updates 提示（如果已启用 instant apply 模式）：

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

注意

For monorepos, you may need to provide additional paths to your package.json 和 node_modules.

成功：

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

第 12 步：在设备上测试 Update

是时候看看 Update 的实际效果了！

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

对于即时更新：

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

对于标准更新：

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

监控日志：

❓ Monitor Capgo logs to verify the update worked?

如果你选择 是，你将看到来自设备的实时日志，展示更新过程。

第 13 步：完成

Welcome onboard ✈️!

恭喜！你已成功为应用配置好 Capgo live updates。

你已完成的任务

完成 onboarding 后，你已实现：

✅ App 已注册

你的 App 已在 Capgo 中注册并配置了 production channel

✅ Plugin 已安装

Capacitor Updater plugin 已安装并配置完成

✅ 已集成 Code

code 集成已添加到你的 App 中

✅ 更新测试通过

你已成功部署并接收到了 live update

日常工作流

后续更新请使用：

npm run build
npx @capgo/cli@latest bundle upload --channel=production

了解更多部署选项，请参阅 部署 Live Update.

继续 Onboarding

如果您退出了 onboarding 流程，可以随时恢复：

npx @capgo/cli@latest init [APIKEY]

您将看到：

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

提示

进度已保存在本地，您可以放心退出并随时恢复 onboarding 流程。

故障排除

未检测到开发环境

问题： 未检测到 Xcode 或 Android SDK。

解决方案：

• 适用于 iOS安装 Xcode (仅限 macOS)
• 适用于 Android: 安装 Android Studio

App ID 已被占用

问题： 您的 app ID 已被注册。

解决方案： 选择建议的备选 ID，或使用反向域名格式输入自定义 app ID。

缺少 Build Script

问题： 在以下路径中未找到 build script： package.json.

解决方案： 请在你的项目中添加 build script： package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

自动注入失败

问题： CLI 无法自动注入集成组件 code。

解决方案： 请手动将 code 添加到你的主文件中：

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Capacitor 版本过低

问题： 您的 Capacitor 版本低于 v5。

解决方案： 将 Capacitor 升级至 v5 或更高版本：

• 升级至 Capacitor 5
• 升级至 Capacitor 6
• 升级至 Capacitor 7

下一步

完成 onboarding 后，您可以进一步探索以下主题：

一次性设置清单

一次性配置好 Channel、CI 和 delta upload，确保长期运行的稳定性

部署 Updates

了解如何通过 Capgo dashboard 部署 updates

更新类型

所有 OTA update 类型参考：应用时机、延迟条件、版本限制及交付方式

CI/CD 集成

通过 CI/CD 实现 update 部署自动化

渠道

使用 Channel 管理多个 update 流

加密

通过端到端加密保障 updates 安全

更新行为

自定义更新的应用时机与方式（直接更新、增量更新等）

获取帮助

如果在入门阶段遇到问题：

• 查看 故障排除指南
• 加入 Discord 社区
• 查阅 常见问题
• 联系我们 支持

继续阅读 CLI 入门指南

如果你正在使用 CLI 入门指南 来规划 dashboard 和 API 操作，请将其连接至 API 概览 关于 API 概览中的实现细节， 简介 了解“简介”中的实现细节， API 密钥 了解“API Keys”中的实现细节， 设备 有关 Devices 的实现细节，请参阅 Bundles 有关 Bundles 的实现细节，请参阅