Remotion 是一个用 React 写视频的框架。装好它之后,你就能把视频当成组件来写——时间轴是 props,改一行代码重渲染一次。
本文翻译并整理自 Remotion 官方文档的 Creating a new project(安装首页)、Installation in existing project 与 Linux Dependencies 三页内容,命令与版本号均按官方文档核对(更新至 2026 年 11 月)。
目录
展开目录
一、创建新项目的三种方式
官方给了三条起手路径,按上手难度从低到高排列。
1.1 用 ChatGPT 桌面版
如果你装了 ChatGPT 桌面版,配合 Remotion 插件,它可以直接生成一个完整的 Remotion 项目,你可以本地编辑、运行和渲染。
1.2 用编程代理
把下面这段提示词粘给 Claude Code、Codex 或 OpenCode:
确保已安装 Node.js。
安装 Remotion 技能:
npx -y skills@latest add remotion-dev/skills -g -y然后用它们帮我做一个视频。
想更系统地用提示词做视频,官方还有一份专门的入门指引。
1.3 用命令行
最直接的方式,一条命令建好项目:
npx create-video@latest --yes --blank my-video
cd my-video
npx remotion skills add
npm run dev
这会在 my-video 目录里用 blank 模板建好项目,装上 Agent Skills,并且不包含 TailwindCSS。
二、模板与向导
2.1 选模板
从模板列表里挑最合适的。第一次做,官方推荐 Hello World 模板。
2.2 交互式向导
create-video 的向导可以选包管理器、选模板,以及决定要不要装 Agent Skills:
| 包管理器 | 命令 |
|---|---|
| npm | npx create-video@latest |
| pnpm | pnpm create video |
| Yarn | yarn create video |
| Nub | nubx create-video@latest |
| Bun(管理器 + 运行时) | bun create video |
注意:Bun 作为运行时是「基本可用」。官方措辞是 mostly supported,详情见这里。
2.3 项目建好后启动
- 普通模板:在编辑器里打开项目,运行
npm run dev启动 Remotion Studio。 - Next.js + React Router 7 模板:运行
npm run dev启动应用,运行npm run remotion启动 Studio。
三、配置 ESLint
Remotion 模板自带一套推荐的 ESLint 配置。想换适配你 ESLint 版本的配置,或者加到别的项目里,参考 @remotion/eslint-config。
四、系统要求
| 环境 | 要求 |
|---|---|
| Node | ≥ 16 |
| Bun | ≥ 1.0.3 |
| macOS | 15 (Sequoia) 及以上,旧版本不支持 |
| Linux | glibc ≥ 2.35(Amazon Linux 2023 ARM64 例外,见下文) |
Alpine Linux 和 nixOS 均不支持。
4.1 Linux 各发行版依赖包
Remotion 在 Linux 上渲染依赖 Chrome Headless Shell,需要装一些共享库。glibc 版本要求 2.35 及以上;Amazon Linux 2023 的 ARM64 支持 glibc 2.34,x64 因为只有 glibc 2.34 而不支持——要么用 ARM64,要么换 Ubuntu 22.04 及以上的发行版。
Ubuntu 24.04 / 22.04(两者一致):
apt install -y \
libnss3 \
libdbus-1-3 \
libatk1.0-0 \
libasound2t64 \
libxrandr2 \
libxkbcommon-dev \
libxfixes3 \
libxcomposite1 \
libxdamage1 \
libgbm-dev \
libcups2 \
libcairo2 \
libpango-1.0-0 \
libatk-bridge2.0-0
老版本 Ubuntu(仅 libasound2 与上面不同):
apt install -y \
libnss3 \
libdbus-1-3 \
libatk1.0-0 \
libasound2 \
libxrandr2 \
libxkbcommon-dev \
libxfixes3 \
libxcomposite1 \
libxdamage1 \
libgbm-dev \
libcups2 \
libcairo2 \
libpango-1.0-0 \
libatk-bridge2.0-0
Debian:
apt install -y \
libnss3 \
libdbus-1-3 \
libatk1.0-0 \
libgbm-dev \
libasound2 \
libxrandr2 \
libxkbcommon-dev \
libxfixes3 \
libxcomposite1 \
libxdamage1 \
libpango-1.0-0 \
libcairo2 \
libcups2 \
libatk-bridge2.0-0
Amazon Linux 2023(仅 ARM64 支持,是 glibc 2.35 要求的例外):
yum install -y \
mesa-libgbm \
libX11 \
libXrandr \
libdrm \
libXdamage \
libXfixes \
libxkbcommon \
dbus-libs \
libXcomposite \
alsa-lib \
nss \
dbus \
pango \
cups-libs \
at-spi2-core \
atk \
at-spi2-atk \
libxkbcommon
4.2 不支持的发行版
- Alpine Linux:不支持,因为缺少所需 Libc 符号。
- nixOS:不支持,因为 Remotion 自带 Chrome 和 FFmpeg 二进制,没有打进系统里,跟 nixOS 的「不可变发行版」架构冲突。
五、在已有项目中安装 Remotion
Remotion 可以装进现有项目,比如 Next.js、React Router、Vite 或 Create React App,也可以装进纯 Node.js 的服务端项目。
5.1 安装核心包
npm i --save-exact remotion@4.0.537 @remotion/cli@4.0.537
(以 npm 为例;pnpm 用 pnpm i remotion@4.0.537 @remotion/cli@4.0.537,bun 用 bun i ...,yarn 用 yarn --exact add ...)
几个要点:
- 上面以 v4.0.537 为例,请换成你当前用的最新版本。
- 把
remotion和所有@remotion/*包统一到同一个版本。 - 删掉版本号前面的
^,否则可能引发版本冲突。
按需再装这几个包:
| 需求 | 包 |
|---|---|
| 在现有 React 应用里嵌入 Remotion 视频 | @remotion/player |
| 用 Node.js API 渲染视频 | @remotion/renderer |
| 在 Remotion Lambda 上触发渲染 | @remotion/lambda |
5.2 建立文件夹结构
新建一个放 Remotion 文件的文件夹,位置和名字随意,这里以项目根目录下的 remotion 为例。在里面建三个文件:
remotion/Composition.tsx:
export const MyComposition = () => {
return null;
};
remotion/Root.tsx:
import React from "react";
import { Composition } from "remotion";
import { MyComposition } from "./Composition";
export const RemotionRoot: React.FC = () => {
return (
<>
<Composition
id="Empty"
component={MyComposition}
durationInFrames={60}
fps={30}
width={1280}
height={720}
/>
</>
);
};
remotion/index.ts:
import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";
registerRoot(RemotionRoot);
调用了 registerRoot() 的文件,就是 Remotion 的入口点。
注意:小心
tsconfig.json里的 import 别名,别让import {...} from "remotion"被解析到你的remotion文件夹。建议不要用不带前缀的paths。
5.3 启动 Studio
npx remotion studio remotion/index.ts
入口点不同的话,把 remotion/index.ts 换成你的实际路径。
5.4 渲染视频
npx remotion render remotion/index.ts MyComp out.mp4
把入口点、composition ID 和输出文件名换成你自己的。
5.5 配置 ESLint
Remotion 提供了 ESLint 规则,用于提示 API 的错误或低效用法。用 @remotion/eslint-plugin 接入你现有的 ESLint 配置;想要 Remotion 的完整 ESLint 设置,看 @remotion/eslint-config。
5.6 把视频嵌入现有 React 应用
用 <Player> 组件就能在 React 项目里播放 Remotion 视频,具体看单独的说明页。
六、小结
- 新项目:
npx create-video@latest --yes --blank my-video一条命令搞定,Hello World 模板最适合入门。 - 系统门槛:Node ≥ 16,macOS ≥ 15,Linux glibc ≥ 2.35;Alpine 和 nixOS 不支持。
- 已有项目:
remotion+@remotion/cli装同一版本、去^,再建Composition.tsx/Root.tsx/index.ts三个文件即可。