12b - 环境搭建

本文是《AI Agent 实战手册》第 12 章第 2 节。 上一节：12a-代码驱动视频概念 | 下一节：12c-端到端工作流

概述

要用 AI Agent 驱动 Remotion 生成视频，你需要搭建三层环境：Remotion 视频框架本身、Claude Code 命令行 AI 助手、以及连接两者的 Remotion Agent Skills。本节提供从零开始的完整环境搭建指南，覆盖每一步的安装、配置和验证，确保你能在 30 分钟内跑通”自然语言 → 视频代码 → 渲染输出”的完整链路。

1. 前置条件与工具总览

在开始搭建之前，先确认你的开发环境满足基本要求，并了解整个工具链的组成。

工具推荐

操作步骤

步骤 1：检查系统前置条件

Remotion 要求 Node.js 16 或更高版本（推荐 20 LTS 或 22 LTS），或 Bun 1.0.3+。在终端中运行以下命令确认：

# 检查 Node.js 版本
node --version
# 应输出 v16.x.x 或更高，推荐 v20+ 或 v22+
 
# 检查 npm 版本
npm --version
 
# （可选）如果使用 Bun
bun --version
# 应输出 1.0.3 或更高

如果尚未安装 Node.js，推荐通过 nvm （macOS/Linux）或 nvm-windows （Windows）安装：

# macOS/Linux：安装 nvm 后
nvm install 22
nvm use 22
 
# Windows：安装 nvm-windows 后
nvm install 22
nvm use 22

步骤 2：确认 Git 已安装

git --version
# 应输出 git version 2.x.x

步骤 3：了解许可证要求

在开始项目前，确认你的 Remotion 许可证资格：

2. 创建 Remotion 项目

操作步骤

步骤 1：使用脚手架创建新项目

Remotion 提供官方脚手架命令，一行即可创建完整项目：

# 使用 npm
npx create-video@latest
 
# 使用 bun
bun create video
 
# 使用 pnpm
pnpm create video
 
# 使用 yarn
yarn create video

运行后会出现交互式提示，依次选择：

1. 项目名称：输入你的项目名（如 my-video-project）
2. 模板选择：首次使用推荐选择 Hello World 模板
3. 安装 Agent Skills：如果使用 bun create video，会提示是否自动安装 Skills，选择 Yes

可用模板包括：

步骤 2：进入项目并安装依赖

# 进入项目目录
cd my-video-project
 
# 如果脚手架没有自动安装依赖
npm install
# 或
bun install

步骤 3：确认项目结构

创建完成后，项目结构大致如下：

my-video-project/
├── src/
│   ├── Root.tsx          # 视频组合注册入口
│   ├── Composition.tsx   # 主视频组件
│   └── ...               # 其他组件
├── public/               # 静态资源（图片、字体等）
├── package.json
├── tsconfig.json
├── remotion.config.ts    # Remotion 配置文件（可选）
└── README.md

提示词模板

我刚创建了一个 Remotion 项目，使用的是 [Hello World / Blank / TailwindCSS] 模板。
请帮我理解项目结构，并解释以下文件的作用：
1. src/Root.tsx
2. remotion.config.ts
3. package.json 中与 Remotion 相关的脚本

然后帮我创建一个简单的 [文字动画 / 数据图表 / Logo 展示] 视频组件作为练习。

3. 启动 Remotion Studio

Remotion Studio 是内置的本地预览工具，提供实时预览、时间线控制、参数编辑和渲染功能。

操作步骤

步骤 1：启动 Studio

# 在项目根目录运行
npm run dev
 
# 或直接使用 Remotion CLI
npx remotion studio

Studio 会在浏览器中自动打开（默认地址 http://localhost:3000）。

步骤 2：熟悉 Studio 界面

Studio 界面包含以下核心区域：

步骤 3：验证 Studio 正常运行

1. 在浏览器中看到视频预览画面
2. 点击播放按钮，动画正常播放
3. 拖动时间线，画面随帧号变化
4. 在侧边栏修改 Props，预览实时更新

