headless Chrome 截图 WebGL 黑块问题排查
462 字
2 分钟
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 启动参数:
options = Options()options.add_argument("--headless=new")options.add_argument("--no-sandbox")options.add_argument("--disable-dev-shm-usage")# WebGL 软件渲染(Spline/Live2D 等 WebGL 内容在 headless 下默认不渲染,产生黑块)# 新版 Chrome 需要 --enable-unsafe-swiftshader 才允许软件 WebGLoptions.add_argument("--use-gl=angle")options.add_argument("--use-angle=swiftshader")options.add_argument("--enable-unsafe-swiftshader")options.add_argument("--ignore-gpu-blocklist")options.add_argument("--disable-extensions")options.add_argument("--disable-software-rasterizer")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)
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!
headless Chrome 截图 WebGL 黑块问题排查
https://blog.amamo.top/posts/headless-chrome-webgl-black-block/相关文章智能推荐
1
koffi 在 Alpine 上直接 abort:一次 musl 预编译排查
运维dsh 在 Alpine aarch64 上一调用工具就整个进程 abort。根因是 koffi 3.1.1 优先加载 glibc 预编译二进制,在 musl 上进入 C++ 初始化后直接终止,musl 回退逻辑根本没机会执行。本文记录排查过程、修复思路和修复仓库。
2
怎么让 dsh 搜索用上 Exa 插件
运维dsh 基础包把 web 行的 searchProvider 钉死为 deepseek-official,导致搜索插件的"零配置自动接管"不会生效;本文记录排查过程与 profile 补丁层的修复方法。2026-10-05 勘误:profile 补丁层是整值替换而非合并,web 行必须把 fetchProvider 一并写上。
3
怎么让 dsh 无限重试
运维dsh 默认只会重试 5 次且间隔很快;本文展示通过配置 retryPolicy 为 always,实现指数退避的无限重试。
4
评论图片直传图床:Waline + EdgeOne 边缘函数踩坑记
blogWaline 评论默认把图片转成 base64 塞进评论数据,又慢又胀。本文记录给评论加上图片直传的全过程:用 EdgeOne 边缘函数做鉴权代理把密钥留在服务端,以及 545、401、404 三层报错的排错实录,还有一次被主动放弃的"点发送才上传"设计。
5
机房装 Node.js 记
4 核 4G 的机房电脑、一份奇怪的问卷,和一个从 Gitee 下载的项目
随机文章随机推荐


