GitHub 趋势 · 第 105 期

把旧 iPhone 变成 Mac 副屏：开源免费，但命门是苹果一个私有 API

#开源项目#Mac技巧#实测核实#选型避坑#GitHub趋势

它到底是做什么的

一句话：把你吃灰的苹果设备，变成 Mac 的一块真正外接显示器。它是 Apple Sidecar、Duet Display、Luna Display 的免费开源替代品，作者原话是「turn your spare Apple devices into second monitors for your Mac」。

关键区别有三个。第一，它是真扩展屏，不是镜像——macOS 会把那台设备当成一个真实第二显示器，你可以把窗口拖过去、在系统设置里排布，而不是单纯把主屏复制一份。第二，它走USB或WiFi两条路：USB 通过 macOS 自带的 usbmuxd 转发，延迟最低、即插即用；WiFi 靠 Bonjour 零配置发现，在下拉菜单里选一下就行。第三，它带触屏输入——你的 iPhone 变成了给 Mac 用的触摸屏：点按等于点击，拖动等于拖拽，双指滑动像触控板一样。官方还把虚拟屏做成 Retina 级别的 @2x 清晰度，文字是锐的。

它和几个现成方案的差距，作者自己列了一张表，结论很直白：

也就是说：Sidecar 免费但不支持 iPhone、还要求同一 Apple ID；Duet 改成了订阅制；Luna 要买一个硬件加密狗。OpenDisplay 卡的就是「免费、开源、不要账号、不要加密狗」这一档——前提是你就想要一块真扩展屏，而不是只图镜像。

怎么上手（步骤取自 README 原文）

最省事的是用发布包，两个 app 都要装：Mac 端发屏用 OpenDisplay.dmg，旧 Mac 当接收屏用 OpenDisplayReceiver.dmg。README 写这两个包用 Developer ID 签名并经苹果公证，macOS 14 以上直接双击就能开，拖进应用程序文件夹即可。发布页在 github.com/peetzweg/opendisplay/releases。

iPhone / iPad 端的 app 不在 App Store，两条路：推荐走 TestFlight 公开测试（testflight.apple.com/join/3NYaY11c），或者自己用 Xcode 配一个免费 Apple ID 把 app 侧载到手机。iOS / iPadOS 需要 16 及以上。

USB 模式（推荐）按 README 的顺序是这样四步：

• ▪在 iPhone 上装好并打开 OpenDisplay（它在 9000 端口监听）；
• ▪在 Mac 上跑 ./run.sh（或直接打开 app），它直连 macOS 自带的 usbmuxd，插线自动连上，不需要任何隧道工具；
• ▪macOS 第一次会要你授权屏幕录制（用于采集）和辅助功能（用于触屏），各点一次；
• ▪把窗口拖到这块新显示器上，完成。

WiFi 模式更简单：在 iPhone 上打开 app，然后在 Mac 端连接菜单里选 iPhone (WiFi)，发现是 Bonjour 自动完成的。README 原话说 USB has lower latency; WiFi has no cable——插线更跟手，无线没线。

想从源码build，README 给的命令是这几条（逐字）：

brew install xcodegen   # project generation

git clone https://github.com/peetzweg/opendisplay.git
cd opendisplay
echo "DEVELOPMENT_TEAM=YOURTEAMID" > .env   # your Apple team ID, for signing
./generate.sh                               # runs xcodegen with your .env
xcodebuild -project OpenSidecar.xcodeproj -scheme OpenSidecarMac \
  -configuration Debug -derivedDataPath build build
xcodebuild -project OpenSidecar.xcodeproj -scheme OpenSidecariOS \
  -configuration Debug -destination 'generic/platform=iOS' \
  -derivedDataPath build -allowProvisioningUpdates build

它最该被知道的一点：靠一个私有 API 活着

