1. 项目概述：什么是 hyperframes？它不是“超帧”，而是前端动效的新范式
“hyperframes”这个词最近在前端圈子里突然冒出来，很多人第一反应是——这该不会是某种视频编解码里的“超分辨率帧预测”或者“高帧率渲染优化技术”吧？其实完全不是。我最早在 GitHub 上看到它，是在一个不到 200 行的 CLI 工具仓库里，README 第一行写着：“A lightweight HTML/CSS frame sequencer for declarative motion — no JavaScript required.”。当时我就愣住了：纯 HTML + CSS 实现帧序列控制？还能“声明式”？这和我们熟悉的<video>标签、<canvas>动画、甚至 CSS@keyframes都不在一个设计思路上。
简单说，hyperframes 是一种用 HTML 结构定义动画时序、用 CSS 控制视觉状态、用 CLI 工具批量生成/校验/打包的轻量级动效组织范式。它不依赖 JS 运行时，不引入框架，不打包 bundle，甚至连requestAnimationFrame都不碰。它的核心思想很朴素：把“一串连续变化的画面”拆解成一组语义化的 HTML 元素（比如<frame id="intro-01">、<frame>{ "name": "ripple", "frames": [ {"id": "0", "opacity": 0, "scale": 0.2}, {"id": "1", "opacity": 0.8, "scale": 0.6}, {"id": "2", "opacity": 0.3, "scale": 1.2} ] }
但实际落地时全垮了。原因很简单：JSON 是数据，不是界面。当产品说“第二帧的涟漪要再大一点”，设计师给的是新 PNG，而 JSON 里scale: 0.6这个数字和图片之间没有绑定关系。下次切图换尺寸，这个值就失效了。而 hyperframes 强制用 HTML 元素承载帧：
<div class="ripple-container"> <frame id="ripple-0"># 1. 初始化项目（自动创建目录结构、基础 HTML 模板） hyperframes init hero-intro # 2. 注入 MP4（自动抽帧、重命名、生成帧清单 JSON） hyperframes import ./design/hero-intro.mp4 --fps=12 # 3. 生成可部署包（HTML+CSS+PNG+manifest.json） hyperframes build --output ./dist/hero-intro/关键在于第 2 步：CLI 不仅抽帧，还会分析 MP4 的关键帧（I-frame）分布，优先选取 I-frame 对应的 PNG，确保首帧加载不花屏；同时生成frames-manifest.json，记录每帧的精确时间戳、尺寸、哈希值，供后续 CI 流程校验资产完整性。这才是工程化的核心——不是省几行代码，而是消灭人肉操作带来的不确定性。
3. 核心细节解析与实操要点：从 MP4 到可交互帧序列的完整链路
3.1 帧命名规范：为什么必须带语义前缀，且禁止纯数字？
这是我在 3 个项目中踩出的血泪教训。最初我们按 FFmpeg 默认规则命名：frame-001.png,frame-002.png… 看似整洁，但很快暴雷：
- 问题1：多动效混杂时无法区分归属
一个页面有“按钮涟漪”、“图片悬停放大”、“加载旋转”三个动效，全用frame-001.png，文件系统直接冲突； - 问题2：Git Diff 失效
git diff显示 “frame-001.png已修改”，但你不知道这是哪个动效的哪一帧，得打开图片逐个比对； - 问题3：CSS 选择器失去语义
frame[src*="frame-001"]这种写法，后期维护者根本看不懂业务含义。
hyperframes 强制采用动效名-类型-序号三段式命名，例如：
| 场景 | 命名示例 | 说明 |
|---|---|---|
| 首页英雄区入场动画 | hero-intro-01.png | hero-intro表明模块和动效类型，01是序号 |
| 按钮点击涟漪 | btn-ripple-01.png | btn-ripple明确组件和动效，避免和icon-ripple混淆 |
| 加载状态指示器 | loader-spin-01.png | loader-spin区分于loader-pulse（脉冲型） |
注意：序号必须两位数字（
01,02），不可用1,2。因为frame-1.png和frame-10.png在字符串排序中frame-10.png会排在frame-1.png前面，导致 CSS:nth-child()选择错乱。CLI 工具在import时会自动补零，但手动放入文件时务必自查。
3.2 HTML 结构设计：<frame>标签的 5 个必填属性与 2 个可选属性
hyperframes 并不发明新标签，而是约定一套<frame>的使用规范（实际仍是<div>或<span>，但语义化命名为frame）。其 HTML 结构必须包含以下属性，缺一不可：
