企业官网建设流程全解析

最近在跑一个网页自动化项目，需要让 Playwright 完成整条流程后，既输出一份截图，又生成一段录屏视频作为交付材料。流程本身倒不复杂，但连续几天卡在一个看似很小的问题上：视频文件能正常生成，封面却永远是黑屏；偶尔连单独截图也是全黑。这种问题在自动化测试、网页监控、数据采集中相当典型，尤其是任务跑在 headless 模式里，出现概率会陡增。

这篇文章想把“Playwright 截图/视频时封面黑屏”这个问题，从现象定位到根因，再到可直接抄走的解决方案，完整梳理一遍。无论你是刚接触 Playwright，还是已经踩过几次坑，应该都能在里边找到自己能用的那部分。

1. 黑屏问题定位：先分清“黑”在哪一层

很多人一看到“封面黑屏”就开始调截图参数，或者到处搜代码片段，结果试了一圈还是黑。这个问题的麻烦之处在于，“黑屏”只是一个结果，它可能发生在好几个完全不同的环节里。先定位清楚，比急着改代码重要得多。

1.1 三种“黑”的现象与差异

我在实际项目里遇到的“黑”，大致能分成三类，现象和原因完全不同。

第一类是整页截图全黑。调用page.screenshot()之后，生成的 JPEG/PNG 文件打开以后整张图都是纯黑色，偶尔带一点点内容残影。这种一般发生在页面还在加载、渲染引擎还没正式工作的时候，你截图截得太早；还有一种情况是 headless 环境缺少必要的渲染参数，页面里的 Canvas 或 WebGL 内容根本没被画出来。

第二类是单独看视频文件，播放器封面黑。Playwright 的录屏能力是context级别的，它会把整个浏览器上下文的活动都录进一个 webm 文件。很多播放器或者平台在展示视频时，默认会取视频的第一帧作为封面。问题在于，第一帧往往是刚打开浏览器、刚创建 tab 的那一帧，此时页面还是空白甚至黑屏，拿它当封面自然就是黑的。

第三类是页面主体正常，但某一块区域黑。比如页面里有一个 Canvas 图表、一个视频播放器，或者一个跨域 iframe，截图出来其余部分都正常，就那块区域是黑的。这类问题通常不是截图时机的问题，而是浏览器合成/渲染层面的特殊限制。

先分清是哪一种，后面的排查方向才不会跑偏。我见过不少同学把“视频封面黑”当成“截图黑”去调wait_until，改了半天毫无效果，就是因为两者链路完全不同。

1.2 先确定是渲染问题还是截图链路问题

定位黑屏问题，我通常先用一个最简单的排除法：把headless改成False，在 headed 模式下跑一遍同样的流程。

如果 headed 模式下截图和视频封面都正常，那说明页面本身没问题，问题几乎可以锁定在 headless 渲染环境或截图时机上。如果 headed 模式下也黑，那可能是业务代码的问题，或者截图逻辑本身的时机就是错的，比如页面里有一段非常耗时的异步数据加载，你的代码在数据返回之前就截图了。

另外一个很实用的操作是把截图文件的信息打印出来看。比如文件大小：一个 1280x720 的空白 JPEG 和一张正常页面截图，文件体积会有明显差别，因为纯黑图压缩后的数据量很小。你可以在代码里把截图保存后立刻输出os.path.getsize()，如果一张全尺寸截图只有几 KB，基本可以断定是黑屏或空白页。

我还会在进入页面后主动监听页面事件，把 console、页面报错和请求失败全部打出来：

page.on("console", lambda msg: print("console:", msg.text)) page.on("pageerror", lambda err: print("pageerror:", err)) page.on("requestfailed", lambda req: print("failed:", req.url, req.failure))

headless 模式下页面 JS 报错不会展示在界面上，但这些监听能帮你看到很多隐蔽问题。比如某个第三方脚本一直请求失败导致页面渲染流程中断，从表面看就像是“页面没画出来”——实际是页面自己崩了。

2. 根因拆解：为什么封面会黑屏

定位到具体环节之后，下一步是理解背后的原因。黑屏不是随机发生的，它有明确的触发机制。把根因拆开，解决方案就顺理成章了。

2.1 视频封面的“默认第一帧”陷阱

可以先想想一个问题：一个 webm 视频文件本身其实没有“封面”这个概念。封面是播放器或平台在展示视频时，从视频流里取某一帧来充当的，绝大多数平台默认取第一帧。