整个方案的命门，在 README 的「How it works」一节写得很清楚：它用来造虚拟显示器的 CGVirtualDisplay 是 CoreGraphics 的私有接口（和 BetterDisplay、DeskPad 用的是同一个）。正因为它踩了这个私有接口，README 自己说「这恰恰就是它没法上 App Store、只能待在 GitHub 的原因」。采集和推流的管线走的是公开 API，但「虚拟显示器」这一层本身是私有的。

代价作者也不回避，FAQ 里直接写了：「Will it break on a macOS update? Possibly」——macOS 一升级，它有可能就坏了，而且「every virtual-display product」都担着同样的风险。换句话说，你用它的免费和开源，换来的就是：它随时可能被一次系统更新打断，而作者能不能跟上补，取决于这个私有接口的底层有没有变。

真实用户在 issue 里踩过的坑

这份材料比官网更有信息量，而且证明上面那个私有接口风险不是嘴上说说。

最硬的一条：#206「Extend mode fails on macOS Tahoe 26.6.1」——升级到 Tahoe 后虚拟显示器在 SCShareableContent 里干脆不出现，扩展模式直接失效。这条现在已经 closed / completed，说明作者跟上来修好了；但它恰好印证了「系统一升级就可能崩」不是吓人，是真发生过的。

第二条是实打实的技术上限：#271 在 5K 面板上选「Best」画质会静默超出 H.264 的像素率上限，编码器直接拒绝每一帧、黑屏；把画质降到「Balanced」就正常。这跟 README 里那条低延迟 H.264 管线是对得上的——硬件 H.264 编码有像素率天花板，高分屏别无脑开最高档。

连接类的问题最多，且不少还开着：#149「iPhone 在 WiFi 下无法连接」、#160「Shows Connected but does not work」、#161 / #171 两条「USB Failed」。README 也承认 WiFi 两端都要开「本地网络」权限，否则会静默失败——Mac 和 iPhone 的隐私设置里都得开，而且两台要在同一 WiFi。

还有几条值得记的：#133 一台 Intel Mac 加 Sequoia 连上了但 iPad 没画面（Apple Silicon 之外的老 Mac 确有坑）；#182 声音目前不在范围里——音频转发明确 out of scope，别指望把声音也传过去；另外 #75 sleep/wake 后 CPU 缓升的内存泄漏已修。整体看维护者是响应的，问题大多有回复、能闭环。

我的判断：适合谁、不适合谁、坑在哪

坑，按上手顺序排：

• ▪iPhone 端不在 App Store：要么走 TestFlight（testflight.apple.com/join/3NYaY11c），要么 Xcode 配免费 Apple ID 侧载，要数据线、要点「信任此电脑」。
• ▪WiFi 两端都要开「本地网络」权限，否则静默连不上；VPN 开着也可能拦本地流量，先关或放行。
• ▪USB 线必须支持数据，充电线不行；USB 1.x 不支持也没测过。
• ▪5K 这类高分屏别无脑开「Best」画质，会踩 H.264 像素率天花板黑屏，用「Balanced」（见 #271）。
• ▪许可是 GPL-3.0（copyleft）：你能随便用、改、学，但只要你分发修改后的版本，就必须同样开源、保留原作者署名——想闭源拿去卖不行。早期 v0.4.x 之前是 MIT，那几个老版本仍可按 MIT 用。
• ▪它依赖私有 CGVirtualDisplay，macOS 大版本更新有概率打断，装之前就把「可能要等作者修」算进成本里。

最后一句话总结：它是目前把「旧 iPhone 变 Mac 副屏」这件事做得最省钱的方案，代价是把稳定性押在苹果的一个私有接口上。能用、好用、免费，但别把它当永不掉链的生产力刚需。

#GitHub趋势#第105期

你更想看哪种「白嫖神器」的下一篇？是同类本地文件互传（比如跨平台的开源 AirDrop），还是把老安卓平板也变成副屏的玩法？留言告诉我，下期顺着这个方向挑一个写。

下期若无更值得写的单项目，我打算做一期「副屏 / 投屏 / 本地互传」开源工具横向合集，把扩展屏、镜像、文件互传几类放在一起对比选型。