迁移指南（Migration Guides）

本页将 Web（JS）运行时相关迁移说明合并到一个页面中，便于集中查阅。

从 v1 迁移到 v2

Web（JS）运行时从 v1 升级到 v2 的迁移说明。

从 v2 开始，Rive 的 Web（JS）运行时支持在运行时使用 Rive Text。相关包包括：

主要变化

没有破坏性 API 变更！

虽然版本号升级到了 major，但 API 本身没有破坏性改动。v2 的主要变化是包体积增大。原因是 Rive 的 WebAssembly（WASM）构建引入了新的内部依赖，用于支持功能更完整的 Rive Text。

以 v2.0.0 为例，加载 Rive 时请求的 WASM 文件大约为 261kb（brotli 压缩后）。

如果你不需要 Rive Text，可以改用更轻量的：

备注：当前新项目在 Web 端通常更推荐优先评估 @rive-app/webgl2 或 @rive-app/canvas，可参考 Canvas vs WebGL。

从 rive.js 迁移

本文用于说明如何从历史的 rive-js npm 包迁移到新版 Web 运行时包体系。

过去，Web 运行时主要通过 rive-js 这个单包发布。现在已升级为按渲染后端与 API 层级拆分的多包模型，你可以按项目需求选择：

此外，上述包都提供 *-single 变体（将 WASM 直接打包进 JS）。

可参考运行时选择文档：Canvas vs WebGL。

改为多包模型后，你可以更明确地选择渲染后端（例如 CanvasRenderingContext2D 或 WebGL），从而在包体积、性能与能力之间做平衡。

同时，新包体系也会持续支持较新的 Rive 运行时能力（例如光栅资源等）。

对大多数使用高级 API 的项目来说，迁移几乎不涉及业务逻辑改造：

旧方式：

npm i rive-js

import rive from 'rive-js';

const foo = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
});

新方式（以 canvas 为例）：

npm i @rive-app/canvas

import { Rive } from '@rive-app/canvas';

const foo = new Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
});

你也可以根据项目需要，将 @rive-app/canvas 替换为其它 Web 运行时包。

备注：如果是新项目，通常可优先评估 @rive-app/webgl2 与 @rive-app/canvas 两个方向。