但 Playwright 录屏的第一帧是什么时候？它在你创建context的时候就开始了。也就是说，视频会从浏览器上下文被创建、新 tab 被打开、页面还没完成跳转的那一刻录起。那段时间里，页面是空白背景，很多情况下直接就是黑屏/白屏帧。等你的页面真正渲染出内容时，视频已经前进好几秒了。

所以你会发现一个很反直觉的现象：录屏视频本身播到后面完全正常，偏偏封面是黑的。这并不是渲染失败，只是“取帧取错了位置”。明白了这一点之后，你就会知道，解决视频封面黑屏的核心思路不是“让视频不黑”，而是“不要在视频开头取封面”。

2.2 时序竞争：代码跑得太快，页面还没画完

如果连单独截图也是黑的，那大概率是时序竞争问题。

Playwright 里page.goto(url)返回时，只代表浏览器接收到了服务器的响应，并不代表页面渲染完成。wait_until="networkidle"稍微好一点，但它只表示网络请求不再发生，也不代表 JS 执行完了、图片解码完了、Canvas 画完了、字体加载完了。

最典型的场景是这样的：页面加载了一个图表库，数据通过 AJAX 请求获取，拿到数据后才开始绘制图表。你的代码在goto之后立刻调用page.screenshot()，此时请求还没返回，图表自然没画出来，截图里对应区域就是空白或黑色。

还有一种隐蔽的情况是页面里用了懒加载。图片或模块在滚动到可视区域内才真正加载，如果你直接对整页截图，首屏以外的部分可能就是空白。这些问题本质上都是同一个根因：截图指令的执行时机跑在了渲染完成之前。

2.3 headless 模式下的 GPU 与渲染差异

另一个绕不开的原因是 headless 环境本身的渲染能力限制。

早期的 headless Chromium 为了节省资源，默认关闭了很多 GPU 合成和硬件加速能力。对于普通的 HTML、CSS 页面，影响不大；但一旦页面里包含 WebGL、Canvas 2D 动画、CSS 3D 变换，甚至<video>标签，渲染结果就可能和正常浏览器大不一样。

比如一个用 WebGL 做数据可视化的页面，在普通浏览器里打开没问题，在 headless 截图里却经常是黑块，就是因为 WebGL 需要的 GPU 能力在 headless 下不可用，而软件渲染又没被正确启用。Chromium 后来推出的新 headless 模式解决了一部分问题，但并不是所有环境都默认开启，而且不同的 Playwright 版本、不同的 Chromium 版本行为也有差异。

所以我一直强调：遇到黑屏，先跑一遍 headed 模式，如果 headed 正常 headless 黑，马上就能想到是渲染环境的问题，而不是页面代码的问题。

3. 第一套解法：把截图时机“钉”在渲染完成之后

如果你确认问题是“截图时机太早”，那么解法就非常明确：不要用固定等待，要把截图时机绑定到渲染完成信号上。

3.1 不要只会 wait_for_timeout

我见过很多代码是这么写的：

page.goto(url) time.sleep(3) page.screenshot(path="shot.png")

这种写法在本地网络环境好、页面简单的时候能跑通，但一到真实生产环境就翻车：网络慢的时候 3 秒不够，页面一直没加载完；网络快的时候 3 秒又过于浪费。而且它有一个致命缺陷——你并不知道页面里某个关键模块是不是已经渲染完成。

更可靠的组合是这样：

page.goto(url, wait_until="networkidle", timeout=30000) # 等待所有图片完成加载 page.evaluate("""() => Promise.all(Array.from(document.images).map(img => { if (img.complete) return Promise.resolve(); return new Promise(resolve => { img.addEventListener('load', () => resolve(), { once: true }); img.addEventListener('error', () => resolve(), { once: true }); }); }))""") # 等待字体加载完成 page.evaluate("document.fonts.ready") # 等待下一帧绘制完成 page.evaluate("() => new Promise(requestAnimationFrame)")

这里有几个细节值得说明。

document.images会拿到页面所有图片，img.complete为true表示已加载完成或加载失败，不需要再等。每个图片都绑定load和error两个事件，是因为加载失败的图片永远不会触发load，如果不监听error，这个 Promise 可能会一直挂在那里，最终把整个等待流程拖死。

document.fonts.ready这个 Promise 会在字体加载完成后 resolve，能解决部分页面因为字体闪烁导致截图内容不完整的问题。

