使用Capgo在中国

If you’re deploying your app to users in China, you’ll need to configure Capgo to use regional OST (Object Storage Technology) URLs to ensure reliable and fast updates.

为什么使用中国特定的 URL?

Due to network infrastructure and regulations in China (the Great Firewall), direct connections to international servers can be slow or unreliable. Capgo provides dedicated OST URLs with data located in Hong Kong to minimize latency and ensure your users receive updates as quickly and reliably as possible.

配置

To configure Capgo for China, you need to set three specific URLs in your Capacitor configuration file. These URLs point to Capgo’s Hong Kong-based infrastructure.

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

2. 将以下配置添加到 CapacitorUpdater 插件部分：

   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. 重建您的应用以应用更改：

   npm run build
   npx cap sync

配置详细信息

以下是每个 URL 的作用：

• updateUrl: https://updater.capgo.com.cn/updates - 用于检查并下载您的应用可用的更新
• 统计URL: https://updater.capgo.com.cn/stats - 用于将分析和使用统计数据报告回 Capgo
• 频道URL: https://updater.capgo.com.cn/channel_self - 用于检索频道配置并确定哪些更新需要应用

提示

所有三个 URL 必须同时配置才能确保 Capgo 在中国的更新器的完整功能

中国的推荐设置

由于中国防火墙的网络性能限制，我们对在中国大陆部署的应用有特定的推荐:

增加 API 响应超时

The Capgo 升级插件在 API 调用时会中断 responseTimeout 超过 (值以秒为单位) 秒). Edge infrastructure in front of Capgo also treats about 秒 视为某些路径的失败预算。

在中国大陆，跨境延迟往往更高。保持较高的 responseTimeout 以便插件有足够的时间完成更新检查和下载，而不是早期失败： 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',
    },
  },
};

protectedTokens

建议使用 responseTimeout: 60 (or higher) for China deployments. A low timeout does not make updates faster — it only causes the plugin to give up while the request may still succeed on Capgo’s side.

使用后台更新

我们 强烈建议使用 autoUpdate: 'atBackground' 中国地区的应用程序。中国地区的网络连接性能低于其他地区，实时应用模式可能会导致下载中断或缓慢，给用户带来糟糕的体验。

相反，使用默认的更新行为，更新在后台下载并在应用程序后台或重启时应用。这为您的用户提供了更可靠的体验。

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',
    },
  },
};

注意

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

完整配置示例

以下是中国地区部署应用程序的推荐设置的完整示例：

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：

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

2. 在中国测试设备上安装您的应用程序

3. 监控更新过程：

   npx @capgo/cli@latest app debug

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

注意

更新行为和时间与标准Capgo配置相同。请参阅 更新行为 文档以了解如何和何时应用更新。

多区域部署

如果您的应用同时服务于中国和全球用户，您可以使用中国域名配置为全球用户。由于阿里巴巴DNS基础设施能够全局解析域名，因此它在中国和全球其他地方都可访问。 updater.capgo.com.cn 多区域部署

使用全球性中文域名

中国域名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',
    },
  },
};

此单个配置将适用于：

• 中国大陆地区的用户（使用香港基础设施）
• 非中国地区的用户（通过阿里巴巴DNS访问相同的基础设施）

性能考虑：

虽然 .cn 域名通过阿里巴巴DNS在全球解析，且在全球各地都能正常工作，但是在中国以外的用户相对于标准域名（api.capgo.app), which is resolved directly by Cloudflare where our backend is hosted. However, DNS resolution is fast, so the performance difference is minimal and won’t significantly impact the user experience.

提示

使用 .cn 域名

为所有用户简化部署并确保所有地区的更新行为一致。您不需要单独的构建或环境配置。中国以外的小性能折衷通常值得简化部署。

区域特定配置

• 如果您希望针对每个区域进行优化，
• 构建不同配置的应用程序
• 使用环境配置动态设置URL

为不同地区创建不同的发布频道 support@capgo.app support@__CAPGO_KEEP_0__.app Discord社区 获取帮助。

监控中国基础设施

您可以在Capgo的中国特定端点上监控健康和状态 status.capgo.com.cn.

使用此页面检查中国OST URL的故障、延迟和运行时间，Troubleshooting

故障排除

1. 如果您在中国遇到更新问题： 验证您的配置项： capacitor.config.ts
2. 提高 responseTimeout - 在中国至少使用 60 秒以免插件在更新请求仍在飞行时中止
3. 检查网络连接 - 确保您的设备可以访问 updater.capgo.com.cn 域名
4. 检查中国状态页面 - 检查 状态.capgo.com.cn 是否有任何正在进行中的事件或性能下降
5. 查看日志 - 使用 npx @capgo/cli@latest app debug 检查错误消息
6. 测试更新 试着上传一个新的包并监控下载过程
7. 联系支持 如果问题持续存在，请联系我们 support@capgo.app 或加入我们的 Discord社区 获取帮助

注意

确保使用 .cn 域名（updater.capgo.com.cn")和中国配置时的标准国际域名不同。

下一步

• 下一步 了解 更新行为
• 以自定义更新应用时 探索 渠道
• Capgo 发布渠道功能名称 Capgo 解决方案营销页面 为了确保您的更新

继续使用Capgo在中国

如果您正在使用 使用Capgo在中国 为了计划实时更新的交付,将其与 Capgo实时更新 为Capgo实时更新中的产品工作流程 概览 概览中的实现细节 特性 特性中的实现细节 更新行为 为更新行为的实现细节,并 更新类型 为更新类型的实现细节.