webreel

webreel

webreel 可将脚本化的浏览器演示录制为 MP4、GIF 或 WebM，并添加光标动画、按键叠加效果和音效。你可以在 JSON 配置中定义步骤，webreel 会驱动无头 Chrome、捕获帧并使用 ffmpeg 编码。

安装

将 webreel 安装为项目依赖，以便在锁定文件中固定版本。这样可以确保在不同机器和 CI 环境中录制结果一致。

npm install webreel

如果项目依赖中已经包含 webreel，请跳过此步骤。

先决条件

webreel 需要 Chrome 和 ffmpeg，但不需要手动安装。如果尚未安装，两者都会在首次运行时自动下载到 ~/.webreel。不要通过 puppeteer、playwright 或其他工具安装 Chrome 或 Chromium。webreel 会管理自己的浏览器。

如需显式下载依赖项，或修复损坏或故障的二进制文件：

npx webreel install
npx webreel install --force   # delete cached binaries and re-download

如需覆盖自动下载的二进制文件，请设置以下环境变量：

• CHROME_PATH - Chrome 或 Chromium 二进制文件的路径（用于预览）
• CHROME_HEADLESS_PATH - chrome-headless-shell 二进制文件的路径（用于录制）
• FFMPEG_PATH - ffmpeg 二进制文件的路径

如果录制时出现“找不到可检查的目标”或类似的浏览器错误，问题几乎肯定出在 webreel 配置中（waitFor 错误、缺少元素、时序问题），而不是缺少浏览器。请检查配置并使用 --verbose 进行调试。

.gitignore

录制期间会在项目根目录创建 .webreel 目录（包含帧和中间文件）。请将其添加到 .gitignore：

.webreel

快速开始

# Scaffold a config
npx webreel init --name my-demo --url https://example.com

# Edit webreel.config.json with your steps

# Preview in a visible browser (no recording)
npx webreel preview my-demo

# Record the video
npx webreel record my-demo

当 webreel 位于 devDependencies 中时，npx 会使用本地安装的版本。默认情况下，输出会保存到 videos/（可通过 outDir 配置）。

CLI 命令

init

创建新的 webreel.config.json 框架。

webreel init
webreel init --name login-flow --url https://myapp.com
webreel init --name hero -o hero.config.json

标志：--name（视频名称）、--url（起始 URL）、-o, --output（输出文件路径）。

record

录制一个或多个视频。

webreel record                        # all videos in config
webreel record hero login             # specific videos by name
webreel record -c custom.config.json  # custom config path
webreel record --watch                # re-record on config change
webreel record --verbose              # log each step
webreel record --dry-run              # print resolved config only
webreel record --frames               # save raw JPEGs to .webreel/frames/

preview

在可见的浏览器中运行步骤，但不进行录制。

webreel preview
webreel preview hero --verbose

composite

将叠加效果（光标、HUD、音效）重新应用到现有的原始视频，无需重新录制。适用于调整主题设置。

webreel composite
webreel composite hero

install

将 Chrome 和 ffmpeg 下载到 ~/.webreel。也可用此命令修复损坏或故障的二进制文件。

webreel install
webreel install --force  # delete cached binaries and re-download

validate

检查配置是否存在错误，但不运行任何内容。

webreel validate
webreel validate -c custom.config.json

配置结构

配置文件会自动发现，文件名为 webreel.config.json（或 .ts、.mts、.js、.mjs）。使用 -c 指定自定义路径。

顶层字段

字段	默认值	描述
$schema	-	"https://webreel.dev/schema/v1.json"
outDir	"videos/"	渲染后视频的输出目录
baseUrl	""	添加到相对视频 URL 前面的基础 URL
viewport	1080x1080	默认视口 { width, height }
theme	-	光标和 HUD 叠加主题
sfx	-	音效设置
include	-	要添加到所有视频前面的步骤文件路径数组
defaultDelay	-	每个步骤后追加的默认延迟（ms）
clickDwell	-	点击前光标的停留时间（ms）

单个视频字段

videos 映射中的每个条目都支持以下字段：

字段	默认值	描述
url	必填	要打开的 URL（绝对路径，或相对于 baseUrl 的路径）
viewport	继承	覆盖视口 { width, height }
zoom	-	CSS 缩放系数
waitFor	-	开始执行步骤前要等待的选择器或文本
output	"<name>.mp4"	输出路径（.mp4、.gif、.webm）
thumbnail	{ time: 0 }	缩略图配置，或 { enabled: false }
include	继承	要置于开头的步骤文件
theme	继承	覆盖主题
sfx	继承	覆盖音效
defaultDelay	继承	覆盖默认延迟
clickDwell	继承	覆盖点击停留时间
fps	60	帧率
quality	80	编码质量（1-100）
steps	必填	步骤对象数组

