拿到一个包含复杂CSS关键帧动画的页面，比如一个loading动效或者角色行走序列，想要把每一帧都还原成独立图片，靠肉眼观察时间轴再手动截图几乎不可能。Node.js配合Puppeteer可以很好地解决这个问题。核心思路是：先用脚本解析页面中动画的定义，提取关键帧百分比和时间点，然后控制无头浏览器跳转到对应时间点，截取指定DOM元素区域并保存为序号图片。整个过程无需人工干预，输出结果可以直接喂给后续的图像处理流水线。
这里有一个容易踩的坑：很多人一开始会想到用requestAnimationFrame在页面内循环播放并截图，但页面内的定时器精度受渲染进程影响，截图时机往往不准。更可靠的方式是由Node.js脚本直接计算关键帧对应的绝对时间，再利用Puppeteer的page.evaluate把动画的currentTime设置到目标值，强制跳帧后再截图。这样每一张图片都严格对应关键帧位置，不会出现半帧或模糊帧。
从动画定义中提取关键帧时间点
网页中的CSS动画通常通过@keyframes规则声明，每个关键帧用百分比表示进度。要从Node.js侧拿到这些次数，需要访问页面的document.styleSheets或者直接请求getComputedStyle的相关接口。最省事的做法是在页面加载完成后，在page.evaluate里遍历所有样式表，找到匹配目标元素动画名称的@keyframes规则，把百分比字符串和对应的样式块抓出来。
举例来说，假设页面上有一个.sprite元素，动画名是walk，关键帧定义如下：0% {transform: translateX(0)} 25% {transform: translateX(-50px)} 50% {transform: translateX(-100px)} 75% {transform: translateX(-150px)} 100% {transform: translateX(-200px)}。解析后可以得到关键帧百分比数组[0, 25, 50, 75, 100]，配合动画总时长（例如2秒），就能算出每个关键帧对应的毫秒时间点：0ms、500ms、1000ms、1500ms、2000ms。这些时间点就是后续截图的依据。
实际项目中动画可能写在外部CSS文件里，跨域样式表无法直接读取cssRules。解决办法是在启动Puppeteer时设置--disable-web-security参数，或者把CSS内容内联到页面里再执行。另一个技巧是用getAnimations()接口，它返回当前元素上所有活跃的Animation对象，每个对象自带effect.getKeyframes()方法，能够拿到浏览器解析后的关键帧数组，比手动解析样式表稳妥得多。推荐优先使用这个标准Web Animations API。
用Puppeteer精确控制动画时间并截图
拿到关键帧时间点后，下一步就是让页面动画停留在指定时刻。Puppeteer的page.evaluate可以在页面上下文执行任意JS代码，我们可以在里面找到目标动画对象，把它的currentTime设置为目标毫秒值，然后立刻调用page.screenshot。注意必须等待一帧渲染完成再截图，否则拿到的是上一帧的残留画面。可以在evaluate里设置完时间后返回一个Promise，配合requestAnimationFrame确保浏览器完成重绘。
下面是一段完整的Node.js脚本示例，假设动画元素选择器是#frame-box，动画时长2秒，关键帧百分比数组提前通过getKeyframes()获取：
const puppeteer = require('puppeteer');
const path = require('path');
const fs = require('fs');
(async () => {
const browser = await puppeteer.launch({ headless: 'new' });
const page = await browser.newPage();
await page.goto('file://' + path.resolve(__dirname, 'animation.html'), {
waitUntil: 'networkidle0'
});
// 获取关键帧百分比和动画总时长
const animData = await page.evaluate(() => {
const el = document.querySelector('#frame-box');
const anim = el.getAnimations()[0];
const keyframes = anim.effect.getKeyframes();
const offsets = keyframes.map(kf => kf.offset).filter(o => o != null);
const duration = anim.effect.getTiming().duration;
return { offsets, duration };
});
const outputDir = path.resolve(__dirname, 'frames');
fs.mkdirSync(outputDir, { recursive: true });
for (let i = 0; i < animData.offsets.length; i++) {
const offset = animData.offsets[i];
const timeMs = offset * animData.duration;
await page.evaluate((targetTime) => {
const el = document.querySelector('#frame-box');
const anim = el.getAnimations()[0];
anim.currentTime = targetTime;
return new Promise(resolve => requestAnimationFrame(() => resolve()));
}, timeMs);
const fileName = `frame_${String(i).padStart(3, '0')}.png`;
await page.screenshot({
path: path.join(outputDir, fileName),
clip: await page.$eval('#frame-box', el => {
const r = el.getBoundingClientRect();
return { x: r.x, y: r.y, width: r.width, height: r.height };
})
});
console.log(`已输出 ${fileName}`);
}
await browser.close();
})();
代码中clip选项用来指定截图区域，保证只截取动画元素本身，避免页面其他内容混入。如果动画元素使用了transform缩放或位移，需要额外注意getBoundingClientRect返回的是变换后的可视区域，这正是我们希望截取的部分。还要处理动画在结束时会保持最后一帧状态的情况，如果关键帧数组末尾的offset为1，截完最后一张后动画可能会停止，但不影响输出结果。
批量输出图片序列的工程化优化
对于需要频繁转换的项目，可以把上述脚本封装成一个CLI工具，接收HTML文件路径、元素选择器、输出目录等参数。另外要考虑并行动画和多个目标元素的情况：一个页面可能同时有多个动画需要提取，可以遍历document.getAnimations()并按元素分组，分别生成独立的帧序列目录。文件名可以加入动画名称前缀，避免混淆。
性能方面，一般的中等复杂度动画几十个关键帧，串行截图的耗时在数秒内。如果关键帧数量非常多，比如粒子动画有上百个关键帧，可以改用page.screenshot({ encoding: 'binary' })拿到Buffer后直接写入文件，减少磁盘IO开销。更进一步的优化是在同一个page.evaluate调用里把多个关键帧的截图任务合并，利用Puppeteer的screenshot支持连续调用的特点，但这样代码复杂度会增加，通常串行方式已经足够。
最后要提醒一点：Puppeteer依赖Chromium下载，国内网络环境可能需要设置镜像。另外动画如果使用了WebGL或Canvas渲染，page.screenshot同样能捕获到内容，但需要确保无头模式支持硬件加速（可加--use-gl=swiftshader参数）。整体方案对前端开发者来说几乎零学习成本，把Node脚本跑起来就能快速产出关键帧图片序列，值得加入日常工具链。