Remotion 最佳实践
将 Remotion 输出构建为帧、输入属性和声明资产的确定性函数。保留用户编辑以及项目现有的包管理器、架构和样式，除非任务需要更改。
从证据开始
- 阅读仓库说明，检查
package.json、锁文件、Remotion 配置、入口点、已注册的合成以及附近的测试。 - 对于现有项目，运行
node <skill-directory>/scripts/audit-remotion-project.mjs <project-root>。将其输出视为证据，而非升级的许可。 - 在选择 API 之前，记录已安装的 Remotion 版本。将所有
remotion和@remotion/*包保持在同一精确版本上。不要添加第二个锁文件。 - 确定交付物是视频、单张静态图像、从视频中采样的帧，还是一批商店截图。
- 在实现之前定义合成 ID、尺寸、FPS、时长、属性、输出路径和所需资源。
仅加载相关参考
- 对于
<Composition>、<Still>、useCurrentFrame()、interpolate()、spring()、<Sequence>或<Series>，请阅读 composition-and-timing.md。 - 对于
staticFile()、媒体、字体、网络数据、useDelayRender()、delayRender()或calculateMetadata()，请阅读 assets-and-async.md。 - 对于 CLI、
renderStill()、服务器端渲染或 Remotion Lambda，请阅读 rendering-and-lambda.md。 - 对于渲染缓慢、内存使用高、非确定性或验证策略，请阅读 performance-and-testing.md。
- 对于 App Store 或 Google Play 图片，包括由
screenshot-studio委托的 1284×2778 输出，请阅读 store-stills.md。 - 当某个 API 或平台规则可能已更改时，请在编码前查阅 sources.md 中链接的实时主要来源。
不可协商的实现规则
- 从
useCurrentFrame()和useVideoConfig()派生时间。不要使用 CSS 过渡、CSS 关键帧动画、挂钟计时器或未设置种子的随机数来生成渲染运动。 - 约束有限动画，除非有意进行外推。将时间表示为秒乘以
fps当它们代表时间时，并集中管理共享场景的时长。 - 请记住，
useCurrentFrame()在时间组件内部是相对的。仅当有意全局同步时，才从合成根传递绝对帧。 - 使用
<Sequence>进行在父时间线上的显式放置，使用<Series>进行连续的场景。为每个场景赋予显式的时长。 - 将本地资源放在
public/中，并使用staticFile()解析它们。使用 Remotion 媒体组件而不是原始 HTML 标签，以便渲染正确等待媒体加载。 - 优先在组件内部使用
useDelayRender()。创建一次句柄，恰好清除一次，并在失败时调用cancelRender(error)。对于需要在每次渲染中确定属性或元数据的数据，优先使用calculateMetadata()。 - 确保渲染时代码不使用浏览器专属的假设，这些假设在无头 Chromium 或 Lambda 中不可用。永远不要将 AWS 凭据或其他机密暴露给浏览器包。
- 为每个商店目标独立验证尺寸、文件格式、Alpha 通道策略和平台特定规则。切勿假设一种竖屏尺寸同时被 Apple 和 Google 接受。
在紧凑的渲染循环中工作
- 进行类型检查并运行聚焦测试。
- 渲染具有代表性的静态帧：开始帧、每个场景边界、运动中间点以及最后一帧。
- 检查实际像素，而不仅仅是 Studio 预览。检查裁剪、文本换行、安全边距、缺失资源和透明背景。
- 在执行完整的高成本视频之前，先渲染短帧范围或低比例草稿。
- 在部署机器上基准测试并发性，而不是盲目最大化。
- 使用显式的合成 ID、属性、输出路径、尺寸和格式渲染最终产物。
- 验证退出状态、文件是否存在、像素尺寸、时长/帧数（如相关）以及最终的视觉样本。
保守地进行更改
- 除非任务要求或用户批准，否则不要升级 Remotion、重写项目结构或替换媒体组件。
- 根据已安装版本门控较新的 API；在可行时提供兼容的回退方案。
- 不要通过任意增加超时来隐藏渲染失败。首先识别未解析的句柄、网络请求、资源、字体或媒体解码。
- 没有来自可比渲染的测量数据，就不要声称性能提升。