最后的requestAnimationFrame等待则是确保当前已执行的任务已经绘制到页面上，相当于手动等了一帧。

如果你觉得这套组合太啰嗦，可以再补一个更直接的动作：等待页面里“真正代表渲染完成”的那个元素出现。比如一个数据图表，它的容器里会有某个内部节点；一个后台页面，登录后右上角会出现用户头像。page.locator(...).wait_for(state="visible")比任何通用等待都可靠。

3.2 用“像素亮度检测”自动判断是否黑屏

等待信号做得再完整，也架不住页面里有不讲武德的复杂逻辑。比如某个图表库在数据到达之后还要做几秒动画，动画结束前 Canvas 里的内容就是半透明的，截出来像一块灰幕。这种场景下，最务实的方法不是去精确计算动画时长，而是“截完看一下，黑就重试”。

我现在的做法是截图之后立刻对图片做一次像素分析，判断它是不是黑屏/空白，如果是，就隔一小段时间重截，直到出现正常内容或者超时。

核心判断逻辑非常简单：

import io import numpy as np from PIL import Image def analyze_screenshot(raw: bytes) -> tuple: img = Image.open(io.BytesIO(raw)).convert("L") arr = np.asarray(img, dtype=np.float32) return float(arr.mean()), float(arr.std()) def is_blank_black(raw: bytes) -> bool: mean, std = analyze_screenshot(raw) # 纯黑空屏：整体亮度极低，且像素之间几乎没有差异 return mean < 20 and std < 10

这里用两个维度，是因为只看平均亮度会误伤深色页面。一个正常的深色后台页面，平均亮度可能只有 40 左右，但页面里有文字、有按钮、有边框，像素之间的差异（标准差）会比较大；而一张真正的纯黑截图，所有像素值几乎都集中在 0 附近，标准差也非常小。

有了这个判断函数，再封装一个带重试的截图方法：

import time def robust_screenshot(page, path: str = None, timeout: float = 15000): deadline = time.time() + timeout / 1000 last_mean = 0.0 last_std = 0.0 while time.time() < deadline: raw = page.screenshot() last_mean, last_std = analyze_screenshot(raw) if not is_blank_black(raw): if path: with open(path, "wb") as fp: fp.write(raw) return raw time.sleep(0.5) raise RuntimeError(f"页面持续黑屏: mean={last_mean:.1f}, std={last_std:.1f}")

这段代码的核心思路是“用结果验证过程”，比任何等待策略都更贴近真实情况：截出来的图确实正常了，才认为正常。

需要提醒的是，如果页面本身是纯黑设计或者整体非常暗，is_blank_black可能会误判。这时候可以把阈值调整得更宽松，或者不考虑std，只把mean作为一个辅助信号记录到日志里，以页面某个关键区域是否出现富文本/图表元素为准。

3.3 强制触发重绘：滚动、缩放与动画开关

有些黑屏并不是页面没加载，而是页面没“画”出来。这里可以主动触发浏览器重绘。

一个常见的场景是懒加载：页面首屏以外的图片、图表模块，在滚动到可视区域之前不会被加载。这时候直接整页截图，下面部分就是空白。可以先滚动到底再滚回来：

page.evaluate("""() => { window.scrollTo(0, document.body.scrollHeight); window.scrollTo(0, 0); }""")

这个动作会让浏览器认为用户浏览了整个页面，懒加载模块被触发，之后再截图就能拿到完整内容。

还有一类页面在 headless 下不会自动开始渲染动画，尤其是 Canvas 动画。这时候可以用requestAnimationFrame或者微调窗口大小来触发重绘：

page.set_viewport_size({"width": 1281, "height": 721}) page.set_viewport_size({"width": 1280, "height": 720})

改变 viewport 会触发一次完整的 layout 和 paint，很多“卡住不画”的页面在尺寸变化之后会被强制重绘。

不过也要谨慎使用page.screenshot(animations="disabled")。这个参数会在截图前把 CSS 动画强制跳到结束状态，本来是为了避免截到动画中间帧，但某些页面在动画被强制结束时，部分依赖动画状态的内容反而会渲染成空白。如果发现animations="disabled"之后截图变黑/变空，可以去掉这个参数，改为先等待动画自然完成再截图。

4. 第二套解法：视频与封面解耦，用 FFmpeg 替换封面

