Remotion 教程 14：版本、浏览器、缓存和渲染稳定性

Remotion 写起来像 React，但渲染链路比普通网页更长。它会经过打包、浏览器渲染、截图、编码等步骤。工程稳定性要提前考虑。

这篇不是讲新功能，而是整理真实项目里最容易影响出片稳定性的点。

Remotion 包版本要对齐

remotion 和 @remotion/* 包建议保持同一版本。混用版本可能导致 CLI、renderer、player 或 studio 行为不一致。

推荐写成精确版本：

{
  "remotion": "4.0.460",
  "@remotion/cli": "4.0.460",
  "@remotion/media": "4.0.460",
  "@remotion/transitions": "4.0.460"
}

不要随手加 ^，否则不同机器安装到的 patch 版本可能不同。

浏览器环境要稳定

Remotion 渲染需要浏览器。开发机可以使用本机 Chrome，也可以让 Remotion 下载 Headless Shell。

CI 或服务器上要确认：

• Chrome 或 Headless Shell 可用。
• 字体存在。
• 沙箱权限满足要求。
• 系统依赖库齐全。
• 浏览器路径固定。

本地排查时可以显式指定 Chrome：

npx remotion still FinalTalkingVideo --frame=100 --browser-executable=/usr/bin/google-chrome

静态素材必须可访问

图片、音频、视频、Rive、wasm 等素材建议放在 public/ 目录，并用 staticFile() 引用：

<Audio src={staticFile("audio/talking-demo.wav")} />

不要在渲染时依赖不稳定的远程地址。批量出片时，任何一次素材下载失败都会变成渲染失败。

WebAssembly 和生态库要单独验证

Skia、Rive、Three 这类生态库比普通 DOM 更容易遇到环境问题。

例如 Skia Web 需要等待 wasm 和图形组件加载完成，否则可能截到空画布。可以用 delayRender()：

const handle = delayRender("加载 Skia 图形");
 
LoadSkiaWeb({ locateFile: (file) => `/${file}` })
  .then(() => import("./SkiaArtwork"))
  .then(() => continueRender(handle));

Rive 文件也可能和 runtime 版本不兼容。如果遇到：

RuntimeError: null function
function signature mismatch

优先检查 .riv 文件使用的 Rive Web runtime 版本。

缓存问题要能快速排查

如果遇到 webpack cache 或打包 hash 异常，可以先清理 Remotion 的 webpack 缓存再复测：

rm -rf node_modules/.cache/webpack/remotion-production-*
rm -rf node_modules/.cache/webpack/remotion-development-*

这不是业务修复，但能帮助你判断问题是否来自构建缓存。

动画要避免运行时依赖

不要把 CSS transition、CSS animation、Motion runtime 动画或 D3 transition 当作视频主动画。

主动画应该来自：

frame -> interpolate / spring -> style

这样单帧预览、局部渲染和完整导出才更稳定。

渲染验证要分层

推荐按这个顺序验证：

1. npm run lint
2. 单帧 still
3. 短片段低分辨率 render
4. 完整视频 render

示例：

npm run lint
npx remotion still LessonDataVideo --frame=90 --scale=0.25 --browser-executable=/usr/bin/google-chrome
npx remotion render FinalTalkingVideo --frames=0-120 --scale=0.25 --browser-executable=/usr/bin/google-chrome

这样能更快定位问题在类型、布局、浏览器还是编码阶段。

线上渲染要记录上下文

批量生成时，每个任务都应该记录：

• Composition ID。
• 输入 props。
• 模板版本。
• Remotion 版本。
• 浏览器版本。
• 素材地址。
• 错误日志。

没有这些信息，渲染失败后很难复现。

示例项目位置

这组文章的示例项目已经覆盖了几类常见验证：

LessonLottieEcosystem：Lottie 渲染
LessonRiveEcosystem：Rive + 本地 wasm
LessonThreeEcosystem：Three 3D 场景
LessonSkiaEcosystem：Skia Web 加载和绘制
FinalTalkingVideo：带音频的竖屏口播模板

读完这一篇，你已经走完了从 Remotion 核心思维、生态选择、AI 口播短视频到批量生成架构的完整路径。后面可以回到 docs/tutorial/，按讲义把示例改成自己的视频模板。