自定义域名

使用您自己的主机名，例如 updates.example.com，用于您应用的 Live Update API 请求，同时由 Capgo 继续管理您的 channels、bundles 和 rollouts。

自定义域名适用于 企业版方案。组织管理员可以在 Console 中添加 Live Update API 主机名，发布提供的 DNS 记录，并检查其激活状态。

1. 添加您的自定义域名

1. 打开 Capgo 控制台 并选择您的组织。
2. 前往 设置 → 组织 → 常规 并找到 自定义域名。您需要拥有修改组织设置的权限以及有效的 Enterprise 方案才能添加域名。
3. 输入主机名，例如 updates.example.com，且不能包含 https://、路径或通配符。
4. 点击 添加域名。Console 会显示需要发布的 DNS 记录以及 等待验证 状态。

每个组织可以配置一个 Live Updates API 主机名。您必须拥有对其 DNS 记录的编辑权限。

如果 自定义域名 选项不可用，请联系您的 Enterprise 支持人员或发送邮件至 support@capgo.app 并提供您的组织、App ID、所需主机名及 DNS 服务商。此外，如果您需要 特定的数据驻留区域 或用于 bundle 下载的自定义主机名，请在设置前联系支持团队。

注意

仅添加 DNS 记录无法激活自定义域名。还必须配置路由和 HTTPS。在更改生产环境配置前，请等待 Console 显示 运行中，或等待技术支持确认已完成人工配置激活。

2. 配置 DNS 并验证 HTTPS

在您的 DNS 提供商处，添加 Console 中显示或由技术支持提供的记录。请准确复制记录类型、名称和值，包括 CNAME 以及任何所有权或证书验证用的 TXT 记录。点击 Console 中的值即可复制。如果您使用 Cloudflare DNS，请保持 CNAME 为 仅 DNS (DNS only) 除非技术支持确认需要其他设置。

请使用提供的目标地址，不要盲目认为指向 plugin.capgo.app 的 CNAME 就足够了。在域名使用期间，请务必保留这些 DNS 记录。

DNS 生效后，点击 刷新状态. 控制台显示 运行中 仅在主机名及其 HTTPS 证书均处于激活状态时；随后将提供 复制 updater 配置. 如需人工协助配置，请联系支持团队确认激活状态。您也可以通过以下命令检查 DNS 和 TLS 连接性：

dig updates.example.com
curl -v https://updates.example.com/updates

替换 updates.example.com 使用您配置的主机名。 curl 命令会检查 DNS、TLS 和 HTTP 连接性；向 /updates 发送的 GET 请求并非有效的更新检查，可能会返回 API 错误。请在步骤 4 中通过 native test build 验证实际的更新流程。

3. 配置 updater

域名生效后，请从 Console 复制 updater 配置，并将这三个 URL 合并到 capacitor.config.ts。对于使用标准 Capgo API 路径配置的主机名，请使用：

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://updates.example.com/updates',
      statsUrl: 'https://updates.example.com/stats',
      channelUrl: 'https://updates.example.com/channel_self',
    },
  },
};

export default config;

请将示例 URL 替换为 Console 中显示的准确 URL 或经由 support 确认的 URL。请保留您现有的 app 设置和其他 plugin 选项。

设置项	用途
updateUrl	检查是否有可用的 bundle。
statsUrl	报告更新统计数据。
channelUrl	处理设备的 channel 操作。

注意

这些设置会更改 API 端点。Bundle 下载使用的是更新服务器返回的 URL，因此更改这些设置不会自动为 bundle 下载启用自定义域名。请另行联系支持团队确认下载主机的相关要求。

4. 同步、测试与发布

将配置同步到您的原生项目中：

npx cap sync

构建并安装原生测试版本，然后：

1. 上传一个测试 bundle 到 测试 channel 使用您常规的 Capgo 工作流。
2. 检查原生设备 logs，以验证更新请求是否已到达您的自定义 hostname，并确认 bundle 是否下载并安装成功。
3. 如果您的应用使用了更新统计功能，请确认 Console 和测试 channel 操作中已显示相关统计数据。
4. 通过您常规的应用商店分发流程发布新的 Native Build 版本。

注意

这些更改 capacitor.config.ts 需要 Native Build 支持。仅上传 JavaScript bundle 无法将这些设置应用到现有的 iOS 和 Android 安装版本中。用户只有在安装了新的 Native 版本后，才会开始使用自定义域名。

旧的 Native 安装版本会继续使用其配置的端点 URL，直到用户安装了新的 Native 版本。Updater 的默认主机名为 plugin.capgo.app，由 Capgo 进行管理。如果您正从另一个受控的自定义主机名迁移，请保持其 DNS 记录和服务处于活跃状态，直到相关用户完成迁移。Channels、bundle uploads 和 rollbacks 将继续使用您正常的 Capgo Console 和 CLI 工作流。

故障排除

要移除域名，请使用 移除域名 → 确认移除 在 Organization 设置中。请先发布一个使用替换端点的 Native App 版本并允许用户迁移：旧版本将无法通过已移除的主机名进行访问。请在删除 Organization 之前先移除其域名。

• DNS 解析失败： 请核对记录名称和目标值是否与支持团队提供的一致，并向您的 DNS 服务商确认解析是否已生效。
• HTTPS 失败： 在发布 Native Build 之前，请联系支持团队检查主机名激活和证书配置情况。
• 请求仍在使用 plugin.capgo.app: 请确认这三个 URL，运行 npx cap sync，重新构建并安装新的 Native 版本。
• Bundle 下载使用了其他主机名： 更新响应中会提供下载 URL。如需自定义 Bundle 交付方式，请咨询支持团队，或查看 自定义存储 如果您想自行管理 Bundle 存储。
• HTTPS 正常但更新失败： 将 App ID、channel、native version、请求时间戳以及 native logs 提供给 Capgo 支持团队.

查看 更新器设置 以获取完整的配置参考，以及 数据存储位置 了解各区域 endpoint 的要求。