Remotion 搭建

你需要搭建一个全新的 Remotion 项目并完成配置，使得后续工作流只需要“让 Claude 写提示词”即可。这是一次性的环境搭建工作。每个项目只做一次；之后 remotion-compose 和 remotion-render 会直接进入创意循环。

请积极触发。只要用户提到任何关于用 Claude 制作视频的内容——比如“设置 Remotion”、“创建一个 Remotion 项目”、“我想用 Claude 制作产品视频”、“开始一个视频项目”——就运行这个技能。

步骤 1 - 验证工具链

Remotion 使用无头 Chromium 进行渲染，因此需要先检查 Node：

node --version   # 需要 >= 16；建议使用活跃的 LTS 版本

如果 Node 版本低于 16，则停止并告知用户升级（使用 nvm：nvm install --lts && nvm use --lts）。同时确认 npx 可用（npm 5.2+ 自带）。

步骤 2 - 脚手架项目

npx create-video@latest

这个命令是交互式的。推荐选择 Blank（Hello World）模板——它是产品视频最干净的起点。CLI 会要求输入项目目录和包管理器；让用户选择，然后 cd 到新文件夹并安装依赖：

cd <项目名称>
npm install

步骤 3 - 安装 Remotion 智能体技能

这样 Claude Code 就可以在该仓库中获得 Remotion 自己的技能上下文了：

npx remotion skills add remotion

这个命令会将 Remotion 的智能体技能文件放入项目中。如果已安装的 Remotion 版本不支持该命令，提示用户更新到更新的 @remotion/cli 并继续——这是一个便利功能，不是硬性依赖。

步骤 4 - 建立文件夹规范

标准化布局，以便后续技能始终知道文件放在哪里：

src/
  Root.tsx              # 注册每个 <Composition>（入口注册表）
  index.ts              # registerRoot(RemotionRoot)
  compositions/         # 每段视频一个 .tsx 文件——remotion-compose 会写入这里
public/
  assets/               # 图片、Logo、音频——通过 staticFile() 引用

如果模板没有创建这些文件夹，则手动创建：

mkdir -p src/compositions public/assets

src/Root.tsx 是注册表。每一段视频都是一个在此处注册的 <Composition>：

// src/Root.tsx
import { Composition } from "remotion";
import { HelloWorld } from "./compositions/HelloWorld";

export const RemotionRoot: React.FC = () => {
  return (
    <Composition
      id="HelloWorld"
      component={HelloWorld}
      durationInFrames={90}
      fps={30}
      width={1920}
      height={1080}
    />
  );
};

// src/index.ts
import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";
registerRoot(RemotionRoot);

合理的默认注册参数：30 fps 和 1920x1080 用于横屏产品视频（竖屏社交媒体使用 1080x1920），以及较短的时长——90 帧在 30 fps 下是 3 秒，大多数产品演示视频时长在 15 到 60 秒之间（450-1800 帧）。

步骤 5 - 加载 Google 字体

Remotion 对 Google 字体提供了一流支持，确保文字渲染具有确定性。安装并加载一次：

npm install @remotion/google-fonts

// 在组合文件顶部加载
import { loadFont } from "@remotion/google-fonts/Inter";
const { fontFamily } = loadFont();
// 然后使用：<div style={{ fontFamily }}>...</div>

loadFont() 会阻塞渲染直到字体就绪，因此屏幕上的文字永远不会出现未样式化的回退字体闪烁。选择与品牌匹配的字体——将 Inter 替换为 Poppins、Roboto 等。

步骤 6 - 冒烟测试组合

编写一个简单的组合，证明整个环境可以端到端渲染：

// src/compositions/HelloWorld.tsx
import { AbsoluteFill, useCurrentFrame, interpolate } from "remotion";
import { loadFont } from "@remotion/google-fonts/Inter";

const { fontFamily } = loadFont();

export const HelloWorld: React.FC = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });
  return (
    <AbsoluteFill style={{ backgroundColor: "#0B0B0F", justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ fontFamily, color: "white", fontSize: 90, opacity }}>
        正常工作。
      </h1>
    </AbsoluteFill>
  );
};

确保它已在 src/Root.tsx 中注册（步骤 4），然后渲染它：

npx remotion render src/index.ts HelloWorld out/smoke-test.mp4

首次渲染会下载无头 Chromium（几百 MB——正常网络连接下预计一次性等待几分钟）；之后，这个 90 帧的冒烟测试应该在一分钟内渲染完成。如果 out/smoke-test.mp4 能够播放一个渐显的标题，说明环境就绪。如果渲染失败，几乎总是由以下原因导致： (a) Chromium 下载/权限问题，(b) 组合未在 Root.tsx 中注册，或 (c) 步骤 1 中的 Node 版本问题。

步骤 7 - 启动 Remotion Studio 预览

要使用交互式预览（拖动时间轴、编辑后热重载）：

npx remotion studio

这会在 http://localhost:3000 提供 Studio 服务。create-video 模板也会将 npm run dev 绑定到相同的功能。迭代时保持 Studio 运行——组合文件的编辑会立即热重载。

交付成果

用户最终得到一个可用的 Remotion 项目：包含 src/compositions/ + public/assets/ 布局的脚手架仓库、已安装的 Remotion 智能体技能、已配置的 Google 字体、已注册的冒烟测试组合、一个实际可播放的渲染后 out/smoke-test.mp4，以及正在运行的 Remotion Studio 预览。在冒烟测试 MP4 存在并可播放之前，一切都算不上“搭建完成”。

禁止事项

不要跳过 Node 检查直接搭建——低于 16 的 Node 版本会在 Chromium 渲染深处引发令人困惑的错误，而不是在安装时提示。
不要在不渲染冒烟测试的情况下就宣布搭建完成——一个能编译但从未产生过 MP4 的项目无法证明 Chromium 渲染管线可用。
不要将组合或资源放在临时位置——后续技能（remotion-compose、remotion-render）依赖于 src/compositions/ 和 public/assets/ 的存在。
不要通过相对路径或 URL 引用资源；使用 staticFile() 从 public/ 引用，否则渲染在本地可以工作，但在其他环境会失败。
不要使用系统字体或 CSS 导入的字体来显示屏幕上的文字——如果没有 loadFont() 阻塞，文字在渲染机器上可能会使用回退字体。
不要为产品视频选择功能繁多的模板；Blank 模板避免了用户稍后需要删除的演示代码。

质量标准

node --version 必须在搭建前检查为 >= 16。
out/smoke-test.mp4 必须存在并可播放一个渐显的标题。
文件夹规范必须完全按照指定方式存在，并且冒烟组合已在 src/Root.tsx 中注册。
文字必须通过 @remotion/google-fonts 配合 loadFont() 渲染，不能使用系统回退字体。
Remotion Studio 必须在 localhost:3000 启动，并且编辑后能热重载。

交接

一旦冒烟测试渲染完成并且 Studio 已启动，告知用户项目已就绪并进行交接：“搭建完成。描述你想要的视频——时长、场景、品牌颜色——我会编写组合（remotion-compose），然后渲染并迭代（remotion-render）。”

Remotion 项目搭建