Hotfix 前端热修复

:::danger ⚠️ 组件已废弃（Deprecated） @rydeen/hotfix 已进入废弃状态，未来不再维护，仅在当前版本中作为过渡方案保留。
请在新项目或正在演进的项目中，优先使用 @rydeen/updater 组件（详见 @rydeen/updater），并逐步迁移现有基于 @rydeen/hotfix 的代码。 :::

@rydeen/hotfix 提供前端资源的 热修复与版本增量更新能力，需要配合 Capgo 的 @capgo/capacitor-updater 使用，实现版本检查、资源包下载、安装、定时检查与回滚等完整链路。

设计定位

• 与 Capgo 对齐：封装 Capgo Updater 的常用能力，统一事件回调与版本元数据结构。 +- 版本可观测：本地版本信息写入 @capacitor-rydeen/preferences，便于排查问题。
• 业务无感升级：支持静默检查与自动下载，业务只需订阅「有新版本」与「下载完成」等回调。

安装与依赖

npm install @rydeen/hotfix

Peer 依赖（需在业务项目中一并安装并完成 Capgo 集成）：

• @capgo/capacitor-updater
• @capacitor-rydeen/preferences
• @capacitor/app

核心概念

• VersionMetadata：服务端返回的版本元数据，描述是否有 App/资源更新、资源包版本号、校验信息等。
• PatchInfo：下载结果，包含本次 Bundle 信息、状态码、元数据等。
• HotfixOptions：热修复管理器的配置，包括更新模式、服务端地址、检查间隔、初始版本等。
• HotfixManage：热修复管理器，对外暴露版本检查、下载、安装、回滚等方法。

快速开始

import { HotfixManage, type HotfixOptions, type VersionMetadata } from '@rydeen/hotfix'

const options: HotfixOptions = {
  updateMode: 'static', // static / dynamic
  enable: true,
  autoCheck: true,
  checkDomain: 'https://your-server.com/version',
  downloadDomain: 'https://your-server.com/assets',
  intervalHours: 24,
  originVersion: {
    hasAppUpdate: false,
    hasAssetsUpdate: false,
    assetsVersion: '1.0.0',
    checksum: '',
  },
  updateAvailable: (bundle) => console.log('有新版本:', bundle.version),
  downloadComplete: (bundle) => console.log('下载完成:', bundle.version),
}

const hotfix = new HotfixManage(options)
await hotfix.registerEvents()
hotfix.checkVersionTimer() // 开启定时检查

// 非静默检查：适合弹窗确认
const meta: VersionMetadata = await hotfix.checkVersion(false)
if (meta.hasAssetsUpdate) {
  const patch = await hotfix.download(meta)
  await hotfix.upgrade(patch, true) // 立即生效
}

实战示例：门店终端静默更新

场景：门店一体机希望在非营业高峰期静默拉取前端补丁，避免影响收银体验。

import { HotfixManage } from '@rydeen/hotfix'

const hotfix = new HotfixManage({
  updateMode: 'dynamic',
  enable: true,
  autoCheck: true,
  checkDomain: 'https://update.your-domain.com/check',
  downloadDomain: 'https://update.your-domain.com/assets',
  intervalHours: 6,
  originVersion: {
    hasAppUpdate: false,
    hasAssetsUpdate: false,
    assetsVersion: '1.0.0',
    checksum: '',
  },
  downloadComplete: (bundle) => {
    console.log('[Hotfix] 资源下载完成:', bundle.version)
  },
})

export async function initHotfix() {
  await hotfix.registerEvents()
  hotfix.checkVersionTimer()
}

API 与类型参考

HotfixOptions

• updateMode：'static' | 'dynamic'，拉取版本信息的请求方式。
• enable：是否启用热更新。
• autoCheck：是否自动定时检查。
• checkDomain：检查更新接口地址。
• downloadDomain：资源包下载基础地址。
• statisticsDomain?：统计上报地址（可选）。
• intervalHours：自动检查间隔（小时）。
• originVersion：当前应用原始版本信息（VersionMetadata）。
• 各阶段事件回调：download?、noNeed?、updateAvailable?、downloadComplete?、updateFailed?、downloadFailed?、appReloaded?、appReady?。

主要方法

方法	签名	说明
构造函数	new HotfixManage(options: HotfixOptions)	仅保存配置，不自动拉取。
registerEvents	registerEvents(): Promise<void>	注册 Capgo 与 App 的监听，并调用 CapacitorUpdater.notifyAppReady()。
checkVersion	checkVersion(silence?: boolean): Promise<VersionMetadata>	检查新版本；silence 为 true 时若有资源更新会自动下载并升级。
download	download(cloudVersion: VersionMetadata): Promise<PatchInfo>	按 VersionMetadata 下载资源包。
upgrade	upgrade(upgradeData: PatchInfo, updateNow?: boolean): Promise<void>	应用已下载版本；updateNow 为 true 时立即切换，否则下次启动生效。
rollbackPrev	rollbackPrev(): Promise<void>	回滚到上一版本。
rollbackOrigin	rollbackOrigin(): Promise<void>	回滚到上次成功版本。
getDeviceId	getDeviceId(): Promise<string>	获取 Capgo 设备 ID。
getLocalVersion	getLocalVersion(): Promise<VersionMetadata>	从 Preferences 读取本地版本元数据。
setAutoCheck	setAutoCheck(autoCheck: boolean): void	设置是否自动检查。
setIntervalHours	setIntervalHours(hours: number): void	设置检查间隔。
checkVersionTimer	checkVersionTimer(): void	若 autoCheck 为 true，则按 intervalHours 定时执行 checkVersion()。

关键类型

• VersionMetadata

  • hasAppUpdate：是否有原生 App 更新。
  • hasAssetsUpdate：是否有前端资源更新。
  • assetsVersion：资源版本号。
  • newVersion?：App 新版本号。
  • filename?：资源文件名。
  • checksum：校验和。
  • sign?：签名信息（用于解析真实下载地址）。

• PatchInfo

  • hasUpdate：是否有可用更新。
  • status：BundleStatus，如 SUCCESS、ERROR、PENDING、DOWNLOADING。
  • message?：提示信息。
  • code：消息码。
  • data?：Capgo 的 BundleInfo。
  • metadata：对应的 VersionMetadata。

平台支持与注意事项

平台	说明
Android / iOS	支持，依赖 Capgo 与原生实现。
Electron	视 Capgo 对 Electron 的支持情况而定。
Web	不支持（无 Capgo 运行环境）。

• Capgo 前置：必须先正确集成 @capgo/capacitor-updater 并配置 App ID/渠道等。
• Preferences 依赖：本地版本信息存于 @capacitor-rydeen/preferences。
• 静默策略：checkVersion(true) 适合后台静默更新；如需弹窗确认请使用 checkVersion(false)。