企业官网建设流程全解析

webreel是一个开源的浏览器演示视频录制工具，它的 webreel CLI 只需一个 JSON 配置文件，就能驱动无头 Chrome 自动点击、输入、拖拽、滚动页面，并以约 60fps 截图合成，自动生成带鼠标动画、按键 HUD 和音效的 MP4 / GIF / WebM 演示视频。本文一次讲透init、record、preview、composite四大核心命令，外加validate与install两个辅助命令，帮你从配置到成片完整跑通 webreel 录制流程。

快速安装与前置条件

只需 Node.js v18+，webreel 会在首次运行时自动下载 Chrome 与 ffmpeg 到~/.webreel目录：

npm install webreel

如果你希望提前预装依赖或修复损坏的二进制，可手动执行webreel install（后文详述）。

💡 整个 webreel 的工作流可以概括为一句话：写配置 → 预览调试 → 录制 → 合成。四个核心命令各占一环。

webreel init：一键生成配置文件

init是起点。它会脚手架式地生成一份带注释的webreel.config.json，模板中已包含输出目录、默认延迟和示例步骤，改几个字段就能直接录制：

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

生成的配置大致如下，steps数组就是"脚本化演示"的核心——按顺序执行的点击、按键、暂停等动作：

{ "videos": { "VIDEO_NAME": { "url": "VIDEO_URL", "viewport": { "width": 1920, "height": 1080 }, "steps": [ { "action": "pause", "ms": 500 }, { "action": "click", "text": "Get Started" }, { "action": "key", "key": "mod+a", "delay": 1000 } ] } } }

完整模板见 init.ts，一份最小可用的真实配置可参考 webreel.config.json。

webreel record：核心命令，产出演示视频

record是整条链路的发动机：它读取配置、启动无头 Chrome、逐步执行动作并录制，最终用 ffmpeg 编码输出视频文件（默认写入videos/<name>.mp4）：

webreel record # 录制配置中的全部视频 webreel record hero login # 只录制指定名称的视频 webreel record -c custom.config.json

几个实用技巧：

• 先--dry-run再录：不启动浏览器就能看到最终解析出的配置和逐步脚本，快速排查"我到底会执行哪些步骤"。
• --watch迭代调参：开发阶段边改配置边自动重录，适合反复微调delay与viewport。
• 一份配置多个视频：在videos下定义多个条目即可，record会逐个输出，参考 multi-demo/webreel.config.json 中一个页面生成 homepage / features / pricing 三条视频的做法。

录制时，原始录屏还会被保留在.webreel/raw/，动作时间轴数据保存在.webreel/timelines/——这正是后面composite命令的基础。

webreel preview：不录制的实时预览调试

调好步骤之前，没人想反复跑完整录制。preview会在可见的浏览器窗口里按脚本执行动作，你可以肉眼检查：点击有没有落在正确元素上、等待时机对不对、滚动位置是否合适——全程不产生视频文件：

webreel preview # 预览配置中的第一个视频 webreel preview hero # 预览指定视频 webreel preview -c custom.config.json hero

如果视频名不存在，会提示Video "xxx" not found. Available: ...，列出所有可用名称，方便快速定位拼写问题。实现见 preview.ts。

webreel composite：不重新录制的重新合成

这是 webreel CLI 中最省时间的命令。由于record阶段已把原始录屏（.webreel/raw/<name>.mp4）和时间轴数据（.webreel/timelines/<name>.timeline.json）分开保存，当你只想调整以下效果时，无需再开浏览器重录：

• 光标覆盖层样式（图片、大小、热区）
• 按键 HUD 外观（颜色、字号、位置）
• 音效配置

直接重新合成即可：

webreel composite # 重新合成全部视频 webreel composite hero login # 只合成指定视频 webreel composite -c custom.config.json

典型场景：你录完一条 3 分钟的演示，发现默认光标太刺眼，在配置里加上theme.cursor自定义光标图片后，跑一次composite就能得到新成片——浏览器操作完全不用重跑。若找不到原始数据，命令会明确报错Run "webreel record" first，提示先录制。实现见 composite.ts。

辅助命令：validate 与 install

validate：不运行配置先查错

webreel validate webreel validate -c custom.config.json

对 JSON 配置做语法 + Schema 校验，错误信息会带行号定位，把问题拦在录制之前。适合提交代码前检查，或配合 CI 使用。

install：预装 / 修复依赖

webreel install webreel install --force

下载三个组件到~/.webreel：headless Chrome（录制用）、完整版 Chrome（preview 用）、ffmpeg。--force会删除缓存并重新下载，专治二进制损坏。如果你通过环境变量CHROME_PATH、CHROME_HEADLESS_PATH、FFMPEG_PATH指定了外部二进制，对应组件会自动跳过。实现见 install.ts。

推荐工作流：四步产出专业演示视频

1. webreel init— 生成带注释的配置文件，填入 URL 与步骤；
2. webreel preview— 肉眼调试步骤落点与节奏；
3. webreel record— 正式录制，输出 MP4/GIF/WebM 与缩略图；
4. webreel composite— 调整主题、HUD、音效后秒级重新合成。

中途随时用validate体检配置，依赖异常时用install --force一键修复。

相关源码与资料

掌握以上六个命令，你就掌握了 webreel CLI 的全部能力：用init起稿、preview调试、record录制、composite精修，再配上validate和install兜底，一套浏览器演示视频生产线就此成型。