headless Chrome 截图 WebGL 黑块问题排查

起因#

维护友链检测工具 check-flink（Selenium + headless Chrome 截取友链主页并上传图床）时发现：部分友链站点使用了 Spline 或 Live2D 这类 WebGL 内容，截出来的图对应区域是一块纯黑色，黑块里还带着 WebGL 初始化失败的报错信息，非常难看。

原因分析#

headless Chrome 在无 GPU 环境下默认禁用 WebGL 渲染。站点通过 WebGL 绘制的 3D/动画内容无法初始化，页面就只剩下一块黑色区域（有时带报错提示）。之前截图工具的 Chrome 启动参数里是 --disable-gpu，等于直接关掉了 GPU 相关的所有能力。

解决方案#

Chrome 支持通过 SwiftShader 做 WebGL 的软件渲染——没有 GPU 也能用 CPU 模拟渲染出 WebGL 内容。改动 screenshot.py 里的 Chrome 启动参数：

1
options = Options()
2
options.add_argument("--headless=new")
3
options.add_argument("--no-sandbox")
4
options.add_argument("--disable-dev-shm-usage")
5
# WebGL 软件渲染（Spline/Live2D 等 WebGL 内容在 headless 下默认不渲染，产生黑块）
6
# 新版 Chrome 需要 --enable-unsafe-swiftshader 才允许软件 WebGL
7
options.add_argument("--use-gl=angle")
8
options.add_argument("--use-angle=swiftshader")
9
options.add_argument("--enable-unsafe-swiftshader")
10
options.add_argument("--ignore-gpu-blocklist")
11
options.add_argument("--disable-extensions")
12
options.add_argument("--disable-software-rasterizer")
13
options.add_argument(f"--window-size={WINDOW_WIDTH},{WINDOW_HEIGHT}")

关键点：

• 移除 --disable-gpu，它会把 GPU 相关能力整个关掉
• --use-gl=angle + --use-angle=swiftshader：ANGLE 层之上跑 SwiftShader 软件实现
• --enable-unsafe-swiftshader：新版 Chrome 的必需参数，没有它软件 WebGL 依然不允许启用
• --ignore-gpu-blocklist：忽略对软件渲染器的黑名单限制

验证#

改完后对含 WebGL 内容的友链站点重新截图，Spline / Live2D 内容可以正常渲染，黑块消失。磁盘没有独立 GPU 的 CI 环境（GitHub Actions / 国内流水线）同样适用。

备注#

• 该修复已通过 PR 提交到上游项目：check-flink
• 此方案是”尽力”渲染：个别站点可能仍有兼容性问题，必要时可再叠加截图后黑区检测兜底
• 如果遇到 WebGL 内容加载慢，可适当调大截图前的等待时间（PAGE_LOAD_WAIT）