Remotion 写完 composition 之后,最终都要落到「渲染」这一步——把 React 组件变成 mp4、图片序列或单帧。渲染的方式不止一种:可以在 Studio 里点按钮,可以用 CLI 一条命令,也可以走 SSR、AWS Lambda,甚至塞进 GitHub Actions。
本文翻译并整理自 Remotion 官方文档的 Render your video(渲染概览)与 npx remotion render(CLI 渲染命令)两页,命令与参数按官方文档核对(更新至 2026 年 11 月)。
目录
展开目录
一、渲染方式总览
1.1 Remotion Studio
在 Remotion Studio 里点「Render」按钮,选好设置,再用「Render video」按钮确认即可。
Studio 还可以部署到云端的一台常驻服务器上,让不懂技术的团队成员只用浏览器访问一个 URL 就能渲染。做法见 Deploy the Remotion Studio。
1.2 CLI
用 render CLI 命令渲染:
npx remotion render HelloWorld
改 HelloWorld 这个 composition ID 就能渲染别的视频;末尾加一个输出路径可以覆盖默认输出。
省略 composition ID,会弹出一个选择器让你挑:
npx remotion render
1.3 SSR
Remotion 有一套完整的服务端渲染 API,详见 server-side rendering API。
1.4 AWS Lambda
云端批量渲染走 Remotion Lambda。
1.5 GitHub Actions
也可以用 GitHub Action 渲染视频。
1.6 渲染变体
| 变体 | 说明 |
|---|---|
| 纯音频 | 只导出音频,或从视频里剔除音频,见 Exporting audio |
| 图片序列 | 不编码成视频,用 --sequence 输出一串图片 |
| 静帧 | 只要单张图,用 CLI 或 Node.js API |
| GIF | 见 Render as GIF |
| 透明视频 | 见 Creating overlays |
二、CLI 渲染命令
2.1 基本用法
npx remotion render <entry-point|serve-url>? <composition-id> <output-location>
- 第一个参数可以传 Serve URL 或入口点;不传则由 Remotion 自动判断。
- 不传
composition-id,Remotion 会问你选哪个 composition。 - 不传
output-location,媒体会渲染到out文件夹。
2.2 输入参数
| 参数 | 作用 |
|---|---|
--props | 传给 composition 的输入 Props。可以是 JSON 字符串或 JSON 文件路径。Windows 命令行不支持内联 JSON 字符串(会吃掉引号),用文件代替 |
--height | 覆盖 composition 高度 |
--width | 覆盖 composition 宽度 |
--fps | 覆盖帧率(frames per second) |
--duration | 覆盖总帧数 |
2.3 编码与画质
| 参数 | 作用 |
|---|---|
--codec | 编码器:h264/h265/av1/png/vp8/vp9/mp3/aac/wav/prores/h264-mkv,默认 H.264。Linux ARM64 GNU 不支持 av1 |
--pixel-format | FFmpeg 像素格式:yuv420p/yuva420p/yuv422p/yuv444p/yuv420p10le/yuv422p10le/yuv444p10le/yuva444p10le |
--crf | 恒定质量因子(CRF),最小 0。要质量优先、不在乎体积时用。设了 --video-bitrate 就不能用它;开了硬件加速也不能设 crf |
--video-bitrate | 目标视频码率,FFmpeg -b:v 语法,如 512K、1M |
--audio-bitrate | 目标音频码率,FFmpeg -b:a 语法,默认 320k |
--x264-preset | x264 预设:superfast…veryslow…placebo,默认 medium,仅 h264 生效 |
--prores-profile | ProRes 档次:4444-xq/4444/hq/standard/light/proxy,默认 hq,仅 codec 为 prores 时有效 |
--gop | 关键帧间隔(FFmpeg -g),默认由编码器决定 |
--buffer-size | FFmpeg -bufsize 值,配合最大码率用 |
--max-rate | FFmpeg -maxrate 值,配合缓冲大小用 |
--jpeg-quality | JPEG 渲染质量 0–100,PNG 帧不生效 |
--color-space | 色彩空间:default/bt601/bt709/bt2020-ncl/bt2020-cl。追求准确建议配 png 图像格式 |
2.4 输出参数
| 参数 | 作用 |
|---|---|
--output | 输出文件路径,替代位置参数 output-location |
--overwrite | 输出文件已存在时是否覆盖,默认开启,--overwrite=false 关闭 |
--sequence | 输出图片序列而非视频,默认 JPEG 格式 |
--image-format | 帧的图像格式:png/jpeg/none,默认 jpeg(更快但不支持透明)。开启共享内存捕获后此参数失效 |
--image-sequence-pattern | 图片序列命名模板,支持 [frame](补零帧号)和 [ext](扩展名) |
--separate-audio-to | 把音频单独渲染到指定文件,不混入主输出 |
--metadata | 嵌入视频的元数据,格式 --metadata key=value,可多次传入 |
2.5 帧控制与性能
| 参数 | 作用 |
|---|---|
--frames | 渲染子集:单帧渲染成静帧,0-9 渲染一段,100- 渲染到结尾。逗号列表 0,30,60 输出指定帧为图片序列;0-99,150-199 把多段拼接成一个视频 |
--every-nth-frame | 仅渲染 GIF 时有效,隔 N 帧采样以降低 GIF 帧率 |
--scale | 输出缩放因子,1.5 把 1280×720 放大到 1920×1080,矢量元素更清晰。取值 (0, 16],默认 1 |
--concurrency | 使用的 CPU 线程数,最小 1,最大为线程总数,也支持百分比如 50% |
--disallow-parallel-encoding | 禁止「渲染帧 + 编码」并行,更省内存但可能更慢 |
--disable-shared-memory-capture | 关闭共享内存捕获,改用普通 JPEG/PNG 截图 |
--media-cache-size-in-bytes | <Video>/<Audio> 解码媒体的内存预算(字节),默认是渲染开始时系统内存的一半 |
--offthreadvideo-cache-size-in-bytes | <OffthreadVideo> 帧缓存大小,默认系统内存一半 |
--offthreadvideo-video-threads | <OffthreadVideo> 抽帧线程数,默认 2,过多可能不稳 |
2.6 浏览器与渲染引擎
| 参数 | 作用 |
|---|---|
--browser-executable | 自定义 Chrome/Chromium 可执行文件路径,默认用 Remotion 自带修复的 Chrome Headless Shell |
--chrome-mode | headless-shell(默认)或 chrome-for-testing(Linux 上用 GPU 驱动) |
--gl | OpenGL 后端:angle/egl/swiftshader/swangle/vulkan/angle-egl,默认交给 Chrome 决定 |
--hardware-acceleration | disable/if-possible/required,默认 disable。required 且无可用硬编则渲染失败 |
--disable-headless | 关闭无头模式,打开真实 Chrome 窗口看渲染过程 |
--disable-web-security | 关闭 Chrome 的 CORS 等安全特性 |
--ignore-certificate-errors | 忽略无效 SSL 证书(如自签名) |
--dark-mode | 让 Chromium 模拟 prefers-color-scheme: dark |
--user-agent | 设置自定义 UA |
--enable-multiprocess-on-linux | Linux 下移除 --single-process 提升速度(v4.0.137 起默认开启,v5.0 移除该参数) |
--preferred-effect-backend | 效果实现优先用 webgpu/webgl2/2d,默认 auto |
2.7 音频参数
| 参数 | 作用 |
|---|---|
--audio-codec | 内嵌音频的编码格式,部分组合需特定容器/扩展名 |
--muted | 关闭音频输出,仅渲染视频时可用 |
--enforce-audio-track | true 时即使无音频也加一条静音音轨(用于分块后拼接),--muted 优先 |
--sample-rate | 输出音频采样率,默认 48000 Hz,匹配源音频避免重采样失真 |
--for-seamless-aac-concatenation | 把音频裁到最近的 AAC 帧边界,便于后续无缝拼接 |
2.8 其他参数
| 参数 | 作用 |
|---|---|
--config | 指定 Remotion 配置文件位置 |
--env-file | 指定 dotenv 文件,默认 .env |
--log | 日志级别:error/warn/info(默认)/verbose |
--port | 指定 Studio/渲染进程的 HTTP 端口,不传则自动找空闲端口 |
--public-dir | bundle 托管路径,默认 ./,固定位置可设绝对路径 |
--timeout | 单帧等待所有 delayRender() 的超时毫秒数,默认 30000 |
--bundle-cache | 启用/禁用 Webpack 缓存,默认开启 |
--rspack | 用 Rspack 而非 Webpack 打包 |
--binaries-directory | Remotion 平台二进制(ffmpeg/ffprobe 等)所在目录 |
--repro | 生成可提交给 Remotion 的复现 ZIP |
--number-of-gif-loops | GIF 循环次数:null 无限循环,0 不循环,1 循环一次 |
--license-key | 授权 key,以 rm_sec_ 开头的私钥 |
--is-production | 标记为生产环境 |
--quality已在 v4.0.0 改名为--jpeg-quality。
三、几点提醒
- 不传参数就用默认:
npx remotion render什么都不带会弹选择器,是最省事的起点。 - Windows 注意:
--props内联 JSON 字符串会被 shell 吃掉引号,改用 JSON 文件路径。 - 码率与 CRF 二选一:
--video-bitrate和--crf不能同时设置;开硬件加速也不能用 crf。 - 透明视频:要透明就选
png图像格式或带 alpha 的编码,JPEG 不支持透明。 - 只看一小段:用
--frames渲染子集,比全量渲染快得多,调试时尤其有用。