截图层面的问题解决之后，再处理视频封面黑屏的问题。前面说过，视频封面黑是因为平台默认取了第一帧，而第一帧是黑屏。这时候要做的不是在 Playwright 里“修”视频，而是把封面和视频解耦：视频正常录，封面单独取。

4.1 视频录制链路的特点

Playwright 的视频录制是在创建BrowserContext时开启的，只能通过record_video_dir和record_video_size配置：

context = browser.new_context( viewport={"width": 1280, "height": 720}, record_video_dir="videos/", record_video_size={"width": 1280, "height": 720}, ) page = context.new_page()

有几个关键点需要记住。

视频文件并不是实时写入的，它会在context.close()时才完成落盘。所以在录制过程中去查看视频目录，可能只有一个临时文件，无法直接读取。你的业务代码必须在context.close()之后再去操作视频文件。

视频时长和你打开 context 的时机强相关。从 context 创建开始，中间经历页面导航、业务操作，到 context 关闭为止，整个过程都会录进去。如果你的流程里还有打开新 tab、加载登录页等步骤，最终的视频包含的可不止目标页面那一段。

所以，想要一个“好看”的封面，不能直接从视频文件里取第一帧，而是要在视频的稳定播放区间里取帧。

4.2 从录制视频中提取非首帧封面

视频录制完成后，用 FFmpeg 提取封面是通用做法。

ffmpeg -y -i recording.webm -ss 3 -frames:v 1 cover.jpg

这条命令的意思是：从视频的第 3 秒取一帧，输出为 cover.jpg。你也可以把-ss放到-i后面，会做精确 seek，速度稍慢，但取到的帧位置更准确：

ffmpeg -y -i recording.webm -ss 3 -frames:v 1 cover.jpg

实际使用中，我会把时间点选在页面稳定加载完之后。如果页面加载需要 2~3 秒，那么就取第 5~8 秒附近的帧，基本能拿到完整渲染后的画面。更稳妥的做法是把视频转成多张帧，人工扫一眼哪些帧是正常的，再决定从第几秒取：

mkdir -p frames ffmpeg -i recording.webm -vf fps=1 frames/frame_%03d.jpg

fps=1会让 FFmpeg 每秒输出一帧 JPEG，这样你可以快速浏览视频每一秒的大致画面，判断黑屏持续了多久、从哪一秒开始正常。这个方法在排查“整段视频是不是某一段黑屏”时尤其好用。

4.3 把处理流程封装成可靠脚本

在 Python 里，完整流程大概是这样：先录制视频，关闭 context 后拿到路径，再用 FFmpeg 提取封面。

import subprocess from pathlib import Path def extract_video_cover(video_path: str, cover_path: str, seek_seconds: int = 5): subprocess.run([ "ffmpeg", "-y", "-i", video_path, "-ss", str(seek_seconds), "-frames:v", "1", cover_path, ], check=True) return cover_path

这里再解释一下为什么我要把“封面”和“视频”分开处理。

在很多业务场景里，你其实不需要把封面“嵌入”视频文件，只需要在报告或前台展示时，把封面图和视频文件当成两个独立素材传给前端即可。页面播放器显示封面图，用户点击后才加载视频，这叫“伪封面”，但它完全能够满足绝大多数需求，而且不需要重新编码视频，省时省力。

如果你确实需要把一个封面图内嵌进 MP4 文件，FFmpeg 也支持：

ffmpeg -i video.mp4 -i cover.jpg -map 0 -map 1 -c copy -disposition:v:0 attached_pic output.mp4

这条命令会把 cover.jpg 作为视频的 attached_pic 写入 MP4 的元数据里，某些播放器会把它显示为封面。但要注意，这种模式在不同播放器中的兼容性并不统一，有的播放器还是会显示黑屏第一帧。所以我的经验是：能用“封面图+视频文件分离”就用分离方案，内嵌封面只作为备选。

5. 实操代码：一个带自适应等待的截图/录屏封装

到这里，前面的思路可以合到一起，变成一个完整的封装。你可以直接把它改成自己项目的工具函数。

5.1 核心封装：带重试的截图函数

先定义一个完整的截图函数，集成像素检测和重试逻辑：

