跳到正文
子在川上曰
返回

Remotion 安装指南:从零创建一个视频项目

编辑此页

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:

包管理器命令
npmnpx create-video@latest
pnpmpnpm create video
Yarnyarn create video
Nubnubx 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
macOS15 (Sequoia) 及以上,旧版本不支持
Linuxglibc ≥ 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 三个文件即可。

参考资料


编辑此页