预加载 WASM

Rive 基于 WASM 的运行时需要加载 Web Assembly 文件。预加载 WASM 可以显著提升性能。

React 运行时是其对应 JavaScript 运行时的轻量封装，会从相同位置加载同一个 WASM 文件。

在页面加载时初始化 Rive

如果你需要 Rive 在页面加载时立即可用于渲染图形（例如 hero 动画），我们建议同时预加载 rive.wasm 文件和 .riv 文件，以便浏览器提前开始下载必要资源。在 JS 端，你可以使用 RuntimeLoader API 在 Rive 组件挂载之前，提前开始下载并编译 WASM。

默认情况下，React 运行时会从它锁定的 @rive-app/canvas 版本对应的 unpkg 上获取 rive.wasm——你无需为此调用 RuntimeLoader.setWasmUrl()。

在 React 中匹配 WASM 版本：@rive-app/react-canvas 的版本与它封装的底层 @rive-app/canvas 版本并不相同。rive.wasm 必须与 canvas 版本匹配。要找到它，请打开你所安装 React 运行时的 GitHub 上的 package.json 并查看 @rive-app/canvas 依赖——例如 [email protected] 锁定了 @rive-app/[email protected]。将 URL 中的 tag 替换为你所安装版本对应的 tag。

要预加载它，只需将一个 <link rel="preload"> 指向同一个 URL（查找版本的方法见上方说明）：

<!-- index.html（或主应用入口） -->
<!-- 尽早打开到 wasm CDN 的连接 -->
<link rel="preconnect" href="https://unpkg.com" crossorigin />

<!-- 如果你自行托管 WASM 文件，请将此处指向 rive.wasm 在你 CDN 中的位置 -->
<link
  rel="preload"
  as="fetch"
  crossorigin
  href="https://unpkg.com/@rive-app/[email protected]/rive.wasm"
/>

<!-- 同时预加载主要的 hero .riv 文件 -->
<link rel="preload" as="fetch" crossorigin href="/assets/hero.riv" />

然后在你的 React 应用中，尽可能早地开始编译 WASM 文件。

import {useRive, RuntimeLoader} from '@rive-app/react-canvas';

// （可选）仅当你从自己的 CDN 提供 rive.wasm 而未使用 unpkg 时添加。
// 这应与你预加载的 URL 一致
// RuntimeLoader.setWasmUrl("https://cdn.example.com/assets/rive-2.41.0.wasm");

if (typeof window !== 'undefined') {
  RuntimeLoader.awaitInstance().catch(() => {});
}

export default function Hero() {
  const { RiveComponent } = useRive({
    src: '/assets/hero.riv',
    stateMachine: 'State Machine 1',
    autoplay: true,
    autoBind: true,
  });

  return <RiveComponent style={{ width: 400, height: 400 }} />;
}

或者，如果你更希望让打包工具在应用构建时自行托管并对 WASM 文件进行版本匹配，也可以导入它。由于 @rive-app/canvas 只是 React 运行时的传递依赖，该导入在 npm/yarn（会将其提升）下可以解析，但在 pnpm 下会失败，除非你将 @rive-app/canvas 以匹配的版本添加到自己的 package.json 中。

import riveWASMResource from '@rive-app/canvas/rive.wasm'; // Vite: 追加 ?url
import {RuntimeLoader} from '@rive-app/react-canvas';
RuntimeLoader.setWasmUrl(riveWASMResource);

该导入会将 rive.wasm 作为单独的哈希文件输出，而不会内联到你的 JS bundle 中。