设置

想更精细地控制更新系统，可以用以下设置进行配置：

提示

若在 capacitor.config 文件中更改了这些设置，生产环境的应用需要同步平台并发布到应用商店才能生效。

注意

需要 Capgo Cloud 的欧盟数据驻留？请设置 updateUrl 改为 https://plugin.eu.capgo.app/updates, statsUrl 改为 https://plugin.eu.capgo.app/stats，以及 channelUrl 改为 https://plugin.eu.capgo.app/channel_self。请参阅 数据位置.

若要使用自定义主机名： updateUrl, statsUrl，以及 channelUrl，请参阅 自定义域名设置.

allowModifyUrl

允许插件从 JavaScript 端动态修改 updateUrl、statsUrl 和 channelUrl。

支持 Android、iOS 和 Electron。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "allowModifyUrl": true
    }
  }
}

appId

在配置中设置应用的 appId。

支持 Android、iOS 和 Electron。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "appId": "com.example.app"
    }
  }
}

appReadyTimeout

配置原生插件在判定更新“失败”前需等待的毫秒数。

支持 Android、iOS 和 Electron。

默认值： 10000 （10 秒）

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "appReadyTimeout": 1000
    }
  }
}

autoDeleteFailed

配置插件是否应自动删除失败的 bundle。

支持 Android、iOS 和 Electron。

默认值： true

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "autoDeleteFailed": false
    }
  }
}

autoDeletePrevious

配置插件是否应在更新成功后自动删除旧的 bundle。

支持 Android、iOS 和 Electron。

默认值： true

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "autoDeletePrevious": false
    }
  }
}

autoSplashscreen

使用 instant apply 模式时必填（"atInstall", "onLaunch"，或 "always"），包括已弃用的 directUpdate 值。请安装 @capacitor/splash-screen 并设置 launchAutoHide: false。 启用后，插件会在更新应用完成后或无需更新时自动隐藏 splashscreen。 这样你就无需手动监听 appReady 事件并调用 SplashScreen.hide() 了。

支持 Android 和 iOS。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": "atInstall",
      "autoSplashscreen": true
    },
    "SplashScreen": {
      "launchAutoHide": false
    }
  }
}

autoUpdate

配置插件检查、下载及应用 Live Update 的方式。 当应用进入前台时，以及应用保持打开状态时的定时器触发时，插件会检查更新。 periodCheckDelay 控制该定时器间隔。 为保持向后兼容，仍支持布尔值： true 等同于 "atBackground" 以及 false 等同于 "off"。 字符串值将合并之前的 Auto Update 和 Direct Update 配置。

选项：

• "off" 或 false: 禁用自动检查更新
• "atBackground" 或 true: 每次进入前台时自动检查并下载，并在下次应用进入后台时应用更新
• "atInstall": 仅在全新安装或通过原生应用商店更新后立即应用；否则使用 "atBackground" 行为
• "onLaunch": 仅在应用从被终止状态进入前台（冷启动）时立即应用。首次检查后，回退到 "atBackground" 行为
• "always": 每次进入前台时检查，并在有可用更新时立即应用
• "onlyDownload": 自动检查并下载，触发 updateAvailable, 且绝不会自动设置下一个 bundle 或应用更新

即时应用模式 ("atInstall", "onLaunch", "always") 会在用户等待时应用。使用 npx @capgo/cli@latest bundle upload --delta 进行 upload，这样仅下载变更的文件。上传完整的 zip 包会降低用户体验。在 Android 和 iOS 上，这些模式需要 autoSplashscreen: true 以及 @capacitor/splash-screen 配合 launchAutoHide: false.

支持 Android、iOS 和 Electron。

默认值： "atBackground" (true 仍然有效)

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": "onlyDownload"
    }
  }
}

channelUrl

配置用于 channel 操作的 URL / 端点。

支持 Android、iOS 和 Electron。

默认值： https://plugin.capgo.app/channel_self

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "channelUrl": "https://example.com/api/channel"
    }
  }
}

defaultChannel

在配置中设置应用的默认 channel。区分大小写。 此设置将覆盖云端设置的默认 channel，但仍会遵循云端进行的覆盖操作。

支持 Android、iOS 和 Electron。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "defaultChannel": "production"
    }
  }
}

directUpdate

已弃用。请改用 autoUpdate 字符串模式： "atInstall", "onLaunch"，或 "always". This option remains supported for existing apps. Instant apply should be uploaded with --delta 以确保更新不会影响用户体验。这些模式需要 autoSplashscreen: true 以及 @capacitor/splash-screen 配合 launchAutoHide: false.

