使用Capgo在中国

如果您正在将应用程序部署到中国用户，您需要配置Capgo以使用区域 OST（对象存储技术）URL，以确保可靠和快速的更新。

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

由于中国的网络基础设施和监管（长城防火墙），直接连接到国际服务器可能会很慢或不可靠。Capgo提供了专用的 OST URL，数据位于香港，以最小化延迟并确保您的用户尽可能快和可靠地接收更新。

配置

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

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

标题为“配置详细信息”的部分

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）而言，性能略有下降，因为标准域名直接由Cloudflare解析，而我们的后端服务器位于此处。然而，DNS解析速度快，性能差异很小，几乎不会对用户体验产生重大影响。

提示

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

备选方案：区域特定配置

如果您希望针对每个区域进行优化，

• 构建不同配置的应用程序
• 使用环境配置动态设置URL
• 为不同地区创建不同的发布频道

如果您需要帮助解决多地区部署策略，请联系我们 support@capgo.app 或加入我们的 Discord社区 获取帮助。

监控中国基础设施

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

使用此页面检查中国OST URL的延迟、可用性和故障前，Troubleshooting

故障排除

1. 如果您在中国遇到更新问题： 验证您的配置项： capacitor.config.ts
2. 提高 responseTimeout - 使用至少 60 秒在中国，以便插件在更新请求仍在飞行时不会中止
3. 检查网络连接 - 确保您的设备可以访问 updater.capgo.com.cn 域名
4. 检查中国状态页面 - 检查 status.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实时更新中 概览 概览 功能 功能 更新行为 更新行为的实现细节 更新类型 更新类型的实现细节