快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-updater` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm

bun add @capgo/capacitor-updater
bunx cap sync

yarn

yarn add @capgo/capacitor-updater
bunx cap sync

pnpm

pnpm add @capgo/capacitor-updater
bunx cap sync

bun

bun add @capgo/capacitor-updater
bunx cap sync

快速入门

对于大多数用户，我们建议参考 主要的 Quickstart 指南 该指南涵盖了插件安装以及 Capgo 云端集成。

本入门指南重点介绍插件的技术细节，适合希望了解底层机制或实现自托管更新的高级用户。

概览

Capacitor Updater 插件可为你的 Capacitor 应用提供 OTA 更新。这样，你无需经过应用商店审核即可向应用推送更新。

工作原理

1. Bundle 下载: 插件会下载更新 Bundle（包含 Web 资源的 ZIP 文件）
2. 解压: Bundle 会被解压到设备的存储空间中
3. 热重载: 应用无需重启即可切换到新的 Bundle
4. 回退: 如果更新失败，应用会回退到上一个正常工作的版本

使用模式

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

使用该插件进行自动更新管理的最简单方式：

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

// Plugin handles everything automatically
// Configure in capacitor.config.ts

添加到你的 capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      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);

设置当前 Bundle

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

使用新 Bundle 重载

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

列出 Bundle

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

删除 Bundle

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

获取当前 Bundle

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: 'atBackground',
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

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

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

集成模式

使用 Capgo Cloud

最简单的入门方式：

// Install the Capgo CLI
bun add -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

请参阅 主 Quickstart 指南 详情。

自托管更新

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

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      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() 当您的应用成功加载时
• 在推送到生产环境前请彻底测试更新
• 针对网络故障实现完善的错误处理机制
• 保持版本号的一致性
• 控制 bundle 体积以实现更快的下载速度
• 监控更新成功率

下一步

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

支持

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

从入门指南继续

如果你正在使用 快速入门 要规划原生插件工作，请将其与 使用 @capgo/capacitor-updater 用于“使用 @capgo/capacitor-updater”中的原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。