开始使用

安装

npm

npm install @capgo/capacitor-updater
npx cap sync

yarn

yarn add @capgo/capacitor-updater
npx cap sync

pnpm

pnpm add @capgo/capacitor-updater
npx cap sync

bun

bun add @capgo/capacitor-updater
npx cap sync

快速入门

对于大多数用户,我们建议遵循主快速入门指南,它涵盖了插件安装和 Capgo 云集成。

本入门指南专注于技术插件细节,适合想要了解底层机制或实现自托管更新的高级用户。

概述

Capacitor Updater 插件为您的 Capacitor 应用启用空中下载 (OTA) 更新。这允许您在不经过应用商店审核的情况下向应用推送更新。

工作原理

1. Bundle 下载: 插件下载更新 bundle(包含 Web 资源的 ZIP 文件)
2. 解压: Bundle 被解压到设备的存储中
3. 热重载: 应用切换到新 bundle,无需重启
4. 回退: 如果更新失败,应用会回退到之前的工作版本

使用模式

1. 自动更新模式(推荐)

使用插件的最简单方式,具有自动更新管理:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 插件自动处理所有事情
// 在 capacitor.config.ts 中配置

添加到您的 capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. 手动模式

对更新过程进行高级控制:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 下载更新
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// 设置 bundle(将在下次应用启动时使用)
await CapacitorUpdater.set({
  id: bundle.id
});

// 或立即重新加载
await CapacitorUpdater.reload();

平台配置

iOS

无需额外配置。插件开箱即用。

Android

无需额外配置。插件开箱即用。

基本 API 使用

下载更新

import { CapacitorUpdater } from '@capgo/capacitor-updater';

const bundle = await CapacitorUpdater.download({
  url: 'https://example.com/update.zip',
  version: '1.0.1'
});

console.log('已下载 bundle:', bundle.id);

设置活动 Bundle

// 设置在下次应用启动时使用的 bundle
await CapacitorUpdater.set({
  id: bundle.id
});

使用新 Bundle 重新加载

// 立即使用新 bundle 重新加载应用
await CapacitorUpdater.reload();

列出 Bundles

const { bundles } = await CapacitorUpdater.list();
console.log('可用的 bundles:', bundles);

删除 Bundle

await CapacitorUpdater.delete({
  id: 'bundle-id'
});

获取当前 Bundle

const { bundle } = await CapacitorUpdater.current();
console.log('当前 bundle:', bundle.version);

事件监听器

监听更新事件:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 监听下载进度
CapacitorUpdater.addListener('download', (info) => {
  console.log('下载进度:', info.percent);
});

// 监听下载完成
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('下载完成:', bundle.version);
});

// 监听更新失败
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('更新失败:', error);
});

// 监听成功更新
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('更新可用:', info.version);
});

配置选项

在您的 capacitor.config.ts 中配置插件:

{
  plugins: {
    CapacitorUpdater: {
      // 自动更新设置
      autoUpdate: true,
      updateUrl: 'https://api.example.com/updates',

      // 更新行为
      resetWhenUpdate: true,
      directUpdate: false,

      // 版本设置
      version: '1.0.0',

      // 安全性
      allowModifyUrl: false,

      // 统计收集
      statsUrl: 'https://api.example.com/stats',

      // 频道(用于 Capgo 云)
      defaultChannel: 'production'
    }
  }
}

集成模式

使用 Capgo 云

最简单的入门方式:

// 安装 Capgo CLI
npm install -g @capgo/cli

// 登录 Capgo
npx @capgo/cli login

// 上传您的第一个 bundle
npx @capgo/cli bundle upload

// 插件从 Capgo 云自动更新

详情请参阅主快速入门指南。

自托管更新

托管您自己的更新服务器:

// 配置您的更新端点
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

您的服务器应返回:

{
  "version": "1.0.1",
  "url": "https://your-server.com/updates/1.0.1.zip"
}

完整详情请参阅自托管模式。

手动更新流程

完全控制更新:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

async function checkAndUpdate() {
  // 从您的服务器检查更新
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // 下载更新
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // 通知 bundle 已准备好
  await CapacitorUpdater.notifyAppReady();

  // 设置为下一版本
  await CapacitorUpdater.set({ id: bundle.id });

  // 准备好时重新加载
  await CapacitorUpdater.reload();
}

最佳实践

• 当应用成功加载时,始终调用 notifyAppReady()
• 在推送到生产环境之前彻底测试更新
• 为网络故障实现适当的错误处理
• 一致地使用版本号
• 保持 bundle 大小小以加快下载速度
• 监控更新成功率

后续步骤

• 插件 API 参考 - 完整 API 文档
• 插件设置 - 所有配置选项
• 事件 - 可用的更新事件
• 自托管模式 - 运行您自己的更新服务器
• 本地开发 - 本地测试更新
• 调试 - 故障排除指南

支持

• 已知问题 - 常见问题和解决方案
• GitHub 讨论 - 社区支持
• Discord - 实时聊天