选项：

• false: 绝不直接更新
• 'atInstall': 同上 autoUpdate: "atInstall"
• 'onLaunch': 同上 autoUpdate: "onLaunch"
• 'always': 同上 autoUpdate: "always"
• true: (已弃用) 同上 "always" 用于向后兼容

支持 Android、iOS 和 Electron。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "autoUpdate": "atInstall"
    }
  }
}

disableJSLogging

禁用插件的 JavaScript 日志记录。如果设为 true，插件将不会向 JavaScript 控制台输出日志，仅保留原生日志。

支持 Android、iOS 和 Electron。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "disableJSLogging": true
    }
  }
}

keepUrlPathAfterReload

配置插件在 reload 后保留 URL 路径。

注意

当触发 reload 时，‘window.history’ 会被清空。

支持 Android、iOS 和 Electron。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "keepUrlPathAfterReload": true
    }
  }
}

periodCheckDelay

配置周期性更新检查的延迟时间。单位为秒。 不能低于 600 秒（10 分钟）。

支持 Android、iOS 和 Electron。

默认值： 600 (10 分钟)

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "periodCheckDelay": 600 // (10 minutes)
    }
  }
}

publicKey

配置用于 Version 2 端到端 live update 加密的公钥。

支持 Android、iOS 和 Electron。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "publicKey": "YOUR_PUBLIC_KEY"
    }
  }
}

注意

publicKey 用于配置 Encryption V2，且必须与上传时使用的私钥一致。对于 Delta 更新，请使用 V2 加密并启用部分加密；如果组织要求每次上传都必须加密，请启用 encrypted-bundle enforcement。请勿仅依赖 publicKey 它作为防止未加密 Delta 发布的服务端策略。

resetWhenUpdate

当设备安装较新的原生应用 bundle 时，自动删除之前下载的 bundle。

支持 Android、iOS 和 Electron。

默认值： true

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "resetWhenUpdate": false
    }
  }
}

responseTimeout

配置原生插件在判定 API 超时前等待的毫秒数。

支持 Android、iOS 和 Electron。

默认值： 20 (20 秒)

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "responseTimeout": 10 // (10 seconds)
    }
  }
}

shakeMenu

启用摇一摇手势以显示更新菜单，用于调试或测试。

支持 Android、iOS 和 Electron。

默认值： false

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "shakeMenu": true
    }
  }
}

statsUrl

配置用于发送更新统计数据的 URL 或端点。

Available on Android, iOS, and Electron. Set to "" to disable explicit stats reporting through /stats.

禁用 statsUrl 并不会禁用所有的 Capgo 设备存储。如果 updateUrl 保持启用状态， /updates 仍会存储用于提供更新和统计 MAU 所需的计费 MAU 行、设备清单以及更新决策事件数据。详情请参阅 合规性 以获取字段级明细。

默认值： https://plugin.capgo.app/stats

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "statsUrl": "https://example.com/api/stats"
    }
  }
}

updateUrl

配置用于发送更新检查请求的 URL 或端点。

支持 Android、iOS 和 Electron。

默认值： https://plugin.capgo.app/updates

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "updateUrl": "https://example.com/api/auto_update"
    }
  }
}

version

配置 App 的当前版本。该版本将用于首次更新请求。 如果未设置，插件将从原生 code 获取版本号。

支持 Android、iOS 和 Electron。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "version": "1.0.0"
    }
  }
}

开发设置

localApi

配置 CLI 以使用本地 api 进行测试。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localApi": "http://localhost:54321/functions/v1"
    }
  }
}

localApiFiles

配置 CLI 以使用本地文件 api 进行测试。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localApiFiles": "http://localhost:54321/functions/v1/files"
    }
  }
}

localHost

配置 CLI 以使用本地服务器进行测试，或使用自托管的更新服务器。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localHost": "http://localhost:5173"
    }
  }
}

localSupa

配置 CLI 以使用本地服务器进行测试，或使用自托管的更新服务器。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localSupa": "http://localhost:54321"
    }
  }
}

localSupaAnon

配置 CLI 以使用本地服务器进行测试。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localSupaAnon": "YOUR_LOCAL_ANON_KEY"
    }
  }
}

localWebHost

配置 CLI 以使用本地服务器进行测试，或使用自托管的更新服务器。

默认值： undefined

capacitor.config.json

{
  "plugins": {
    "CapacitorUpdater": {
      "localWebHost": "http://localhost:5173"
    }
  }
}

提示

还有更多设置可在 Capgo Web 应用 中按渠道配置，无需发布原生应用。

从设置继续

如果你正在使用 设置 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。