CLI 入职指南

快速概述

Capgo CLI 提供交互式入门，为您的 Capacitor 应用程序设置实时更新。你会：

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

预计时间： 10-20 分钟（根据您的互联网速度和构建时间而有所不同）

提示

入职培训是完全可恢复的 - 随时退出并稍后从上次中断的地方继续。

开始入职

使用 API 密钥运行入门命令：

npx @capgo/cli@latest init [APIKEY]

您将看到欢迎消息：

Capgo onboarding 🛫

入职期间会发生什么

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

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

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

测试阶段（步骤 7-12）：

• 构建您的应用程序并在设备/模拟器上运行它
• 进行可见的代码更改（自动或手动）
• 将更新后的捆绑包上传到 Capgo
• 实时查看您设备上显示的实时更新

完成（步骤 13）：

• 您的应用程序已准备好进行实时更新！ 🎉

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

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。

注意

应用 ID 必须遵循反向域表示法（例如 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 将安装与您的 Capacitor 版本兼容的 @capgo/capacitor-updater 插件。

❓ 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

提示

什么是即时更新？ 启用即时更新后，您的应用程序在后台运行并重新打开时会立即应用更新。这可以无缝工作，因为 Capgo 可以在 300 毫秒内在全球范围内分发更新。如果没有它（标准模式），更新将在后台下载并在下次应用程序重新启动时应用。即时更新对于开发过程中的更快迭代和生产中的关键错误修复非常有用。

如果您选择是：

• 更新将配置为在应用程序后台运行并重新打开时立即应用
• directUpdate: 'always' 和 autoSplashscreen: true 将添加到您的配置中
• 您的 capacitor.config.ts 将自动更新
• 增量更新将自动启用 - 这仅发送更新之间更改的文件而不是完整的捆绑包，从而使更新速度更快

如果您选择否：

• 更新将使用标准行为（在后台下载，在下次重新启动时应用）
• 您以后随时可以通过修改 capacitor.config.ts 来启用即时更新

步骤 5：添加集成代码

CLI 会自动将所需的代码注入到您的主应用程序文件中。

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

添加了什么：

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

CapacitorUpdater.notifyAppReady()

项目类型检测：

• Nuxt.js：创建 plugins/capacitorUpdater.client.ts
• 其他框架：添加到您的主条目文件中

提示

如果自动注入失败，您可以手动将代码添加到主应用程序文件中：

对于 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()

将此代码放在导入之后和应用程序初始化之前。有关更多详细信息，请参阅添加应用程序指南。

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

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

📱 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

自动模式： 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 {appId} with changes before uploading?

提示

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

第 11 步：上传包

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

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

CLI 运行：

npx @capgo/cli@latest bundle upload

提示

使用直接更新进行增量更新： 如果您在步骤 4 中启用了即时更新（直接更新），CLI 将自动询问您是否要启用增量更新。增量更新仅发送版本之间发生更改的文件，而不是整个捆绑包。由于更新之间通常只有少数文件发生变化，这使得下载速度更快。选择是以获得即时更新的最佳体验。

Delta 更新提示（如果启用了直接更新）：

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

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

警告

对于 monorepos，您可能需要提供指向 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 更新程序插件已安装并配置

✅ 代码集成

集成代码已添加到您的应用程序中

✅ 更新已测试

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

日常工作流程

对于后续更新，请使用：

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?

提示

进度保存在本地，因此您可以安全退出并恢复入门过程。

故障排除

无开发环境

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

解决方案：

• 对于 iOS：安装 Xcode（仅限 macOS）
• 对于 Android：安装 Android Studio

应用程序 ID 已被占用

问题： 您的应用程序 ID 已注册。

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

缺少构建脚本

问题： 在 package.json 中找不到构建脚本。

解决方案： 将构建脚本添加到您的 package.json 中：

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

自动注入失败

问题： CLI 无法自动注入集成代码。

解决方案： 将代码手动添加到您的主文件中：

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

CapacitorUpdater.notifyAppReady()

Capacitor 版本太旧

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

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

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

后续步骤

现在您已完成入职培训，请探索以下主题：

部署更新

了解如何从 Capgo 仪表板部署更新

更新类型

所有OTA更新类型参考：应用时机、延迟条件、版本阻止和交付

持续集成/持续交付集成

使用 CI/CD 自动执行更新部署

Channels

使用通道管理多个更新流

Encryption

通过端到端加密保护您的更新

更新行为

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

获取帮助

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

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