在中国使用 Capgo
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
如果您要将应用部署给中国用户,需要配置 Capgo 使用区域性的 OST(对象存储技术)URL,以确保更新可靠且快速。
为什么使用中国专用 URL?
标题为“为什么使用中国专用 URL?”的章节由于中国的网络基础设施和法规(即“防火长城”),直接连接国际服务器可能缓慢或不可靠。Capgo 提供专用的 OST URL,数据位于香港,以最小化延迟并确保您的用户尽可能快速、可靠地接收更新。
配置
“配置” 章节要为 Capgo 配置中国区域,您需要在 Capacitor 配置文件中设置三个特定的 URL。这些 URL 指向 Capgo 位于香港的基础设施。
-
打开你的
capacitor.config.ts文件 -
将以下配置添加到
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; -
重新构建应用以应用更改:
终端窗口 npm run buildnpx 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)造成的网络性能限制,我们针对部署在中国大陆的应用有以下建议:
调高 API 响应超时时间
标题为“调高 API 响应超时时间”的章节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 后,您可以验证更新是否正常工作:
-
向 Capgo 上传新的 bundle:
终端窗口 npx @capgo/cli@latest bundle upload --channel=production -
在中国境内的测试设备上安装您的应用
-
监控更新过程:
终端窗口 npx @capgo/cli@latest app debug -
检查更新是否从中国 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 的事件、延迟和正常运行时间。
故障排除
“故障排除”章节如果您在中国遇到更新问题:
- 验证您的配置 - 仔细检查您的 中是否正确设置了所有三个 URL
capacitor.config.ts - 提高
responseTimeout- 至少使用60秒,位于中国,以便插件在更新请求仍在处理中时不会中止 - 检查网络连接 - 确保您的设备可以访问
updater.capgo.com.cn域名 - 查看中国区状态页 - 查看 状态.capgo.com.cn 确认是否存在正在发生的故障或性能下降
- 查看日志 - 使用
npx @capgo/cli@latest app debug来检查错误信息 - 测试更新 - 尝试上传新 bundle 并监控下载过程
- 联系支持 - 如果问题仍然存在,请联系我们: support@capgo.app 或加入我们的 Discord 社区 获取协助
下一步
“后续步骤”章节继续了解在中国使用 Capgo
章节标题:“从在中国使用 Capgo 继续”如果你正在使用 在中国使用 Capgo 要规划 live update 的交付,请将其与 Capgo Live Update 用于 Capgo Live Updates 中的产品工作流, 概览 用于 Overview 中的实现细节, 功能 用于 Features 中的实现细节, 更新行为 有关 Update Behavior 中的实现细节,请参阅 更新类型 关于 Update Types 中的实现细节。