CLI 入门指南

快速概览

该 Capgo CLI 提供了一个交互式引导体验，用于为您的 Capacitor 应用程序设置实时更新。您将：

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

__CAPGO_KEEP_0__ 大约需要

提示

整个引导过程都是可恢复的 - 可以随时退出并在之前停止的地方继续。

开始引导

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

npx @capgo/cli@latest init [APIKEY]

您将看到欢迎消息：

Capgo onboarding 🛫

注册过程

The CLI will guide you through 13 interactive steps:

设置阶段（步骤 1-6）：

• 检查开发环境（Xcode/Android Studio）
• 将您的应用程序添加到Capgo并创建生产渠道
• 安装 @capgo/capacitor-updater 插件
• 将所需的code注入您的应用程序
• 可选：启用端到端加密
• 选择测试平台（iOS或Android）

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

• 构建您的应用并在设备/模拟器上运行
• 进行可见的 code 变更 (自动或手动)
• 将更新的捆绑包上传到 Capgo
• 在实时看到您的设备上更新的效果

完成 (步骤 13):

• 您的应用已准备好实时更新！ 🎉

13 步入门流程

步骤 1：检查前置条件

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

What’s checked:

• Xcode (macOS only) - for iOS开发
• Android SDK - for Android开发

可能的结果:

✅ Both environments found:

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

⚠️ No environment found:

⚠️ 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 步：添加您的应用

CLI 将登录到 Capgo 并将您的应用添加到您的帐户中。

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

❓ Add {appId} in Capgo?

如果您的应用 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 IDs必须遵循反向域名表示法（例如， com.example.myapp)

步骤 3：创建生产渠道

渠道允许您管理应用程序的不同更新流

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

提示

别担心！ 这只是用于本地测试的过程。创建“生产”渠道并不意味着您的更新将立即发布给客户。您完全控制更新何时部署。选择 是 除非您有特定的渠道要求

如果您选择是：

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

将会创建一个生产频道并设置为默认频道。这是大多数用户的推荐选项。

如果您选择否：

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

您需要在后期手动创建和配置频道。或者，您可以：

• 在您的 capacitor.config.ts 文件
• 使用 JavaScript setChannel() 方法动态设置频道
• 从Capgo web控制台中配置频道

步骤 4：安装更新插件

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

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

__CAPGO_KEEP_0__版本兼容性

• 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

提示

即时更新是什么? 启用即时更新后，应用程序会立即在后台和重新打开时应用更新。这一切都非常顺畅，因为 Capgo 可以在 300ms 内在全球范围内分发更新。没有它（标准模式），更新会在后台下载并在下一次应用程序重启时应用。即时更新对于开发期间的快速迭代和生产环境中的关键 bug 修复非常有用。

如果您选择是：

• 更新将配置为在应用程序后台和重新打开时立即应用
• autoUpdate: 'always' 并 autoSplashscreen: true 将添加到您的配置
• 您的 capacitor.config.ts 将自动更新
• 差分更新 将自动启用 - 这样只会发送更新之间变化的文件，而不是整个捆绑包，这使得更新速度大大提高

如果您选择否：

• 更新将使用标准行为（后台下载，下一次重启时应用）
• 您可以随时通过修改您的配置来启用即时更新 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()
})

对于其他框架: 将此 __CAPGO_KEEP_0__ 添加到您的主入口文件（例如 main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

将此 code 放在您的导入之后和应用初始化之前。有关详细信息，请参见 添加应用程序指南.

步骤 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：选择平台

步骤 7：选择平台

📱 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

提示

这只会影响引导流程。您的最终应用程序将支持所有平台。

步骤 8：构建您的项目

CLI 将构建您的应用程序并同步它与 Capacitor。

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

发生什么事：

1. 检测您的项目类型
2. 运行您的构建脚本
3. 执行 npx cap sync {platform}

如果构建脚本丢失：

您将被询问是否要跳过构建或添加一个构建脚本到您的 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

自动模式： The CLI will automatically modify your files to add a visible test banner or change.

手动模式： 您自己修改（例如，改变文本、颜色或添加元素）。

版本处理：

❓ 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 {appId} with changes before uploading?

提示

如果您需要在另一个终端手动构建，请选择“否”，然后自己构建，然后继续。

步骤 11: 上传包

将您的更新应用程序包上传到 Capgo。

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

CLI 运行：

npx @capgo/cli@latest bundle upload

提示

Delta 更新与即时更新： 如果您在步骤 4 中启用了即时更新，CLI 将自动询问是否要启用 Delta 更新。Delta 更新只发送文件之间的版本变化而不是整个包。由于通常只有少数文件在更新之间会发生变化，因此这使得下载速度大大加快。请选择 是 为了获得最佳体验和即时更新。

如果启用了即时应用模式，Delta更新提示：

💡 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)

注意

对于多包仓库，您可能需要提供额外的路径到您的 package.json 和 node_modules.

成功：

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

第 12 步：在设备上测试更新

看看更新的效果吧！

🧪 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实时更新功能。

您已经实现了什么

完成入门后，您已经完成了：

✅ 应用程序已注册

您的应用程序已在Capgo中注册，生产频道

✅ 插件已安装

Capacitor更新器插件已安装并配置

✅ Code已集成

将code集成到您的应用程序中

✅ 更新已测试

您已成功部署并接收到实时更新

每日工作流

对于后续的更新，请使用：

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

更多部署选项，请参见 部署实时更新.

恢复引导

终端窗口

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 已经被占用

问题： 您的应用 ID 已经注册过了。

解决方案： 选择以下建议的替代方案之一，或者输入一个自定义的应用ID，使用反向域名表示法。

构建脚本缺失

问题： 在 package.json.

中未找到构建脚本。 解决方案： package.json:

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

添加一个构建脚本。

自动注入失败（Auto-Injection Failed） CLI 不能自动注入该集成 code。

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

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

CapacitorUpdater.notifyAppReady()

Capacitor 版本过低

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

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

• 升级到 Capacitor 5
• 升级到 Capacitor 6
• 升级到 Capacitor 7

下一步

您已经完成了入门流程后，探索这些主题：

一次性设置清单

配置通道、CI和delta上传一次，长期稳定

部署更新

从 Capgo 控制台中学习如何部署更新

更新类型

OTA更新类型的参考：应用时间、延迟条件、版本阻塞和交付

CI/CD集成

使用CI/CD自动化您的更新部署

频道

使用频道管理多个更新流

加密

使用端到端加密保护更新

更新行为

自定义更新时机和方式（直接、差分等）

获取帮助

如果您在入门过程中遇到问题：

• 检查 故障排除指南
• 加入 Discord 社区
• Review the FAQ
• 联系我们 支持

CLI 入门指南继续

如果您正在使用 CLI 入门指南 来规划仪表板和API 运营，连接它与 API 概览 查看API 概览中的实施细节 简介 简介中的实现细节 API 键 API 键中的实现细节 设备 设备中的实现细节 捆绑包 捆绑包中的实现细节