import io import time import numpy as np from PIL import Image def analyze_screenshot(raw: bytes) -> tuple: img = Image.open(io.BytesIO(raw)).convert("L") arr = np.asarray(img, dtype=np.float32) return float(arr.mean()), float(arr.std()) def is_blank_black(raw: bytes) -> bool: mean, std = analyze_screenshot(raw) return mean < 20 and std < 10 def wait_for_page_stable(page, timeout_ms: int = 20000): deadline = time.time() + timeout_ms / 1000 # 等待网络空闲，注意这里可能超时，需配合 try try: page.wait_for_load_state("networkidle", timeout=timeout_ms) except Exception: pass # 等待字体 try: page.evaluate("document.fonts.ready") except Exception: pass # 等待图片完成 page.evaluate("""() => Promise.all(Array.from(document.images).map(img => { if (img.complete) return Promise.resolve(); return new Promise(resolve => { img.addEventListener('load', () => resolve(), { once: true }); img.addEventListener('error', () => resolve(), { once: true }); }); }))""") # 等待动画下一帧 page.evaluate("() => new Promise(requestAnimationFrame)") def robust_screenshot(page, path: str = None, timeout: float = 15000): deadline = time.time() + timeout / 1000 last_mean, last_std = 0.0, 0.0 while time.time() < deadline: raw = page.screenshot() last_mean, last_std = analyze_screenshot(raw) if not is_blank_black(raw): if path: with open(path, "wb") as fp: fp.write(raw) return raw time.sleep(0.5) raise RuntimeError(f"页面持续黑屏: mean={last_mean:.1f}, std={last_std:.1f}")

wait_for_page_stable里把所有等待包了try，是因为不同页面的行为差异很大：有的页面有全局长连接，networkidle永远不会触发，硬等只会超时；有的页面没有字体或图片，等待逻辑不会阻塞。加了try之后，即使某个等待步骤失败，也不会让整个流程卡死，退出条件交给后面的像素检测来把关。

5.2 录屏场景下的完整使用姿势

接下来是把录屏、截图、业务操作整合到一起的完整示例：

from playwright.sync_api import sync_playwright def run_task(url: str): with sync_playwright() as p: browser = p.chromium.launch( headless=True, args=[ "--use-gl=swiftshader", "--enable-unsafe-swiftshader", ] ) context = browser.new_context( viewport={"width": 1280, "height": 720}, record_video_dir="videos/", record_video_size={"width": 1280, "height": 720}, ) page = context.new_page() page.on("console", lambda msg: print("console:", msg.text)) page.on("pageerror", lambda err: print("pageerror:", err)) page.on("requestfailed", lambda req: print("failed:", req.url, req.failure)) page.goto(url, wait_until="domcontentloaded", timeout=30000) wait_for_page_stable(page) # 自适应截图，作为业务封面 robust_screenshot(page, path="cover_business.jpg", timeout=15000) # 下面执行你自己的业务操作，比如点击按钮、填写表单、翻页等 # page.click("button.submit") # 关闭前记录视频路径 video_path = page.video.path() context.close() # context 关闭后，视频文件才完整 print("video path:", video_path) # 提取视频封面 extract_video_cover(video_path, "cover_video.jpg", seek_seconds=5)

这里的wait_until="domcontentloaded"是故意的：比networkidle更不容易卡死，页面只要 DOM 构建完成就算返回，后续渲染稳定交给wait_for_page_stable去处理。

我个人的习惯是封面图分两份：一份叫业务封面，是从页面直接截图，主要用于报告缩略图；一份叫视频封面，是从录屏视频里提取中间帧，用于视频播放器的 poster。两者可能内容一致，但来源不同，适配的场景也不同。

5.3 关于 headless 启动参数的实测经验

在 headless 模式下面启用软件渲染，我实测下来比较有效的启动参数组合是：

browser = p.chromium.launch( headless=True, args=[ "--use-gl=swiftshader", "--enable-unsafe-swiftshader", "--enable-gpu", "--ignore-gpu-blocklist", ] )

--use-gl=swiftshader会让 Chromium 使用 SwiftShader 软件渲染器来处理 WebGL 等图形能力；--enable-unsafe-swiftshader是新版 Chromium 里让 SwiftShader 生效的必要开关之一。--enable-gpu和--ignore-gpu-blocklist在 headless 下不一定有效，但加上通常不会有坏影响。

这里有一个经验要分享：不要为了提高截图成功率去加--disable-gpu。很多人以为 headless 黑屏是 GPU 导致的，干脆关掉 GPU，结果反而导致更多 CSS 合成异常。正确的方向是提供软件渲染能力，而不是禁用图形能力。

