puppeteer 是录制 html 动画为视频最稳方案，需正确配置 headless 模式、等待元素挂载、禁用滚动、强制图层合成、手动控制 canvas 帧节奏，并用 ffmpeg 修复帧率与时间戳问题。
用 Puppeteer 录制 HTML 动画为视频最稳
Chrome/Chromium 内核能真实还原 CSS 动画、Canvas 渲染和 requestAnimationFrame 行为，Puppeteer 是目前最可控的方案。别指望纯前端 JS 库（比如 gif.js）能准确捕获带时间轴、transform、filter 或 WebGL 的动画。
常见错误现象：Puppeteer.launch() 启动后页面空白、动画卡顿、录出黑屏——多半是没等动画元素挂载或没禁用自动暂停策略。
- 必须在
page.goto()后加await page.waitForSelector('.anim-target')，不能只靠waitUntil: 'networkidle0' - 启动时传
{ headless: 'new', args: ['--no-sandbox', '--disable-gpu'] }，旧版headless: true在新版 Chromium 里会丢帧 - 录制前执行
await page.evaluate(() => { document.body.style.overflow = 'hidden'; })，防滚动抖动干扰帧率 - 用
page.video.startRecording()（需启用video: true），别用截图轮询 + FFmpeg 拼接——后者时间精度差、CPU 占用高
FFmpeg 命令行补救：当 Puppeteer 录不出声或分辨率错
Puppeteer 默认录的是无音频的 WebM，且帧率固定为 30fps，不匹配源动画节奏时会出现快放或卡顿。这时得用 FFmpeg 重封或重采样。
典型问题：Invalid data found when processing input（WebM 文件损坏）、Non-monotonous DTS（时间戳乱序）、输出 MP4 后动画变慢。
立即学习“前端免费学习笔记（深入）”；
- 修复 WebM 时间戳：用
ffmpeg -i input.webm -c copy -fflags +genpts fixed.webm - 强制匹配源动画帧率（比如源是 60fps）：加
-r 60参数，如ffmpeg -i input.webm -r 60 -c:v libx264 output.mp4 - 加音频需先单独录音轨（如用
MediaRecorder输出 WAV），再用-i audio.wav -c:a aac合并 - 分辨率不对？不是改
-s，而是确保 Puppeteer 启动时设了defaultViewport: { width: 1920, height: 1080 }
CSS 动画导出失败的三个隐藏原因
不是所有 @keyframes 都能被 Puppeteer 视频录制捕获。关键在“是否触发了合成层”和“是否被浏览器优化掉”。
现象举例：文字淡入正常，但 transform: scale() 动画录出来是静止缩放后的终态；或者整个动画段直接跳过。
- 加
will-change: transform到动画元素，强制创建独立图层（否则 Chrome 可能复用上一帧纹理） - 避免用
animation-fill-mode: forwards+opacity: 0起始态——Puppeteer 可能截到透明帧，导致首帧丢失 - 不要依赖
:hover或:focus触发动画——headless 环境无鼠标事件，得用page.hover()或page.focus()显式触发
Canvas 动画要手动控制帧节奏
requestAnimationFrame 在 headless 模式下默认按系统时间走，不是按动画逻辑时间。Canvas 动画常因此加速、跳帧或提前结束。
错误做法：直接录 canvas 元素，指望 Puppeteer 自动同步；正确做法是接管帧生成时机。
- 把动画逻辑从
requestAnimationFrame改成setInterval+ 固定毫秒间隔（如setInterval(draw, 1000 / 60)） - 在 Puppeteer 中注入脚本，用
page.evaluate(() => { window.__ANIM_RUNNING = true; })控制启停，比监听 DOM 更可靠 - 若用 Three.js，务必调用
renderer.setAnimationLoop(null)，否则录屏时可能持续渲染空帧 - 导出前加
await page.waitForTimeout(100)，等最后一帧真正绘制完成再 stopRecording
