Remotion 项目脚手架工具 create-video 完全指南：从零创建、模板选型到 CLI 源码解析

本篇指南围绕 Remotion 官方脚手架包 create-video（即 @remotion/create-video，README 位于 packages/create-video/README.md）展开。你将从"如何安装并启动一个全新 Remotion 项目"出发，系统掌握交互式与非交互式两种创建方式、全部内置模板的适用场景，以及该工具在仓库中从参数解析、模板拉取到版本对齐、Git 初始化的完整实现链路。读完即可像官方 CLI 一样精确地批量生成视频项目，并理解其底层行为以便二次定制或排查问题。

create-video 是什么

在 Remotion 官方 monorepo（根目录 package.json）中，create-video 是一个只承担"创建新项目"这一单一职责的包，package.json 中的描述是 "Create a new Remotion project"，并对外暴露了 create-video 可执行命令（"bin": { "create-video": "bin.js" }）。

值得注意的一个设计细节：这个包本身没有程序化 API 可供调用。入口文件 的默认导出直接抛错，提示用户改为运行 npx create-video@latest、pnpm create video 或 yarn create video；同时 index.ts 也导出了 CreateVideoInternals（内含 FEATURED_TEMPLATES 与 listOfRemotionPackages）以及 Template 类型，供 Remotion 内部与周边工具复用模板元数据。真正的入口是 bin.js：它以 Node shebang 启动后 require('./dist/init') 并调用 init()，成功退出码为 0，出错则打印错误并以 1 退出。

安装 create-video

按官方 README 的说明，可将 create-video 作为依赖安装：

npm install create-video --save-exact

--save-exact 会去掉版本号前的 ^，写入精确版本号。这一点对 Remotion 生态尤其重要：

