故障排除

**修复：**运行 npx hyperframes init 从示例创建合成，或验证你的 index.html 具有正确的结构：

<div id="root" data-composition-id="my-video"
data-start="0" data-width="1920" data-height="1080">
<!-- elements here -->
</div>

本地渲染需要你系统上安装了 FFmpeg。为你的平台安装：

brew install ffmpeg

sudo apt install ffmpeg

# Download from https://ffmpeg.org/download.html
# Add the bin directory to your PATH

ffmpeg -version

安装后，运行 npx hyperframes doctor 验证 CLI 能找到它。

💡 Tip

如果你无法安装 FFmpeg，请改用 Docker 模式——它在容器内捆绑 FFmpeg：npx hyperframes render --docker --output output.mp4

运行 npx hyperframes lint 检查常见结构问题（参见 CLI: lint）：

确保你正在编辑项目目录中的 index.html。预览服务器监视文件更改并自动重新加载。

如果更改仍然不出现：

1. 检查终端中预览服务器的错误
2. 停止并重启 npx hyperframes preview
3. 强制刷新浏览器：Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（macOS）
4. 如果 CSS 更改未反映，清除浏览器缓存

**症状：**预览播放卡顿或跳帧，但渲染的 mp4 看起来正常。

**原因：**单帧绘制时间超过 16-33ms。渲染会隐藏这个（它逐帧捕获），预览不会。

常见原因，从最频繁到最少：

• 叠加的 backdrop-filter: blur() 层，尤其是半径超过 32px 的
• 非常高分辨率（超过 4K）的源图片在小区域显示
• 大元素上的 filter: blur() 或 filter: drop-shadow()
• 多个同时动画的元素带有 box-shadow 或 text-shadow

**首先检查：**卡顿是仅在特定场景中发生，还是贯穿始终？场景特定的卡顿通常指向某个元素，通常是模糊覆盖层，在该场景中变为可见。

**如何诊断：**打开 Chrome DevTools，切换到 Performance 标签页，录制几秒钟的播放，查找标记为"Composite Layers"或"Paint"的长任务。完整操作指南参见性能：测量慢合成。

**临时解决方案：**渲染为 mp4 然后观看输出。渲染在任何每帧开销下都是准确的。

npx hyperframes render --quality draft --output preview.mp4

完整指南请参见性能，了解高开销 CSS 模式及修复方法。

使用 --docker 模式获取确定性输出。本地渲染可能因以下原因不同：

• 字体可用性——不同平台上的不同字体导致文本重排
• Chrome 版本——本地 Chromium 与 Docker 固定版本渲染可能略有不同
• 系统特定渲染——GPU 合成、亚像素抗锯齿等

npx hyperframes render --docker --output output.mp4

在本地和 Docker 渲染之间选择的指导请参见渲染：何时使用哪种模式。

验证 Docker 已安装且守护进程正在运行：

docker info

常见问题：

• **Docker 未运行：**启动 Docker Desktop 或 Docker 守护进程
• **权限被拒绝：**将你的用户添加到 docker 组（sudo usermod -aG docker $USER）并重启 shell
• **镜像拉取失败：**检查你的网络连接；首次渲染下载 Hyperframes Docker 镜像

尝试以下优化：

1. 开发期间使用 --quality draft 以获得更快编码
2. 运行 npx hyperframes benchmark 查找系统的最优工作进程数
3. 本地 Chrome/WebGL GPU 捕获自动启用；故障排除时与 --no-browser-gpu 比较
4. 使用 --gpu 进行硬件加速编码（仅本地模式）
5. 如果不需要 30fps，降低 --fps 到 24
6. 检查你的合成是否有不必要的元素或过于复杂的动画

所有可用标志请参见渲染：选项。