Remotion新手入门教程

你会写 React，但一想到做视频就去找剪辑软件，改个字号都要用鼠标拖半天。Remotion 的思路是把视频当成 React 组件来写，用 CSS 排版、用 props 传数据、用代码循环生成上百个镜头。这篇不堆概念，按你实际动手的顺序走一遍：先判断这条路适不适合你，再把第一个动画跑出来，最后讲清参数、渲染和常见坑。

你会写 React，但一想到做视频就去找剪辑软件，改个字号都要用鼠标拖半天，改完还得重新导出。Remotion 的思路反过来：把视频当成 React 组件来写，用 CSS 排版、用 props 传数据、用代码循环生成上百个镜头。它的确定性来自一个简单前提——同一帧、同一份输入，渲染出来的画面永远一样。

这篇不堆概念，按你实际动手的顺序走一遍：先判断这条路适不适合你，再把第一个动画跑出来，然后讲清参数、渲染和常见坑。文中涉及具体数字的地方（价格、版本、帧率对照），都建议你到站内页面核对当时的值，因为这些东西迭代得快。

Remotion 到底把视频变成了什么

一句话定位：把每一帧当成一次 React 渲染，时间是唯一的外部输入。你写的是一个组件，它接收「当前第几帧」这个数字，然后返回那一帧长什么样。Remotion 负责把这个组件按帧循环调用、截图、编码成视频文件。你熟悉的组件树、props、条件渲染、map 循环，全部照常能用。

和剪辑软件、文生视频工具的分工差别在于：剪辑软件处理的是「已有的连续素材」，做的是剪切、拼接、调色；文生视频工具处理的是「从文字到画面」，结果不可控、不可复现。Remotion 处理的是「确定性的合成」——数据驱动、可复用、适合批量套模板。这三者不是替代关系，是各干各的活。

动手前先确认三件事

第一件是前端基础清单：React 组件与 props、CSS 布局（尤其是绝对定位和 transform）、npm 脚本。缺哪块先补哪块，特别是 CSS 的定位和层级，Remotion 里所有的排版最终都落在这一层。如果只会写业务逻辑、几乎没碰过布局，会在这个环节卡很久。

第二件是把环境对齐。Node 版本、包管理器、浏览器内核这几样要按官方要求配好，避免第一次跑就报环境错——这类错误信息往往指向底层依赖，和你写的代码毫无关系，新手很容易被误导成「我代码写错了」。遇到这类报错，先怀疑环境，再怀疑代码。

• React 组件与 props：能独立写一个接收参数、返回结构的函数组件
• CSS 布局：会用 position、transform、flex 控制元素位置和层级
• npm 脚本：能看懂 package.json 里的 scripts，会跑自定义命令
• 命令行基础：会在终端里执行命令、看输出、定位报错
• 目标想清楚：固定模板批量出片，还是一次性动画，这决定了要不要规划数据层

第一个项目：从脚手架到能看的画面

用官方脚手架起项目，它会给你一个能跑的示例。你要认清三个东西的关系：入口文件负责把项目挂载起来，Composition 注册负责登记「有哪些可渲染的片段」，根组件负责决定当前渲染哪个片段。这三层搞混了，后面改什么都不知从哪下手。

把 Composition 理解成一个配置对象：它描述「一个可渲染的片段 + 尺寸 + 帧率 + 时长」。你注册几个 Composition，预览器里就能切换几个。尺寸和帧率是全局性的决定，后面所有动画数值都要基于它们换算，所以第一步就定好，别中途改。

1. 起项目用官方脚手架创建项目，装依赖，跑起来。验证标准是预览器能打开、能看到默认示例。
2. 读懂三个文件找到入口文件、Composition 注册处、根组件。验证标准是你能在预览器里新增一个 Composition 并切换过去。
3. 做静态画面把默认内容改成一个纯静态的排版，放几行文字和一个色块。验证标准是画面比例、位置符合预期。
4. 加一帧位移只加一个位置变化，不做复杂动画。验证标准是预览器能实时刷新，改代码立刻看到效果。
5. 确认再往下预览流畅、改动即时生效，说明环境和链路都通了，这时候再学动画。

时间和动画：帧、时长、插值怎么用

帧率决定一切数值。你说「让它两秒移过去」，代码里必须换算成帧数，因为组件拿到的是帧号不是秒。这是新手最容易忽略的一点：直接写秒数、或者凭感觉写个位移量，结果就是不同帧率下快慢完全不一样。养成先把时间换算成帧、再写进动画的习惯。

插值函数负责把帧号映射成某个属性的值，比如把帧号映射成透明度或位移。关键是处理边界：如果不在首尾做限制，动画可能在开头或结尾出现突然的跳变。解决办法是明确指定输入区间和输出区间，并让超出区间的值停在边界上，而不是继续外推。

序列和嵌套解决的是「一条时间线怎么拼」的问题。别把所有内容都塞进一个组件，用序列把不同片段按时间排开，或者把片段拆成独立组件再嵌套。这样每段可以单独预览、单独改，出问题时定位范围也小。

帧率

每秒渲染多少帧，所有时间数值换算的基准，定了就别改

插值

