入门

安装

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 更新程序插件可为您的 Capacitor 应用程序启用无线 (OTA) 更新。这使您可以将更新推送到您的应用程序，而无需经过应用程序商店评论。

它是如何工作的

1. 捆绑包下载：插件下载更新捆绑包（包含您的网络资产的 ZIP 文件）
2. 提取：捆绑包被提取到设备的存储中
3. 热重载：应用程序无需重新启动即可切换到新捆绑包
4. 回退：如果更新失败，应用程序将恢复到之前的工作版本

使用模式

1.自动更新模式（推荐）

使用具有自动更新管理功能的插件的最简单方法：

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

// Plugin handles everything automatically
// Configure in 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';

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

// Set the bundle (will be used on next app start)
await CapacitorUpdater.set({
  id: bundle.id
});

// Or reload immediately
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('Downloaded bundle:', bundle.id);

设置活动捆绑包

// Set bundle to be used on next app start
await CapacitorUpdater.set({
  id: bundle.id
});

重新加载新包

// Reload app immediately with new bundle
await CapacitorUpdater.reload();

列出捆绑包

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

删除捆绑包

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

获取当前捆绑包

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

事件监听器

监听更新事件：

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

// Listen for download progress
CapacitorUpdater.addListener('download', (info) => {
  console.log('Download progress:', info.percent);
});

// Listen for download completion
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download complete:', bundle.version);
});

// Listen for update failures
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Update failed:', error);
});

// Listen for successful updates
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.version);
});

配置选项

在 capacitor.config.ts 中配置插件：

{
  plugins: {
    CapacitorUpdater: {
      // Auto-update settings
      autoUpdate: true,
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,
      directUpdate: false,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

      // Stats collection
      statsUrl: 'https://api.example.com/stats',

      // Channel (for Capgo cloud)
      defaultChannel: 'production'
    }
  }
}

集成模式

使用 Capgo 云

最简单的入门方法：

// Install the Capgo CLI
npm install -g @capgo/cli

// Login to Capgo
npx @capgo/cli login

// Upload your first bundle
npx @capgo/cli bundle upload

// The plugin auto-updates from Capgo cloud

有关详细信息，请参阅主要快速入门指南。

自托管更新

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

// Configure your update endpoint
{
  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() {
  // Check for updates from your server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Download the update
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notify bundle is ready
  await CapacitorUpdater.notifyAppReady();

  // Set as next version
  await CapacitorUpdater.set({ id: bundle.id });

  // Reload when ready
  await CapacitorUpdater.reload();
}

最佳实践

• 当您的应用成功加载时，始终调用 notifyAppReady()
• 在投入生产之前彻底测试更新
• 对网络故障实施适当的错误处理
• 一致地使用版本号
• 保持较小的捆绑包大小以加快下载速度
• 监控更新成功率

后续步骤- 插件 API 参考 - 完整的 API 文档

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

支持

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