先弄清楚：为什么会捕获不到窗口
讲清楚这个问题，我们先把常见原因摆一摆，别着急去改代码。捕获失败的本质通常是“看不到”或“被系统拦住”两类：一个是目标窗口本身没有可读像素（比如最小化或独占显式渲染），另一个是操作系统或应用做了保护（权限、DRM、Wayland策略、UAC安全桌面等），再就是自动化工具选用的捕获API和目标窗口类型不匹配（例如PrintWindow对分层窗口失效）。理解了这一点，后面每一步就有针对性了。
常见具体原因（快速清单）
- 权限不足：macOS需授予“屏幕录制”，某些Linux Wayland配置需PipeWire授权。
- 窗口被最小化或不在同一会话：许多API无法捕获被最小化的窗口或在不同桌面/远程会话的窗口。
- 独占渲染 / DRM保护：视频播放器或游戏可能使用受保护路径，不能被普通截屏API读取。
- 硬件加速与渲染模式：GPU直连渲染、硬件加速或使用独立显卡的应用，普通GDI/PrintWindow可能拿不到内容。
- API限制或应用设置：Electron/Chromium 应用可能启用了内容保护（setContentProtection），浏览器的 getDisplayMedia 有显示类别限制。
- 操作系统差异：Wayland 与 X11、Windows 的 Desktop Duplication、macOS 的 CG APIs 行为不同。
一步步排查：从最容易到最彻底
按顺序来，像拆机器那样，一步步排除。下面的方法大多数情况下能把问题定位到点上。
1）先检查最简单的：窗口与会话状态
- 确保目标窗口不是被最小化。把它恢复、前置（bring to front）再试。
- 确认目标窗口在当前用户会话与桌面，有时远程桌面或切换用户会让窗口不可捕获。
- 如果是多显示器，试试把窗口移到主显示器再捕获。
2）权限与安全设置
- macOS：系统偏好设置 → 安全性与隐私 → 屏幕录制，给比特浏览器或自动化工具授权并重启进程。
- Linux（Wayland）：确认 PipeWire 与权限代理是否允许截屏；必要时在 X11（XWayland）下重试。
- Windows：虽然没有统一的“屏幕录制权限”，但UAC安全桌面会阻止截屏（例如提升对话框），试着以管理员身份运行捕获进程或关闭安全桌面场景测试。
3）切换捕获方式：API 不同效果差很大
不同API的行为差别大。可以按下面优先级尝试切换：
- 全屏/显示级别截屏（Desktop Duplication / CGDisplay / PipeWire）——通常最稳定，但如果目标受DRM保护也可能失败。
- 窗口级别截屏（Windows Graphics Capture / CGWindowListCreateImage / Xcomposite）——对非最小化窗口有效，但对分层窗口或内容保护有限制。
- 像素拷贝（GDI BitBlt、PrintWindow）——有时对老程序有效，但遇到硬件加速或透明窗口内容会是黑屏或空白。
按操作系统给出更具体的建议
Windows（最常见的场景）
Windows下问题来源很多，我把常用的排查和解决写清楚：
- 优先使用 Windows.Graphics.Capture 或 Desktop Duplication API：这两种方式对现代 GPU 渲染支持较好。Desktop Duplication（DXGI）适合捕获整桌面或特定显示器；Windows.Graphics.Capture 可以更友好地捕获窗口和应用。
- 避免单纯依赖 PrintWindow/BitBlt：这些 GDI 方法无法读取 GPU 直接渲染到显存的内容，也不适合分层（layered）窗口。
- 提升权限或运行时上下文：如果目标窗口属于管理员进程，捕获进程需要相同权限才能访问。试试以管理员方式启动自动化程序。
- Electron/Chromium 应用特例：检查是否启用了 setContentProtection(true) 或在命令行中用了 –disable-features=… 等；这些会阻止屏幕捕获。若是浏览器扩展调用屏幕共享，确认扩展权限和浏览器设置。
- 被占用的独占模式：全屏游戏或使用独占呈现的应用可能无法被DXGI以常规方式捕获，改用整屏捕获或在窗口模式下运行。
macOS
- 必须在“系统偏好设置 → 安全性与隐私 → 屏幕录制”中给捕获工具授权，授权后通常要强制关闭并重启程序。
- 使用 CGWindowListCreateImage、AVCaptureScreenInput 等系统API进行捕获更可靠；如果使用第三方库，确保它们支持最新 macOS 的隐私模型。
- 对受保护内容（例如某些视频应用），系统层面也可能阻止捕获。
Linux（重点：Wayland vs X11）
- 在X11下，可以用 Xcomposite、xwd、x11grab 等进行捕获，通常比较直接。
- Wayland对安全更严格：许多桌面环境只允许通过 PipeWire 的 screencast 接口进行合法共享。确保你的应用或自动化框架支持 PipeWire，并且权限代理（比如xdg-desktop-portal）允许截屏。
- 实在不行的常见办法：在X11 (XWayland) 环境下运行目标或使用X11会话来测试是否能捕获。
一些具体场景与可行的替代方案
下面是几种常见的“卡住点”及应对策略，比较实用：
目标窗口是视频播放器或受DRM保护内容
- 系统级DRM一般不能被普通截屏API读取，解决办法是：使用播放器本身导出帧或截图接口，或改为捕获整屏（有时整屏也被保护），或者在允许的前提下关闭内容保护。
- 对浏览器视频，可尝试使用浏览器提供的媒体捕获接口并与扩展结合，但受制于播放端的保护策略。
目标是Electron或自家应用，发现截屏是黑屏
- 检查是否调用了 setContentProtection(true) 或在窗口创建时使用了透明/分层属性；尝试临时关闭这些设置。
- 如果应用使用硬件加速，尝试临时禁用硬件加速或提供软件渲染回退。
实用的排查步骤（可复制执行）
- 把目标窗口恢复并前置，确认不是最小化。
- 以管理员/相同用户权限运行捕获程序，或在目标进程权限下运行。
- 在系统设置中授予“屏幕录制/截屏”权限，重启应用。
- 切换捕获API：先试整屏，再试窗口级，再试GDI；记录哪一步有效。
- 如果在Linux，用X11测试；在Windows，尝试Windows Graphics Capture而不是PrintWindow。
- 若怀疑DRM或内容保护，尝试换成非加密内容或使用应用内导出。
对比表：常见OS问题与首选解决方案
| 操作系统 | 最常见问题 | 首选解决方案 |
| Windows | 硬件加速、独占渲染、管理员权限 | 使用Desktop Duplication或Windows.Graphics.Capture，提升到相同权限，禁用硬件加速测试 |
| macOS | 未授予屏幕录制权限、受保护内容 | 授予“屏幕录制”并重启应用，使用CG APIs |
| Linux (Wayland) | Wayland权限模型、PipeWire配置 | 使用PipeWire + xdg-desktop-portal，或切回X11测试 |
如果都试过还不行，有几个替代路径
- 用外部工具做屏幕采集再把结果交给自动化逻辑，比如 OBS、ffmpeg 的屏幕采集模块；OBS 可以捕获绝大多数场景并输出给虚拟摄像头。
- 如果是自动化测试场景，尽量使用应用内的截图或导出接口（比如通过应用提供的API、热键或日志导出），比外部截屏更稳定。
- 在无法解决的情况下，考虑在受控的虚拟机或容器里运行目标与捕获程序，保证两者在同一桌面会话和配置下运行。
常见误区，顺便提一提
- 误以为“以管理员运行一定可以截屏”：行政权限能解决权限隔离问题，但对DRM和Wayland策略无效。
- 误以为“PrintWindow 能截所有窗口”：对分层窗口、透明窗口、GPU直连渲染通常失败。
- 误以为“最小化也能截到内容”：大多数API无法捕获最小化窗口的实际像素。
对了，我还经常碰到一个小坑：自动化脚本在本地能捕获，但跑到 CI 或远程机器就不行——通常就是会话/显示器不存在或没有桌面会话造成的。解决思路就是保证有一个活跃的桌面会话或者用虚拟显示（dummy display）/虚拟帧缓冲（Xvfb、dummy monitor）来保证可截图的上下文存在。
好吧，如果你愿意，可以按照上面的步骤一步步来排查。我写这些时也想着如果遗漏了什么就补上：遇到具体错误信息（比如黑屏、空白窗口、捕获报错码），把错误码贴出来会更快定位。事情大体就是这些，慢慢来，通常能找到原因并对症下药。