OpenScreen 如何在 macOS 上从源码构建 ScreenCaptureKit 与光标原生 helper？

OpenScreen 如何在 macOS 上从源码构建 ScreenCaptureKit 与光标原生 helper【免费下载链接】openscreenCreate stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio.项目地址: https://gitcode.com/GitHub_Trending/open/openscreen如果你从源码跑 OpenScreen 的 macOS 版本会发现录制链路依赖两个 Swift 写成的原生 helperopenscreen-screencapturekit-helper负责 ScreenCaptureKit 屏幕/窗口采集和openscreen-macos-cursor-helper负责真实系统光标位图采样。仓库里只有 Swift 源码没有预编译二进制所以在本地做开发或排查原生录制问题时需要自己从源码构建这两个 helper。本文的目标是在 macOS 上用npm run build:native:mac构建出两个 helper确认产物落到了应用能解析的位置并用独立冒烟测试和录制 sidecar 文件验证它们真的在工作。构建前需要确认什么两个 helper 来自同一个 Swift 包 electron/native/screencapturekit/Package.swift声明了swift-tools-version: 5.9、最低平台.macOS(.v13)并定义了两个可执行产品。因此前提是构建必须在 macOS 主机上进行。构建脚本在非 darwin 平台会直接跳过并成功退出不影响 Windows/Linux 开发需要完整的 Xcode而不仅仅是 Command Line Tools。scripts/build-macos-screencapturekit-helper.mjs 会先调用xcodebuild -version失败时会报 full Xcode is not active并提示 CLT 可能缺少 SwiftPM 需要的 Swift SDK/平台元数据package.json 声明engines为node: 22.22.1、npm: 10.9.4。如果构建报缺少 SDK metadata 的错误docs/testing/macos-native-cursor.md 给出的处理方式是切换到 Xcode 的 Developer 目录并接受许可。以下两条命令都需要 sudo 管理员权限且作用于整台机器的开发者工具指向与 Xcode 许可状态执行前请确认你的系统允许这类变更sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer sudo xcodebuild -license accept构建命令与产物位置在仓库根目录执行npm run build:native:mac该脚本对应 package.json 中的node scripts/build-macos-screencapturekit-helper.mjs实际行为是对每个目标架构执行swift build -c release --arch arch --package-path electron/native/screencapturekit不构建通用fat二进制而是每种架构单独构建把两个可执行文件复制到两处electron/native/screencapturekit/build/—— 本地 dev server 使用electron/native/bin/darwin-arm64/或darwin-x64/由uname -m决定—— 打包版本使用。架构选择脚本默认构建主机架构CI 场景可通过环境变量OPENSCREEN_MAC_HELPER_ARCHS指定接受arm64、x64或x86_64可逗号分隔多个。本地按需构建 Intel 版本时可这样用OPENSCREEN_MAC_HELPER_ARCHSx64 npm run build:native:mac这与文档中的已知限制一致分发的 helper 是darwin-arm64构建Intelx86_64Mac 必须在目标机器上从源码构建。验证构建产物构建完成后确认两个二进制都出现在上述两类目录中。构建脚本对缺失可执行文件会以非零状态退出并打印executable was not found所以命令正常返回时产物应当已就位。应用侧的解析顺序见 electron/native/README.mdOPENSCREEN_SCK_CAPTURE_EXE环境变量本地开发与诊断用electron/native/screencapturekit/build/openscreen-screencapturekit-helper本地构建输出electron/native/bin/darwin-arm64/或darwin-x64/下的同名文件打包预构建。光标 helper 的解析顺序是OPENSCREEN_MAC_CURSOR_HELPER_EXE优先然后是同样的 build 目录与electron/native/bin/darwin-${arch}目录。也就是说构建成功后直接启动 dev 版本应用会自动从第 2 个位置找到 helper不需要额外配置。Electron 通过is-native-mac-capture-available做能力探测在 Swift helper 二进制就位之前它报告missing-helper——这是判断应用是否真的看到了 helper的明确信号。独立冒烟测试光标 helper在引入完整应用之前可以单独运行光标 helper 检查它的原始输出。以下命令在仓库根目录执行BIN指向本地构建输出它会把 helper 放到后台运行、2 秒后终止该进程kill $PID只终止这条命令自己启动的 helper并把 stdout 前 20 行打印出来BINelectron/native/screencapturekit/build/openscreen-macos-cursor-helper ($BIN {sampleIntervalMs:100} PID$!; sleep 2; kill $PID) | head -20文档给出的期望首行文档示例timestampMs为占位{type:ready,mouseTapReady:true,accessibilityTrusted:false,timestampMs:...}其中accessibilityTrusted: false在开发/未签名构建中是正常的表示 text/pointer 形态检测被关闭但原生位图捕获不受影响。后续应当出现type: sample的 JSON 行首次出现某个assetId时带完整asset含imageDataUrl、width、height、hotspotX、hotspotY、scaleFactor之后的采样只带assetId保持 stdout 精简。运行时移动光标到一个文本输入框如果出现新的assetId且位图不同说明采样链路正常text/pointer形态的替换依赖 Accessibility 授权见下文。可选让应用指向指定 helper 二进制如果要做本地诊断、让 dev 版本使用一个非默认位置的 helper用环境变量覆盖。下面命令中的/path/to/openscreen-macos-cursor-helper需要替换为你实际构建产物的绝对路径export OPENSCREEN_MAC_CURSOR_HELPER_EXE/path/to/openscreen-macos-cursor-helper npm run devOPENSCREEN_SCK_CAPTURE_EXE对 ScreenCaptureKit helper 起同样的覆盖作用。系统权限Screen Recording 与 Accessibility原生路径涉及两个相互独立的系统权限见 docs/testing/macos-native-cursor.md权限作用授予位置Screen RecordingScreenCaptureKit 视频采集System Settings → Privacy Security → Screen System Audio Recording → Electron ✅Accessibilitytext/pointer光标形态检测affordance hintsSystem Settings → Privacy Security → Accessibility → Electron ✅Screen Recording 是必需的没有它录制根本无法开始。Accessibility 是可选的没有它时cursorType恒为null所有光标都按捕获到的位图渲染不做 SVG 替换文档明确说这是预期回退、不降低非 text/pointer 形态的光标质量。一个容易踩的坑在系统设置里授予任一权限后必须完全退出并重启 dev server——getMediaAccessStatus按进程缓存结果。另外对未签名/dev 构建getMediaAccessStatus(accessibility)可能不反映开关状态此时应以 helperready事件里的accessibilityTrusted字段为权威信号。验证录制确实走了原生路径在应用里录一段短片并保存后检查与视频同目录写入的 sidecar 文件videoPath.cursor.json例如视频为/tmp/rec.mp4时sidecar 是/tmp/rec.mp4.cursor.json。文档给出的示例结构示例结果{ version: 2, provider: native, assets: [ { id: a7472..., platform: darwin, imageDataUrl: data:image/png;base64,..., width: 64, height: 64, hotspotX: 26.0, hotspotY: 16.0, scaleFactor: 2.0 } ], samples: [ { timeMs: 0, cx: 0.42, cy: 0.38, visible: true, assetId: a7472..., interactionType: move } ] }判断标准是文档明确给出的provider: native且assets非空说明位图捕获已激活如果看到provider: none和assets: []说明 helper 没找到或在ready事件之前就退出了——回到验证构建产物一节检查二进制位置。已知限制与原生路径的启用条件原生 ScreenCaptureKit 后端的启用条件三者缺一不可macOS 13 (Ventura) 或更新、openscreen-screencapturekit-helper二进制存在、Screen Recording 权限已授予。此外文档列出的限制CGS 层自定义光标helper 通过NSCursor.currentSystem采样某些游戏或 GPU 加速应用通过 CoreGraphics/CGS 层设置的光标可能采不到这是已知的 macOS API 限制Retina 对齐helper 会报scaleFactor: 2.0渲染端按该值折算像素尺寸与 hotspot摄像头当前仍走 Electron 侧录并挂到同一录制会话原生 AVFoundation 摄像头合成是目标态而非现状见 docs/engineering/macos-native-recorder-roadmap.md。helper 契约、阶段划分与 SSOT 规则详见 docs/engineering/macos-native-recorder-roadmap.md如果要连同应用本体一起打包npm run build:mac会先执行build:native:mac再跑tsc vite build electron-builder --mac打包产物按架构落在electron/native/bin/darwin-${arch}下。【免费下载链接】openscreenCreate stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio.项目地址: https://gitcode.com/GitHub_Trending/open/openscreen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考