另外，如果机器上装了系统级显卡驱动，可以尝试把--use-gl=angle换成--use-gl=desktop或者去掉这个参数，让 Chromium 自己做选择，不同环境的最优解不一样。我的习惯是先在 headed 模式验证一段脚本，确认页面和业务都正常，再切到 headless 跑同一段脚本，这样能快速区分环境差异。

6. 常见问题与排查技巧实录

最后把我在项目里实际遇到过的典型问题整理成一个速查表，同时补充几个排查方法和特殊场景处理方案。

6.1 常见问题速查表

6.2 排查方法论：从现象到根因

当面黑屏问题的时候，我习惯按下面这个顺序推进，能少走很多弯路。

第一步，现在 headed 模式下复跑。这能快速区分“页面问题”和“headless 环境问题”。如果 headed 模式下一切都好，接下来基本只排查 headless 特有的因素。

第二步，用二分法缩小范围。页面渲染黑，你可以先把业务操作注释掉，只保留打开页面和截图两步，看是否还黑。如果还黑，说明和业务操作无关，问题出在页面加载或渲染本身；如果不黑了，那就是某一步业务操作导致页面状态变化，触发了黑屏。

第三步，检查页面报错和请求失败。headless 下的 JS 报错不会自己跳出来，但会真实影响渲染。提前挂上page.on("pageerror")和page.on("requestfailed")，很多“莫名黑屏”都能在这里找到答案。

第四步，保存现场素材。黑屏截图不要覆盖保存，文件名里带上时间戳，比如shot_20250115_153000.jpg，否则你很难对比黑屏出现时页面到底处于什么状态。同样，把截图的mean和std打到日志里，之后翻日志能发现规律。

6.3 几个“看起来像黑屏”的特殊场景

有些场景的黑屏，原因非常隐蔽，甚至可以绕开元凶直接改业务方案。

跨域 iframe 是重灾区。页面主体正常，但某个 iframe 来自其他域名，由于跨域限制，Playwright 的整页截图可能会把 iframe 区域渲染成空白或黑色。这时候不要硬截整页，可以用frame_locator定位 iframe 内部的元素，再对那个元素截图：

element = page.frame_locator("iframe.result-frame").locator("body") element.screenshot(path="frame_body.jpg")

<video>元素区域黑是另一个典型。HTML5 视频在播放时，视频帧通常经过硬件解码，不一定会进入浏览器的合成器，所以截图经常只能截到黑底或者播放器控件，看不到视频画面。如果视频是同源的，可以尝试在页面里用 Canvas 把当前帧画出来再转成图片：

page.evaluate("""() => { const video = document.querySelector('video'); const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; canvas.getContext('2d').drawImage(video, 0, 0, canvas.width, canvas.height); return canvas.toDataURL('image/jpeg', 0.9); }""")

但要注意，如果视频是跨域的，Canvas 会被“污染”，toDataURL会直接抛安全错误。这种情况下，我的建议是别跟视频帧死磕，业务上换一个方案：不截视频画面，而是截视频容器区域外的页面信息，或者在视频加载后用播放器的 poster 图片作为封面。

还有一类黑屏其实不是黑屏。有些后台系统是暗黑主题，整体背景就是接近黑色，亮色文字面积很小。用像素检测时，mean可能很低，看起来像黑屏。这时候别急着改渲染配置，先看一眼人的肉眼判断：如果页面元素轮廓清晰、可读性强，那只是风格问题，不是 bug。

最后再说一个容易忽略的：窗口焦点问题。Playwright 里如果一个自动化任务中途打开了新 tab 或弹窗，当前活跃页面会切换，你再对原来的page对象截图，可能会截到一张黑屏或空白图。可以用page.bring_to_front()把目标页面切回前台再截图，这个小动作能解决不少“偶发性黑屏”。

我个人在实际项目里已经被这个坑反复折磨过几次，所以现在所有涉及截图/录屏的任务都默认跑同一套组合：先 headed 验证，再 headless 跑；等待流程里不做无脑time.sleep，统一走“关键信号等待 + 像素检测重试”；视频封面永远不取第一帧，而是用 FFmpeg 从视频稳定区间取帧。这套组合不能说保证 100% 不再黑屏，但至少能覆盖掉绝大多数黑屏场景，而且出了问题也能快速定位到具体环节。最后一个小技巧再分享一次：把每张截图的mean和std写进日志，下次线上出现黑屏报告时，你扫一眼数值就能判断是纯黑帧还是暗色页面，不用再重新下载图片人工看。