视频映射

配置中按名称为视频指定键：

{
  "videos": {
    "hero": { "url": "...", "steps": [...] },
    "login": { "url": "...", "steps": [...] }
  }
}

按名称录制特定视频：webreel record hero login。

步骤类型

每个步骤都有一个 action 字段。大多数步骤都可选用 label、delay（步骤执行后的毫秒数）和 description 字段。

操作	关键字段	用途
pause	ms	等待指定时长
click	text 或 selector、within、modifiers	点击元素
type	text、selector、within、charDelay	在输入框中输入文本
key	key、target	按下组合键（例如 "cmd+s"）
drag	from、to（元素目标）	在两个元素之间拖动
scroll	x、y、selector	滚动页面或元素
wait	selector 或 text、timeout	等待元素出现
moveTo	text 或 selector、within	将光标移至元素
navigate	url	导航到新的 URL
hover	text 或 selector、within	将鼠标悬停在元素上
select	selector、value	选择下拉菜单中的值
screenshot	output	截取 PNG 屏幕截图

有关每种步骤类型的完整字段详情，请参阅 steps-reference.md。

元素定位

许多步骤使用以下字段定位元素：

• text - 按可见文本内容匹配
• selector - 按 CSS 选择器匹配
• within - 将搜索范围缩小至与此 CSS 选择器匹配的父元素

可以使用 text 或 selector（不能同时使用）。within 为可选项，用于限定搜索范围。

{ "action": "click", "text": "Submit" }
{ "action": "click", "selector": "#submit-btn" }
{ "action": "click", "text": "Submit", "within": ".modal" }

视口预设

将预设名称作为 viewport 的字符串值使用，或指定 { width, height }：

desktop（1920x1080）、desktop-hd（2560x1440）、laptop（1366x768）、macbook-air（1440x900）、macbook-pro（1512x982）、ipad（1024x1366）、ipad-pro（834x1194）、ipad-mini（768x1024）、iphone-15（393x852）、iphone-15-pro-max（430x932）、iphone-se（375x667）、pixel-8（412x915）、galaxy-s24（360x780）。

主题

自定义光标外观和按键 HUD：

{
  "theme": {
    "cursor": {
      "image": "./cursor.svg",
      "size": 32,
      "hotspot": "center"
    },
    "hud": {
      "background": "rgba(30, 41, 59, 0.85)",
      "color": "#e2e8f0",
      "fontSize": 48,
      "fontFamily": "\"SF Mono\", monospace",
      "borderRadius": 12,
      "position": "top"
    }
  }
}

• cursor.image - 自定义光标 SVG 或 PNG 的路径
• cursor.size - 光标尺寸，单位为像素
• cursor.hotspot - "top-left"（默认值）或 "center"
• hud.position - "top" 或 "bottom"

常见模式

通过 include 共享步骤

将可复用的步骤序列（例如关闭 Cookie 横幅）提取到 JSON 文件中：

// steps/dismiss-banner.json
{
  "steps": [
    { "action": "wait", "selector": ".cookie-banner", "timeout": 5000 },
    { "action": "click", "selector": ".accept-btn", "delay": 300 }
  ]
}

在配置中引用它们：

{
  "include": ["./steps/dismiss-banner.json"],
  "videos": { ... }
}

在一个配置中录制多个视频

在 videos 映射中定义多个视频。共享设置（viewport、theme、defaultDelay）会从顶层继承。

环境变量

配置值支持从环境变量替换 $VAR 和 ${VAR}。

输出格式

设置 output 扩展名以控制格式：.mp4（默认值）、.gif、.webm。

{ "output": "demo.gif" }

提示

• 始终为视频设置 waitFor，确保页面准备就绪后再运行步骤。
• 使用单个步骤上的 delay 控制操作之间的节奏。
• 开发时使用 --watch，在配置发生更改时自动重新录制。
• 使用 composite 迭代主题和叠加层设置，无需重新录制。
• 使用 --verbose 调试步骤执行过程。
• 使用 --dry-run 检查完全解析后的配置（包括 include、环境变量和默认值）。
• 使用 zoom 放大小型 UI，提升录制内容的可读性。
• 先使用 preview 确认步骤正常运行，再提交完整录制。

参考文件

• steps-reference.md - 12 种步骤类型的详细文档
• examples.md - 常见用例的配置示例及注释