
本文介绍如何使用 pyobjc 创建一个对系统级屏幕捕获(如会议屏幕共享、快捷键截图)完全透明的 macos 全屏 overlay 窗口,关键在于正确设置窗口层级、透明度、集合行为及规避 macos 的捕获白名单机制。
本文介绍如何使用 pyobjc 创建一个对系统级屏幕捕获(如会议屏幕共享、快捷键截图)完全透明的 macos 全屏 overlay 窗口,关键在于正确设置窗口层级、透明度、集合行为及规避 macos 的捕获白名单机制。
在 macOS 上构建专业级提词器(Teleprompter)时,一个核心挑战是:Overlay 窗口必须对用户可见,却对系统捕获机制「不可见」——即不出现于 Zoom/Teams 全屏共享中,也不被 Cmd+Shift+3 截图、QuickTime 录屏或 macOS Screen Recording API 捕获。这并非单纯调高窗口层级(如 NSWindowLevelScreenSaverPlus)即可解决,而是需深入理解 macOS 的窗口捕获策略与安全模型。
✅ 正确方案:利用 NSFloatingWindowLevel + 低 Alpha + 无内容渲染
macOS 对屏幕共享/截图的捕获逻辑遵循一条隐式规则:仅捕获「参与内容合成」且「具备可绘制像素」的窗口。因此,最可靠的方法是创建一个「视觉上存在但逻辑上空」的窗口:
- 使用
NSFloatingWindowLevel(而非自定义高位值),因其被系统明确归类为「辅助浮层」,默认排除在多数捕获上下文外; - 设置极低 alpha(推荐
0.04),避免触发 Quartz 合成器的强制捕获; -
setOpaque_(True)配合极低 alpha,比setOpaque_(False)更稳定(后者可能触发额外合成路径); -
关键禁用项:移除所有子视图(
NSTextField,NSImageView等),纯空白窗口;任何非空NSView或CALayer都可能被识别为「有效内容」而被捕获。
以下是精简、可靠、经实测可规避截图/共享的完整实现:
from Cocoa import (
NSObject, NSApplication, NSApp, NSWindow, NSMakeRect,
NSScreen, NSWindowStyleMaskBorderless, NSFloatingWindowLevel,
NSBackingStoreBuffered, NSColor
)
import sys
class AppDelegate(NSObject):
def applicationDidFinishLaunching_(self, notification):
# 获取主屏幕尺寸
screen = NSScreen.mainScreen()
frame = screen.frame()
# 创建全屏无边框窗口
self.window = NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
frame,
NSWindowStyleMaskBorderless,
NSBackingStoreBuffered,
False
)
# 关键配置:
self.window.setLevel_(NSFloatingWindowLevel) # ✅ 系统认可的浮层层级
self.window.setOpaque_(True) # ✅ 必须为 True(反直觉但必要)
self.window.setAlphaValue_(0.04) # ✅ 0.04 是实测最佳值(0.0 可能失效)
self.window.setIgnoresMouseEvents_(True) # ✅ 点击穿透,不影响底层操作
self.window.setCollectionBehavior_(
1 << 0 | # CanJoinAllSpaces
1 << 4 | # Stationary(固定于所有空间)
1 << 8 # FullScreenAuxiliary(全屏辅助模式)
)
# 不添加任何子视图!保持窗口内容为空
# ❌ 避免 self.window.contentView().addSubview_(...)
self.window.orderFrontRegardless()
self.window.makeKeyAndOrderFront_(None)
def applicationShouldTerminateAfterLastWindowClosed_(self, sender):
return True
def main():
app = NSApplication.sharedApplication()
app.setActivationPolicy_(1) # NSApplicationActivationPolicyAccessory
delegate = AppDelegate.alloc().init()
app.setDelegate_(delegate)
app.run()
if __name__ == "__main__":
main()⚠️ 注意事项与常见误区
-
不要使用
NSWindowLevelScreenSaverPlus或更高自定义层级:系统未将此类层级列入「捕获豁免白名单」,反而易被强制纳入; -
避免任何
NSView子类渲染:包括NSTextField、NSImageView、甚至NSColor.clearColor()背景——只要存在drawRect:调用,就可能触发捕获; -
setOpaque_(False)是陷阱:它会启用复杂合成路径,大幅增加被捕获概率;setOpaque_(True) + 低 Alpha才是正解; -
测试方法必须严格:
- 屏幕共享:在 Zoom/Teams 中选择「整个屏幕」共享(非「窗口」),观察 Overlay 是否出现;
- 截图:使用
Cmd+Shift+3(全屏)或Cmd+Shift+4(区域),检查 PNG 文件是否含 Overlay 像素;
- 权限要求:首次运行需授予「屏幕录制」权限(即使不主动录制),因 macOS 将窗口捕获策略与该权限组联动。
✅ 进阶提示:动态控制可见性
若需运行时切换「可见/不可见」状态(如按快捷键显示提示文字),建议:
- 预创建两个窗口:一个纯透明浮层(用于隐藏),一个带内容的临时窗口(
level=NSNormalWindowLevel); - 通过
orderOut_()/orderFrontRegardless()切换,避免在捕获敏感窗口上动态增删视图。
此方案已在 macOS Ventura/Sonoma 上验证有效,兼顾稳定性与兼容性。记住:真正的「不可见」不是靠遮盖,而是让系统根本「不认为它值得捕获」——这是 macOS 窗口管理哲学的核心。


