把帧号映射成属性值的函数，重点在边界怎么收尾

序列

把多个片段按时间顺序排开，替代在一个组件里堆条件判断

时长

Composition 的总帧数，决定了整片能播多久，超出部分不会渲染

把数据传进去：参数化与批量出片

参数化是 Remotion 相对剪辑软件最大的优势。把文案、图片、配色这些会变的东西从组件里抽出来，做成输入参数，同一套组件就能出不同片子。做法是给组件定义好 props 类型，然后在渲染时传入不同的数据对象。改数据不改代码，这是批量出片的前提。

数据结构要提前定：一条记录对应一帧，还是一片镜头。这个决定影响后面所有循环逻辑。如果是一条记录一帧，适合逐帧变化的数据展示；如果是一条记录一片，适合把每条数据渲染成一个完整片段再拼接。定错了返工成本很高。

参数校验是个习惯问题：传进来的数据缺字段时，先让它明确报错，而不是渲染出一片空白。空白画面最难排查，因为你不知道是数据没到、位置算错、还是组件没渲染。在组件开头做一次字段检查，缺什么直接抛出，能省下大量猜测时间。

• 抽出的应该是「会变的东西」：文案、图片地址、配色、时长参数
• 不变的排版逻辑留在组件里，别为了灵活把结构也参数化
• 给 props 写明类型，编辑器能帮你提前发现传错的字段
• 渲染前统一校验一次数据，缺字段直接报错，不要静默降级
• 准备好几组样本数据，随时切换测试，避免只测一组

图片、音频、字体这些素材怎么放

静态资源目录和引用方式有区别，路径写错时的典型表现是：预览器里能看到，渲染出来是空白或占位。原因通常是预览和渲染的工作目录不一致。稳妥做法是统一用官方提供的静态资源引用方式，别写相对路径。相对路径在多环境下的行为差异最大。

加载远程素材要考虑等待时间。如果图片还没加载完，画面就已经渲染到那一帧，出来的就是空白。别让画面先于图片出现——要么用阻塞机制等素材就绪，要么提前把素材落到本地。远程素材还有个隐患是网络抖动，渲染大项目时中途失败，排查起来很麻烦。

字体和中文排版是最容易出差异的地方：字重缺失会回退成默认字体，行高变化会让原本对齐的版式错位，不同机器上的渲染结果也可能不一致。建议把字体文件本地化，明确指定字重，别依赖系统默认字体。版式定好后，在另一台机器上跑一次，确认结果一致再批量出片。

渲染出片：本地预览、命令行渲染的顺序

别一上来就整片渲染等半天。先小范围试渲染，比如只渲染开头几帧或者截取一小段，确认没问题再整片跑。原因很简单：渲染是逐帧执行的，一个小错误在整片里不会被放大，只会让你多等一轮。试渲染是成本最低的验证手段。

分辨率、码率、编码格式这几个参数各自影响不同的东西：分辨率决定画面尺寸，码率决定画质和文件大小，编码格式决定兼容性。按用途选，而不是一律拉满——拉满的代价是渲染时间和文件体积都上去了，但很多场景根本用不到那个画质。

产出文件偏大或画面糊时，排查顺序是：先看素材源本身够不够好，再看分辨率设置对不对，最后才调码率。很多人一上来就调码率，其实源头素材就糊，怎么调都救不回来。顺序反过来，能少走很多弯路。

1. 试渲染只渲染少量帧或一小段，确认画面、字体、素材都正常。
2. 定参数按用途选分辨率和编码格式，别默认拉满，先确认需求。
3. 整片渲染确认试渲染没问题后再跑整片，中途别改代码。
4. 检查产出播一遍成片，重点看首尾、转场、素材加载处。
5. 偏大或糊时排查按「素材源 → 分辨率 → 码率」的顺序逐项排除，不要跳步。

新手最容易卡住的几处对照表

最典型的一类问题是「预览能播、渲染失败」。这多半不是代码逻辑问题，而是浏览器内核或资源路径的问题。排查顺序是先确认内核配置，再检查素材路径，最后才怀疑组件代码。这个顺序能让你少改很多本来没问题的代码。

第二类是画面抖动或卡顿。查逐帧计算里是不是依赖了随机值——比如每帧重新算一次随机数，画面就会抖。正确做法是让随机值在渲染前固定下来，或者用基于帧号的确定性伪随机。第三类是性能吃紧，长视频优先拆片段、减少重复计算，再考虑上渲染队列。

• 预览能播、渲染失败：先查浏览器内核，再查资源路径，最后看代码
• 画面抖动：检查逐帧计算是否依赖随机值或时间戳
• 画面闪烁：检查元素是否每帧重新挂载或重新计算
• 性能吃紧：先拆片段、减少重复计算，再考虑渲染队列
• 结果不一致：换一台机器跑同一份代码，确认是否环境差异

还有一类是结果不一致：同一份代码在不同机器上渲染出来有差异。这种情况优先怀疑字体、内核版本、依赖版本这些环境因素，而不是先改代码。团队协作时把环境要求写进文档，比事后排查省事得多。想了解同类工具在渲染链路上的表现，可以到站内工具页面看当时的对比记录。