如果 Studio 无法启动，常见原因和解决方法：

# 端口被占用 → 指定其他端口
npx remotion studio --port 3001
 
# Chrome/Chromium 未安装 → 安装浏览器依赖
npx remotion browser ensure
 
# 依赖缺失 → 重新安装
rm -rf node_modules && npm install

4. 安装和配置 Claude Code

Claude Code 是 Anthropic 推出的终端 AI 编码助手，能直接在命令行中理解代码库、生成代码、执行命令。它是驱动 Remotion 视频生成的 AI 引擎。

工具推荐

操作步骤

步骤 1：安装 Claude Code

Claude Code 通过 npm 全局安装：

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

验证安装：

claude --version

步骤 2：认证登录

首次使用需要认证。有两种方式：

方式 A：使用 Claude 订阅（推荐）

# 启动 Claude Code，会自动引导浏览器登录
claude
 
# 在浏览器中完成 Anthropic 账号登录
# 登录后终端会显示认证成功

方式 B：使用 API Key

# 设置环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
 
# 或在 Claude Code 中配置
claude config set apiKey sk-ant-xxxxx

步骤 3：验证 Claude Code 正常工作

# 在 Remotion 项目目录中启动 Claude Code
cd my-video-project
claude
 
# 在 Claude Code 中输入测试问题
> 这个项目是做什么的？请简要说明项目结构。

如果 Claude Code 能正确识别项目为 Remotion 视频项目并描述其结构，说明安装和认证成功。

提示词模板

我刚安装好 Claude Code，正在一个 Remotion 视频项目中使用。
请帮我确认环境是否正确：
1. 检查 Remotion 版本和依赖是否完整
2. 确认 TypeScript 配置是否正确
3. 列出当前项目中已注册的 Composition
4. 尝试启动 Remotion Studio 并报告结果

5. 安装 Remotion Agent Skills

Remotion Agent Skills 是连接 Claude Code 和 Remotion 的关键桥梁。它是一组 Markdown 知识文件，教会 AI Agent Remotion 的 API 模式、最佳实践和常见陷阱。2026 年 1 月发布后迅速走红，让 Claude Code 从”通用编码助手”变成”Remotion 视频开发专家”。

操作步骤

步骤 1：安装 Skills

在 Remotion 项目根目录运行：

npx remotion skills add

或者直接指定 Skills 源：

npx skills add remotion-dev/skills

安装过程约 15 秒，无需额外配置或 API Key。

步骤 2：确认安装结果

安装成功后，你会看到类似输出：

✓ Installed remotion-best-practices to .claude/skills/remotion-best-practices

检查文件是否存在：

ls .claude/skills/remotion-best-practices

你应该看到以下结构：

.claude/skills/remotion-best-practices/
├── SKILL.md                    # Skills 主文件
└── rules/
    ├── animations.md           # 动画最佳实践
    ├── audio.md                # 音频处理规则
    ├── compositions.md         # Composition 编写规范
    ├── rendering.md            # 渲染配置指南
    ├── ...                     # 更多规则文件（共 28+ 个）
    └── typescript.md           # TypeScript 类型规范

这些文件包含了 Remotion 的核心知识：帧计算、interpolate() 用法、Sequence 编排、音频同步、渲染配置等。Claude Code 在处理 Remotion 相关请求时会自动加载这些知识。

步骤 3：验证 Skills 是否生效

启动 Claude Code 并提问一个 Remotion 特定问题来验证：

claude
> 如何在 Remotion 中创建一个平滑的淡入效果？

Skills 已生效的标志： Claude 会使用 interpolate() 和 useCurrentFrame() 来实现，这是 Remotion 的标准做法。

Skills 未生效的标志： Claude 会建议使用 CSS transition 或 React useState，这是通用 React 的做法，不适用于 Remotion。

步骤 4：更新 Skills

当 Remotion 发布新版本或 Skills 有更新时：

npx remotion skills update

提示词模板

我已经安装了 Remotion Agent Skills。请用 Remotion 的方式（不是普通 React）帮我实现以下效果：

