在中国使用 Capgo

如果您的应用面向中国用户发布，则需要配置 Capgo 以使用区域性 OST (Object Storage Technology) URL，从而确保更新过程既快速又可靠。

为什么要使用中国专用 URL？

由于中国的网络基础设施和监管政策（防火长城），直接连接国际服务器可能会出现延迟或不稳定。Capgo 提供专门的 OST URL，数据存储在香港，以最大限度地降低延迟，并确保您的用户能够尽可能快速、可靠地接收更新。

配置

要在中国配置 Capgo，您需要在 Capacitor 配置文件中设置三个特定的 URL。这些 URL 指向 Capgo 位于香港的基础设施。

1. 打开你的 capacitor.config.ts 文件

2. 请在以下 CapacitorUpdater plugin 部分添加配置：

   import { CapacitorConfig } from '@capacitor/cli';
   
   const config: CapacitorConfig = {
     plugins: {
       CapacitorUpdater: {
         autoUpdate: 'atBackground',
         updateUrl: 'https://updater.capgo.com.cn/updates',
         statsUrl: 'https://updater.capgo.com.cn/stats',
         channelUrl: 'https://updater.capgo.com.cn/channel_self',
       },
     },
   };
   
   export default config;

3. 重新构建您的 App 以应用更改：

   npm run build
   npx cap sync

配置详情

各 URL 的作用如下：

• updateUrl: https://updater.capgo.com.cn/updates - 用于检查并下载应用可用的更新
• statsUrl: https://updater.capgo.com.cn/stats - 用于向 Capgo 上报分析数据和使用统计
• channelUrl: https://updater.capgo.com.cn/channel_self - 用于获取 channel 配置并确定要应用哪些更新

提示

必须同时配置这三个 URL，才能确保 Capgo 更新器在中国完整可用。

中国区推荐设置

由于中国防火长城（GFW）造成的网络性能限制，我们针对部署在中国大陆的应用有以下建议：

调高 API 响应超时时间

Capgo 更新器插件会在 API 调用超过限制时中止 responseTimeout （数值单位为 秒）。Capgo 前面的边缘基础设施也会将约 3 秒 作为某些路径的容错预算。

在中国大陆，跨境延迟通常较高。请为中国部署设置较高的 responseTimeout 这样插件就有足够的余量来完成 Live Update 的检查和下载过程 updater.capgo.com.cn 而不是过早失败：

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      // Seconds. Raise above the default (20) for China network conditions.
      responseTimeout: 60,
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

提示

优先使用 responseTimeout: 60 (或更高) 的超时时间。较低的超时时间并不会让更新变快 —— 它只会导致插件在 Capgo 端请求可能成功时提前放弃。

使用 Background Updates

我们 强烈建议使用 autoUpdate: 'atBackground' 针对中国地区的 App。由于中国境内的网络连接性能通常低于其他地区，如果下载中断或速度过慢，instant apply 模式可能会导致糟糕的用户体验。

建议改用默认的更新行为，即在后台下载更新，并在 App 进入后台或重启时应用更新。这能为您的用户提供更可靠的体验。

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

注意

虽然我们位于香港的基础设施有助于降低延迟并提高可靠性，但前往中国大陆的网络性能仍可能受到防火墙的影响。使用后台更新有助于确保更新成功完成，且不会干扰用户体验。

完整配置示例

以下是针对部署在中国地区的 App 所推荐设置的完整示例：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for better reliability in China
      responseTimeout: 60, // Seconds — give China network more room
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

export default config;

测试您的配置

配置完中国区专用 URL 后，您可以验证更新是否正常工作：

1. 向 Capgo 上传新 bundle：

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

2. 在中国的测试设备上安装您的 App

3. 监控更新过程：

   npx @capgo/cli@latest app debug

4. 检查更新是否正从中国 OST URL 下载

注意

更新行为和时机与标准的 Capgo 配置保持一致。请参阅 更新行为 有关更新如何应用以及何时应用的详细文档。

多区域部署

如果您的应用同时面向中国境内外用户，可以为全球所有用户使用中国域名配置。得益于 updater.capgo.com.cn Alibaba DNS 基础设施，该域名可在全球范围内解析，确保中国境内及世界其他地区均可访问。

在全球范围内使用中国域名

中国域名 URL 可在多区域应用中无缝运行：

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China users
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

此单一配置将适用于：

• 中国大陆用户（使用基于香港的基础设施）
• 中国境外用户（通过 Alibaba DNS 访问相同的基础设施）

性能注意事项：

虽然 .cn 域名通过 Alibaba DNS 进行全球解析并在任何地方都能使用，但与标准域名相比，对于中国境外用户的性能略低（api.capgo.app标准域名由我们的后端托管地 Cloudflare 直接解析）。不过，DNS 解析速度很快，因此性能差异极小，不会显著影响用户体验。

提示

使用 .cn 域名供所有用户使用可以简化您的部署，并确保所有地区的更新行为保持一致。您无需进行单独的 build 或基于环境的配置。中国境外微小的性能权衡通常是值得的，因为这简化了部署流程。

备选方案：特定区域配置

如果您希望针对不同地区进行差异化优化，也可以考虑：

• 构建具有不同配置的独立 App 版本
• 使用基于环境的配置来动态设置 URL
• 为不同地区创建不同的发布渠道 (release channels)

如果您在多地区部署策略方面需要帮助，请通过以下方式联系我们： support@capgo.app 或者加入我们的 Discord 社区 获取帮助。

监控中国区基础设施

您可以在此处监控 Capgo 中国区特定端点的运行状况和状态： 状态 capgo.com.cn. 在排查应用问题前，请通过此页面检查中国区 OST URL 的故障、延迟及在线状态。

故障排除

如果在中国的更新出现问题：

1. 验证配置 - 请再次确认您的配置中已正确设置这三个 URL capacitor.config.ts
2. 提高 responseTimeout - 在中国区请至少使用 60 秒，以确保更新请求在进行中时插件不会中断
3. 检查网络连接 - 确保您的设备可以访问 updater.capgo.com.cn 域名
4. 查看中国区状态页 - 查看 状态.capgo.com.cn 确认是否存在正在发生的故障或性能下降
5. 查看日志 - 使用 npx @capgo/cli@latest app debug 来检查错误信息
6. 测试更新 - 尝试上传新 bundle 并监控下载过程
7. 联系支持 - 如果问题仍然存在，请联系我们： support@capgo.app 或加入我们的 Discord 社区 获取帮助

注意

请务必使用 .cn 域名 (updater.capgo.com.cn)，在进行中国区配置时，请勿使用标准的国际域名。

下一步

• 了解 更新行为 自定义更新的应用时机
• 探索 通道 管理不同的发布渠道
• 查看 加密 保障更新的安全

继续阅读：在中国使用 Capgo

如果你正在使用 在中国使用 Capgo 要规划 live update 的交付，请将其与 Capgo Live Updates 用于 Capgo Live Updates 中的产品工作流， 概览 用于 Overview 中的实现细节， 功能 用于 Features 中的实现细节， 更新行为 有关 Update Behavior 中的实现细节，请参阅 更新类型 关于 Update Types 中的实现细节。