跳转到正文

在中国使用 Capgo

如果您要将应用部署给中国用户,需要配置 Capgo 使用区域性的 OST(对象存储技术)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

各 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 配置并确定要应用哪些更新

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

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

在中国大陆,跨境延迟通常较高。请保留较高的 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',
},
},
};

我们 强烈建议 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 上传新的 bundle:

    终端窗口
    npx @capgo/cli@latest bundle upload --channel=production
  2. 在中国境内的测试设备上安装您的应用

  3. 监控更新过程:

    终端窗口
    npx @capgo/cli@latest app debug
  4. 检查更新是否从中国 OST URL 下载

如果您的应用同时服务中国境内和境外的用户,可以为全球所有用户使用中国域名配置。 updater.capgo.com.cn 该域名通过阿里云 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 解析速度很快,因此性能差异极小,不会明显影响用户体验。

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

  • 构建具有不同配置的独立应用变体
  • 使用基于环境的配置动态设置 URL
  • 为不同地区创建不同的发布渠道

如果您需要多区域部署策略方面的帮助,请通过以下方式联系我们: 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 社区 获取协助
  • 了解 更新行为 自定义更新应用时机
  • 探索 通道 管理不同的发布轨道
  • 查看 加密 保护您的更新安全

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