WebGPU

使用无头 Chrome 对 WebGPU 页面进行截图和录制视频 —— three.js WebGPURenderer、Babylon.js 或原生 WebGPU。

默认情况下，无头 Chrome 不会暴露 WebGPU。如果不进行设置，这会静默失败：页面加载正常，截图命令也成功，但画布是黑的。--webgpu 标志会启用一个启动预设，使 WebGPU 正常工作，包括在没有 GPU 的容器和 CI 环境中。

也可以使用 AGENT_BROWSER_WEBGPU 环境变量，或在 ~/.agent-browser/config.json 或通过 --config 加载的文件中设置 "webgpu": true。

快速开始¶

agent-browser --webgpu open https://my-webgpu-app.example.com
agent-browser screenshot app.png

预设功能¶

macOS 使用硬件 Metal 后端，Windows 使用 D3D —— 两者都无需额外安装。

平台支持¶

Windows/Linux 的截图差距是上游无头 Chrome 的限制：即使渲染正常，WebGPU 画布的呈现也永远不会到达无头合成器（可通过像素回读验证）。目前已知没有任何标志组合可以解决这个问题。

在 Linux 上，即使在无显示服务器和容器中，也只需 --headed：当未设置 DISPLAY 且已安装 Xvfb（apt-get install -y xvfb）时，agent-browser 会为浏览器启动一个私有虚拟显示器，并在浏览器退出时一并拆除（AGENT_BROWSER_NO_XVFB=1 可选择退出）：

agent-browser --webgpu --headed open https://my-webgpu-app.example.com
agent-browser screenshot app.png   # real WebGPU pixels, no display hardware

在 Windows 上，有头会话必须在已登录的桌面会话中运行 —— 仅从 ssh/服务上下文启动是不够的（可使用 schtasks /IT 在交互桌面上安排启动，然后从任何位置驱动该会话）。

使用 doctor 验证¶

agent-browser doctor --webgpu

该探测会使用该预设启动一个临时会话，并分别对两个阶段进行像素检查 —— WebGPU 失败时是静默黑色，因此只有像素断言才能证明问题：

1. 渲染 —— 请求一个适配器（对冷启动时的空值进行重试），通过真实的渲染通道将离屏纹理清除为红色，然后读回缓冲区。报告实际使用的适配器。
2. 截图 —— 解码正在呈现的画布的实际截图，端到端验证捕获路径。

WebGPU probe
  pass  WebGPU rendered and read back pixels in 1.61s (nvidia ampere)
  fail  WebGPU renders, but headless screenshots miss the canvas (expected red, got rgb(0,0,0)); this is a known headless Chrome limitation on this platform
        fix: run WebGPU sessions with --headed on a logged-in desktop for screenshots

在 macOS 上，两项检查均可无头通过；在 Windows/Linux 上，第二项检查会告诉你该平台何时需要使用 --headed 进行捕获。运行 agent-browser doctor --webgpu --headed 来验证该路径本身 —— 在无显示 Linux 上，探测会自行启动 Xvfb，因此两项检查都应通过。

Linux、容器与 CI¶

SwiftShader Vulkan 路径需要系统 Vulkan 加载器和 Mesa ICD。如果没有它们，requestAdapter() 会返回 null：

apt-get install -y libvulkan1 mesa-vulkan-drivers

容器配方（仅截图路径需要 xvfb）：

FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y \
    ca-certificates libvulkan1 mesa-vulkan-drivers xvfb xauth \
    && rm -rf /var/lib/apt/lists/*
RUN npm install -g agent-browser \
    && agent-browser install

不需要真实 GPU 或 /dev/dri。如果要在拥有可用驱动的 Linux 机器上优先使用硬件 Vulkan，请同时覆盖 Vulkan 驱动和适配器 —— 该预设固定了 --use-vulkan=swiftshader，因此仅覆盖适配器仍会枚举 SwiftShader（用户参数优先于预设）：

agent-browser --webgpu --args "--use-vulkan=native,--use-webgpu-adapter=default" open ...

注意事项¶

仅限安全上下文。 navigator.gpu 仅存在于安全上下文中：https://、http://localhost 和 file:// 符合条件；普通的 http:// 局域网地址则不行，无论使用什么标志。

不要太早截图。 WebGPU 应用是异步初始化的 —— three.js WebGPURenderer 在首帧之前会等待异步 init()。在页面 load 时截图会捕获到空白画布且没有任何错误。请等待应用特定的就绪信号，或给渲染循环几帧时间：

agent-browser eval "new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))"
agent-browser screenshot app.png

three.js 会静默回退。 当没有可用的 WebGPU 适配器时，WebGPURenderer 会无错误地切换到其 WebGL2 后端。要检查页面实际获得的是什么：

agent-browser eval "document.querySelector('canvas').getContext('webgpu') ? 'webgpu' : 'webgl-fallback'"

自定义像素回读：避免画布快照。 drawImage(webgpuCanvas, ...) 依赖于呈现时序，并且在某些平台上即使渲染正常也会读回透明黑色。请渲染到离屏纹理，然后使用 copyTextureToBuffer + mapAsync 读回 —— 在每个平台上都是确定性的（doctor 探测正是这样验证渲染的）。

SwiftShader 是一个 CPU 光栅化器。 简单场景渲染良好；复杂场景仅能以个位数 FPS 运行。这对截图来说通常无关紧要，但对于复杂场景的流畅视频，请使用硬件（macOS/Windows，或使用真实 Vulkan 驱动程序的 Linux，并加上 --use-vulkan=native,--use-webgpu-adapter=default）。