**需求：**
[描述你想要的视频效果]

**要求：**
- 使用 useCurrentFrame() 和 interpolate() 驱动动画
- 使用 Sequence 组织时间线
- 遵循 Remotion 最佳实践
- 代码可直接在 Remotion Studio 中预览

6. 完整环境验证：端到端测试

所有组件安装完成后，执行一次端到端测试，确保整个链路畅通。

操作步骤

步骤 1：用 Claude Code 生成视频代码

在 Remotion 项目目录中启动 Claude Code：

cd my-video-project
claude

输入以下 prompt：

请帮我创建一个 5 秒的视频组件，内容是：
- 深色背景（#0f0f0f）
- 白色标题文字 "Hello, AI Video!" 从底部滑入并淡入
- 淡入动画持续 1 秒
- 文字停留 3 秒后从顶部滑出并淡出
- 分辨率 1920x1080，30fps

请创建组件文件并注册到 Root.tsx 中。

步骤 2：在 Studio 中预览

# 启动 Remotion Studio
npm run dev

在浏览器中打开 Studio，从侧边栏选择新创建的 Composition，播放预览效果。

步骤 3：渲染为 MP4

确认预览效果满意后，渲染为视频文件：

# 使用 CLI 渲染
npx remotion render <CompositionId> out/video.mp4
 
# 例如
npx remotion render HelloAIVideo out/hello-ai-video.mp4

首次渲染时，Remotion 会自动下载 Chrome Headless Shell（用于将 React 组件渲染为视频帧）。

步骤 4：确认输出

# 检查输出文件
ls -la out/
# 应看到 hello-ai-video.mp4
 
# （可选）用系统播放器打开
open out/hello-ai-video.mp4        # macOS
xdg-open out/hello-ai-video.mp4    # Linux
start out/hello-ai-video.mp4       # Windows

如果视频正常播放，恭喜——你的 Remotion + Claude Code + Agent Skills 环境搭建完成！

实战案例：从零搭建到第一个 AI 生成视频

场景描述

一位前端开发者想用 AI 快速制作一个产品功能介绍视频。他从未使用过 Remotion，但熟悉 React 和 TypeScript。

完整操作流程

时间线：约 30 分钟

00:00 - 05:00  安装 Node.js 22 + 确认环境
05:00 - 08:00  npx create-video@latest → 选择 Hello World 模板
08:00 - 10:00  npm run dev → 打开 Remotion Studio → 确认模板正常
10:00 - 13:00  npm install -g @anthropic-ai/claude-code → 登录认证
13:00 - 15:00  npx remotion skills add → 确认 Skills 安装
15:00 - 20:00  claude → 用自然语言描述视频需求 → AI 生成代码
20:00 - 25:00  在 Studio 中预览 → 用自然语言要求 AI 修改
25:00 - 30:00  npx remotion render → 输出 MP4 → 完成

案例分析

关键决策点：

1. 模板选择：Hello World 模板包含基础示例代码，适合首次使用者理解 Remotion 的工作方式。如果已有 React 经验且想从零开始，可选 Blank 模板。

2. Claude Code 订阅方案：学习阶段用 Pro（$20/月）足够。如果计划频繁生成视频代码，Max 5×（$100/月）更合适，避免频繁触发速率限制。

3. Skills 的价值：没有 Skills 时，Claude Code 会用通用 React 模式写代码（useState、CSS 动画），这些在 Remotion 中不工作。安装 Skills 后，Claude 会使用 useCurrentFrame()、interpolate()、spring() 等 Remotion 原生 API，生成的代码可以直接运行。

4. 渲染方式选择：本地渲染适合开发和测试（单个视频几秒到几分钟）。如果需要批量渲染或更快速度，后续可配置 Remotion Lambda（详见 12e-成本与生产部署）。

避坑指南

❌ 常见错误

1. Node.js 版本过低

   • 问题：使用 Node.js 14 或 15 会导致 Remotion 安装失败或运行时报错
   • 正确做法：使用 Node.js 16+，推荐 20 LTS 或 22 LTS。用 nvm 管理多版本

