使用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 file
• 统计URL: https://updater.capgo.com.cn/stats - 用于将分析和使用统计数据报告回 Capgo
• 频道URL: https://updater.capgo.com.cn/channel_self - 用于检索频道配置并确定哪些更新需要应用

提示

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

中国的推荐设置

增加 __CAPGO_KEEP_0__ 响应超时

Increase API Response Timeout

The Capgo 升级插件在 API 调用时会中断 responseTimeout 当超出 (值以秒为单位) 秒)。在 Capgo 前面的 Edge 基础设施也将大约 秒 视为某些路径的失败预算。

在中国大陆，跨境延迟往往更高。保持较高的 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 为所有用户提供域名简化您的部署并确保所有地区的更新行为一致。您不需要单独的构建或环境基于的配置。中国以外的小性能折衷通常值得简化部署。

Alternative: Region-Specific Configurations

如果您希望针对每个地区优化不同，请考虑以下选项:

• 为每个地区构建不同的应用程序版本并使用不同的配置
• 使用环境配置动态设置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. 检查中国状态页面 - 检查 状态.capgo.com.cn 状态页面
5. 查看日志 - 使用 npx @capgo/cli@latest app debug 检查错误消息
6. 测试更新 尝试上传新包并监控下载过程
7. 联系支持 如果问题持续存在，请联系我们至 support@capgo.app 或加入我们的 Discord社区 获取帮助

注意

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

下一步

• 下一步 了解 更新行为
• 以自定义更新应用时的方式 探索 频道
• 区域：Capgo解决方案营销页面。角色：短的UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`solutions_white_label_visual_cell2_value`（解决方案白标签视觉单元2值）。 管理不同发布轨道的方式 为了确保您的更新

继续使用Capgo在中国

如果您正在使用 继续使用Capgo在中国 为了计划实时更新的交付，连接它到 Capgo实时更新 for the product workflow in Capgo Live Updates, 为__CAPGO_KEEP_0__实时更新中的产品工作流 概览 概览中的实现细节 特性中的实现细节 更新行为 查看更新行为的实现细节 更新类型 查看更新类型的实现细节