When installing a Remotion package, make sure to align the version of all remotion and @remotion/* packages to the same version. Remove the ^ character from the version number to use the exact version.

即 所有 remotion 与 @remotion/* 相关包的版本必须保持一致，不要使用 ^ 允许漂移。仓库中 set-version.ts 与各包通过 workspace 统一版本的管理方式也印证了这一点——Remotion 的渲染器、播放器、CLI 等模块对版本一致性非常敏感。

不过在实际工作流中，create-video 更常见的用法是"即取即用"的脚手架命令，无需先装为本地依赖，index.ts 里就给出了三种官方推荐入口：

npx create-video@latest      # npm / 通用
pnpm create video            # pnpm
yarn create video            # yarn

基础用法：交互式创建

在不带任何参数运行时，create-video 会以交互式向导的方式逐步引导你完成创建。完整流程实现于 src/init.ts，大致经历以下步骤：

1. 打印欢迎信息 Welcome to Remotion!；
2. 弹出模板选择列表（每页最多展示 20 项，由 select-template.ts 中的 selectAsync 实现），每项附带短名、描述以及可点击的 (?) 帮助链接；
3. 提示输入目标目录（默认值 my-video）；
4. 交互询问是否 Add TailwindCSS?（仅当所选模板允许启用 Tailwind 时，见 ask-tailwind.ts，默认 Yes）；
5. 询问是否需要安装 Skills（Agent/LLM 辅助技能包，见 ask-skills.ts）；
6. 自动探测你正在使用的包管理器，据此生成对应的后续命令提示；
7. 克隆模板、做版本与名称修补、按需初始化 Git，最后打印"接下来运行什么"的完整指引（详见下文"创建后的收尾"）。

在交互过程中若处于一个非空目录，resolve-project-root.ts 会报错 Something already exists at "..." 并提示换一个新目录名或移走现有文件。

目录解析的智能行为

resolve-project-root.ts 展示了目标目录的解析优先级：

• 若传了目录位置参数，直接用该参数（并会剥离控制字符）；
• 若带 --tmp，则在系统临时目录生成 remotion-video-<随机串> 并直接使用；
• 若当前目录恰好为空且创建时间在一小时以内，create-video 会认为你刚 mkdir 并 cd 进来，从而直接在当前目录创建项目；
• 否则弹出文本输入框询问目录名。

目录名会经过 validate-name.ts 校验：项目名不能为空，且只能包含 URL 友好的字符（字母数字以及 @ . - _）。

非交互式用法：CLI 参数速查

脚本化、CI 或需要可重复执行的场景使用非交互模式。完整的帮助文本生成逻辑在 src/help.ts，核心用法与参数如下：

npx create-video --yes --blank my-video
npx create-video [options] [directory]

位置参数

参数	说明
directory	项目创建的目标目录

选项

选项	说明
--yes, -y	启用非交互模式。必须同时指定一个模板 flag 和目录（除非使用 --tmp）
--no-tailwind	与 --yes 配合时跳过 TailwindCSS 的安装
--tmp	在临时目录中创建项目
--help, -h	打印帮助信息

模板则通过 --<cliId> 形式的 flag 指定（与 select-template.ts 中 minimist 的 boolean 声明一一对应）。

模板 flag 全列表

根据 templates.ts 中 FEATURED_TEMPLATES 与 PAID_TEMPLATES 的 cliId 字段，可用的模板 flag 如下：

--blank                    --hello-world
--next                     --next-no-tailwind
--next-pages-dir           --vercel
--recorder                 --prompt-to-motion-graphics
--javascript               --render-server
--electron                 --react-router
--three                    --still
--audiogram                --music-visualization
--prompt-to-video          --skia
--overlay                  --code-hike
--stargazer                --tiktok

其中 editor-starter 是付费模板（PAID_TEMPLATES），在交互列表中会被标注 (Paid)；一旦选中，init.ts 会打印提示信息与购买页并直接退出，不会执行克隆。

参数之间的约束关系

• 使用 --yes 但未提供目录且未加 --tmp：报错退出，提示示例 --yes --blank my-video；
• 使用 --yes 但未指定模板：抛错 "A template must be specified when using --yes"；
• --yes 对 Tailwind 的默认策略是"启用"（allowEnableTailwind 的模板会加装 TailwindCSS），如需跳过必须显式追加 --no-tailwind；
• 交互模式下，如果你正位于某个 Git 仓库内且未传 --yes，会弹出确认框询问是否继续（因为新项目将不会再次初始化 Git 仓库）。

模板全景：从空画布到 SaaS 生成器

模板元数据全部集中在 src/templates.ts。每条 Template 记录包含 shortName、description、cliId、org/repoName（对应 GitHub 上的模板仓库）、templateInMonorepo（对应本仓库 packages/ 内的目录）、allowEnableTailwind、previewURL、contributedBy 等字段。下表汇总了各模板在本仓库对应的实体目录：

CLI flag	场景定位	本仓库对应模板
--blank	纯空画布，适合已有经验或打算用 AI 写代码的用户	packages/template-blank
--hello-world	预置 TypeScript + Prettier + ESLint 的基础动画练习场	packages/template-helloworld
--javascript	Hello World 的纯 JS 版本	packages/template-javascript
--next	内置 Remotion Player 与 Lambda 渲染的 Next.js App Router SaaS 套件	packages/template-next-app-tailwind
--next-no-tailwind	同上但不含 Tailwind	packages/template-next-app
--next-pages-dir	使用 Next.js Pages Router 的 SaaS 套件	packages/template-next-pages
--vercel	通过 Vercel Sandbox 按需渲染视频，输出存 Vercel Blob	packages/template-vercel
--react-router	基于 React Router 7 的 SaaS 视频生成套件	packages/template-react-router
--recorder	纯 JavaScript 的视频制作工具（录屏/摄像头 + 字幕 + 音乐）	packages/template-recorder
--prompt-to-motion-graphics	面向 AI 动效生成的 SaaS 模板（流式输出代码并浏览器内编译预览）	packages/template-prompt-to-motion-graphics
--prompt-to-video	从提示词生成带脚本、图片与配音的短视频（OpenAI + ElevenLabs）	packages/template-prompt-to-video
--render-server	提供 Express.js 服务来启动/追踪/取消渲染	packages/template-render-server
--electron	Electron Forge + Vite 桌面应用内渲染视频	packages/template-electron
--three	React Three Fiber 3D 场景	packages/template-three
--still	动态 PNG/JPEG 静态图，内置可部署 HTTP 服务	packages/template-still
--audiogram	播客音频片段的文字 + 波形可视化短视频	packages/template-audiogram
--music-visualization	音乐片段的波形可视化视频	packages/template-music-visualization
--skia	预配置 React Native Skia	packages/template-skia
--overlay	供传统剪辑软件使用的透明 Overlay 素材	packages/template-overlay
--code-hike	基于 Code Hike 的代码动画（多语言 + TS 错误标注）	packages/template-code-hike
--stargazer	仓库 Star 里程碑庆祝视频（社区贡献，pomber）	packages/template-stargazer
--tiktok	逐词动画字幕，自动安装 Whisper.cpp 转写	packages/template-tiktok

说明：templates.ts 中的 repoName（GitHub 仓库名）与 templateInMonorepo（本仓库目录名）并不总是一致。例如 blank 对应的 GitHub 仓库是 remotion-dev/template-empty，而本仓库中的同名模板位于 packages/template-blank。上表展示的是本仓库可直接阅读源码的对应目录。

此外 recorder、prompt-to-motion-graphics、stargazer 等模板标注了非官方贡献者（contributedBy），说明模板生态本身是开放协作的；prompt-to-motion-graphics 等还通过 promoBanner/promoVideo 字段（muxId、宽高）驱动官方站点与选择器中的预览媒体。

创建后的收尾：版本对齐、Tailwind、Git 与运行指引

模板克隆完成后，init.ts 会执行一系列"修补"，这是 create-video 最体现工程细节的部分。

1) 从 GitHub 拉取模板归档

模板拉取没有引入 degit 依赖，而是由 degit.ts 自实现：直接请求 https://github.com/<org>/<repo>/archive/HEAD.tar.gz，跟随 3xx 重定向写入临时目录，再用 tar 解压并 strip: 1 去掉顶层目录。缓存位于系统临时目录的 .degit/<org>/<repo>/ 下。

2) 实时查询 npm 上最新的 Remotion 版本

latest-remotion-version.ts 会先通过 npm config get registry 探测当前 registry（默认 https://registry.npmjs.org），随后请求该 registry 下 remotion 包的元数据，读取 dist-tags.latest。请求失败时不会中断流程，而是以 create-video 自身版本作为 fallback 并打印警告（init.ts 中以 onError: Log.warn 接入）。

3) 修补 package.json

patch-package-json.ts 完成四件关键工作：

• 把项目 name 改为你输入的目录名；
• 遍历 dependencies 与 devDependencies，凡是命中 list-of-remotion-packages.ts（该文件注明了由 package-sync.test.ts 生成，包含 remotion 及全部 @remotion/* 官方包）的依赖，统一替换为刚查询到的最新精确版本——这正是 README 中"所有 Remotion 包必须同版本"落地的机制；
• 若使用 Bun 安装，脚本中的 remotion 命令会被替换为 remotionb（Bun 专用二进制，防止与同名依赖包冲突）；
• 若同时启用了 Tailwind，则追加 @remotion/tailwind-v4 与 tailwindcss: 4.0.0 依赖，并写入 sideEffects: ['*.css']。

该函数支持注入 getPackageJson/setPackageJson 以便测试，对应的测试见 packages/create-video/src/test/patch-package-json.test.ts。

4) 其他收尾动作

• 依据所选模板与包管理器重写 README（patchReadmeMd）；
• 允许 Tailwind 的模板默认启用时调用 add-tailwind.ts 追加根 CSS 与 remotion 配置（Tailwind v4 方式）；
• 创建 public/ 静态资源目录（create-public-folder.ts）；
• Yarn 2+ 用户会被写入 .yarnrc.yml，内容为 nodeLinker: node-modules，以规避 Remotion 尚未支持的 Yarn PnP（见 add-yarn2-support.ts）；
• 若不在已有 Git 仓库内，则自动 git init → git add --all → 提交 "Create new Remotion video" → 分支改名 main（init.ts）；若 Git 未安装则直接报错退出；
• 若选择了 Skills 且处于交互模式，调用 install-skills.ts 安装技能包。

5) 按包管理器输出运行指引

create-video 会通过环境变量探测你实际使用的包管理器（npm / yarn / pnpm / bun / nub），探测逻辑位于 pkg-managers.ts：通过 npm_config_user_agent、npm_execpath、.pnpm 路径特征、bun 路径等判断。随后打印形如下的指引：

Copied to my-video.
Get started by running:
  cd my-video
  npm i
  npm run dev
To render a video, run:
  npx remotion render

npm run dev/npx remotion render 在 pnpm/bun/yarn 下会分别映射为 pnpm run dev/pnpm exec remotion render、bun run dev/bunx remotion render 等（各包管理器的安装、运行、渲染、升级命令矩阵都在 pkg-managers.ts 中集中定义）。注意：对 next、next-no-tailwind、next-pages-dir、react-router 这类应用型模板，开发命令用的是 run dev 而非 npm run dev 的单脚本形式。

非交互模式（--yes）下流程到此结束；交互模式最后还会询问是否要用已安装的编辑器打开项目（open-in-editor-flow.ts）。

从模板到源码：仓库内的可运行示例

如果你希望直接阅读或对照某个模板的最终形态，而不经过脚手架拉取，本仓库 packages/ 下提供了全套与模板一一对应的实体项目（目录列在上表）。例如：

• packages/template-blank 的结构最简，能直观看到 Remotion 项目的最小文件组成（remotion.config.*、tsconfig.json、src/index.ts 注册 Composition 等）；
• packages/template-helloworld 与 packages/template-javascript 可对比 TS/JS 两种形态的差异；
• packages/template-tiktok 展示了本地字幕工作流（自动安装 Whisper.cpp）的完整落地；
• 对 SSR/SaaS 方向感兴趣的读者，可直接阅读 packages/template-next-app-tailwind 与 packages/template-render-server。

测试与可维护性

create-video 的关键逻辑均有测试覆盖，位于 packages/create-video/src/test/：

• help.test.ts：校验帮助文本与模板 flags 的输出；
• latest-remotion-version.test.ts：验证 registry 探测、版本解析与失败回退；
• patch-package-json.test.ts：验证 Remotion 依赖版本对齐、Tailwind 依赖注入、Bun 下 remotionb 脚本替换等行为；
• pkg-managers.test.ts：验证各包管理器命令矩阵；
• resolve-project-root.test.ts 与 git-status.test.ts：验证目录解析与 Git 初始化分支行为；
• add-tailwind.test.ts：验证 Tailwind 配置注入。

包本身的工程配置同样完整：package.json 声明了 bun test src 测试脚本、tsgo/bundle.ts 构建流程以及兼容 require/import 的 exports 映射；dist/ 产物路径、ESM/CJS 双形态都是标准 Remotion 包结构。如果你要修改或扩展模板列表，只需改动 templates.ts 中的 FEATURED_TEMPLATES（确保仓库存在、字段齐全并保持本仓库版本一致即可），无需改动核心流程代码。

小结

从使用角度，create-video 与模板相关的常规用法一句话可概括为：交互模式直接运行 npx create-video@latest 并按向导选择；CI/脚本场景运行 npx create-video --yes <--template> <directory>，必要时加 --no-tailwind 或 --tmp。从实现角度，它的本质是一个"模板下载器 + 项目修补器"：通过 degit.ts 拉取 GitHub 模板归档，再依据实时查询到的最新 Remotion 版本对 package.json 做统一精确锁版（remotionb 处理、Tailwind 注入），随后完成 README 重写、public/ 创建、Yarn PnP 规避与 Git 初始化，最后按当前包管理器输出可直接照做的启动与渲染命令。理解这套流程后，无论是排查"为什么帮我改了版本号"、"为什么不给我建 Git 仓库"，还是想为团队定制自己的项目生成器，都能在 packages/create-video/src/ 中找到对应答案。