2. 在没有 Remotion 项目的目录中安装 Skills

   • 问题：Skills 安装到了错误的位置，Claude Code 无法加载
   • 正确做法：先创建 Remotion 项目（npx create-video@latest），再在项目根目录中运行 npx remotion skills add

3. 混淆 Remotion Studio 和 Remotion Player

   • 问题：Remotion Studio 是开发时的预览工具（npx remotion studio），Remotion Player 是嵌入 Web 应用的播放组件（@remotion/player）。两者用途完全不同
   • 正确做法：开发阶段用 Studio 预览和调试；需要在网页中嵌入视频播放时才用 Player

4. Claude Code 未认证就尝试使用

   • 问题：安装 Claude Code 后直接使用，但没有登录或配置 API Key，导致请求失败
   • 正确做法：首次运行 claude 时完成浏览器登录认证，或提前设置 ANTHROPIC_API_KEY 环境变量

5. 忽略 Chrome Headless Shell 依赖

   • 问题：渲染时报错”Browser not found”或类似错误
   • 正确做法：运行 npx remotion browser ensure 确保浏览器依赖已安装。在 Docker 环境中需要额外安装系统级依赖（libnss3、libgbm-dev 等）

6. Skills 过期未更新

   • 问题：Remotion 升级后 API 有变化，但 Skills 还是旧版本，导致 Claude 生成的代码使用了已废弃的 API
   • 正确做法：Remotion 升级后同步运行 npx remotion skills update

✅ 最佳实践

1. 使用 bun create video 一步到位：Bun 的脚手架会自动提示安装 Skills，省去手动步骤
2. 将 .claude/ 目录纳入 Git：Skills 文件应该随项目版本控制，确保团队成员共享相同的 AI 知识
3. 为每个项目单独安装 Skills：不同项目可能使用不同版本的 Remotion，Skills 应与项目版本匹配
4. 先跑通官方模板再自定义：确认 Studio 预览和渲染都正常后，再开始修改代码
5. 设置 CLAUDE.md 增强上下文：在项目根目录创建 CLAUDE.md，描述项目的视频风格、品牌规范、常用组件，让 Claude Code 生成更符合需求的代码
6. 使用 npx remotion browser ensure 预装浏览器：避免首次渲染时等待下载

相关资源与延伸阅读

• Remotion 官方文档 — 创建新项目  — 官方脚手架使用指南和模板说明
• Remotion Agent Skills 文档  — Skills 安装、更新和使用的官方说明
• Remotion CLI Skills 命令  — npx remotion skills 命令的完整参数说明
• Remotion AI 集成总览  — Remotion 为 AI Agent 提供的所有集成功能
• Remotion Studio 文档  — Studio 界面功能和配置选项
• Remotion 许可证说明  — 免费许可和企业许可的详细条款
• Claude Code 官方文档  — Claude Code 安装、认证和使用指南
• Remotion GitHub 仓库  — 开源代码、示例项目和社区讨论
• Remotion Docker 部署指南  — 在 Docker 容器中运行 Remotion 的完整配置
• Remotion AI SaaS 模板  — 基于 Next.js 的 AI 视频生成 SaaS 启动模板

参考来源

• Remotion Official Documentation — Creating a New Project （2026-06）
• Remotion Agent Skills Documentation （2026-06）
• Remotion CLI Skills Command Reference （2026-06）
• Remotion License & Pricing （2026-02）
• Remotion Studio Documentation （2026-03）
• How to Install Remotion Agent Skills and Verify They Work — Crepal.ai （2026-02）
• Create React Videos via Claude Code — Gaga.art （2026-06）
• Make Videos with Claude Code: Remotion AI Video — StartupHub （2026-06）
• Claude Code Pricing Explained — InventiveHQ （2026-07）
• Claude AI Pricing — ScreenApp （2026-06）
• Remotion Docker Deployment Guide （2026-06）

📖 返回 总览与导航 | 上一节：12a-代码驱动视频概念 | 下一节：12c-端到端工作流