OpenDisplay：让 iPhone 变成 Mac 的免费 Retina 副屏
给 Mac 用户把 iPhone 变成免费 Retina 副屏，支持 USB、WiFi 和触控，不用订阅或 dongle。
GitHub peetzweg/opendisplay 更新 2026-09-15 分支 main 星标 3.6K 分叉 251
Swift TypeScript macOS iOS H.264 Bonjour usbmuxd 虚拟显示器

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你有 iPhone、iPad 或备用 Mac，并需要 Mac 的真实扩展显示而非仅镜像。
    README 的 Features 和 Install：支持 true display extension；备用 Mac 使用 OpenDisplay Receiver。
  • 你优先考虑 USB 低延迟，并能使用支持数据的 Lightning/USB-C 线。
    README 的 Run (USB — recommended) 与 FAQ：USB 延迟最低，充电线不支持，USB 2.0 数据线足够。
  • 你需要 Retina @2x、触控点击、拖拽和双指滚动输入。
    README 的 Features：Retina/HiDPI 按面板逐像素匹配，Touch input 支持 tap、drag 和 two-finger scroll。
  • 你希望屏幕内容只在 Mac 与设备之间传输，不使用账号或第三方服务器。
    README 的 Self-hosted & private 和 FAQ：使用一个直接 TCP 连接，没有 servers、accounts、analytics。

不适合，如果你

  • 你不能接受依赖 macOS 私有 API 的虚拟显示器方案。
    README 的 FAQ 明确说明 CGVirtualDisplay 是 private API，macOS 更新可能导致故障。
  • 你需要音频传输或 Apple Pencil 压感输入。
    README 的 FAQ：Audio out of scope；iPad 的 Pencil、pressure 仍在 roadmap。
  • 你的工作环境禁止 Screen Recording 或 Accessibility 权限。
    README 的 Quick start：首次运行需要授予 Screen Recording 和 Accessibility 权限。
  • 你只有充电线、USB 1.x，或无法解锁设备并确认 Trust This Computer。
    README 的 FAQ：充电线和 USB 1.x 不支持；可靠连接需要数据线、解锁设备并接受 Trust This Computer。

前置条件

  • 需要两款应用：Mac 端 OpenDisplay 与 iOS 端接收应用；备用 Mac 方案改装 OpenDisplay Receiver。 / Requires two apps: the Mac OpenDisplay app and the iOS receiver; for a spare Mac, install OpenDisplay Receiver instead.
  • 发送端 Mac 需要 macOS 14；备用 Mac 接收端需要 macOS 12 Monterey 或更新版本。 / The sending Mac requires macOS 14; a spare Mac receiver requires macOS 12 Monterey or newer.
  • USB 需要支持数据的 Lightning/USB-C 线；USB 2.0 数据线足够，USB 1.x 不支持或未测试。 / USB requires a data-capable Lightning/USB-C cable; USB 2.0 is sufficient, while USB 1.x is unsupported or untested.
  • 首次运行需授予 Screen Recording 和 Accessibility 权限。 / The first run requires Screen Recording and Accessibility permissions.
  • WiFi 连接要求 Mac 与 iPhone 都开启 Local Network 权限并处于同一 WiFi。 / WiFi requires Local Network permission on both the Mac and iPhone, with both on the same WiFi network.

第一步命令（README 原文）

./run.sh

要注意

  • WiFi 发现失败时，两端 Local Network 权限缺失会静默失败；USB 模式不受影响。
    README FAQ：The Mac app doesn't show my iPhone in the Connection menu (WiFi)。
  • USB 连接要解锁设备并接受 Trust This Computer，避免不可靠 hub 或 adapter。
    README FAQ：What USB cable or version do I need?
  • macOS 菜单栏会出现紫色录屏指示灯，OpenDisplay 无法隐藏它。
    README FAQ：Why do I see the purple screen-recording indicator in the menu bar?
  • iPad 可用同一代码库，但 Pencil 和 pressure 仍在 roadmap。
    README FAQ：Does it support iPad?

替代方案

  • Apple Sidecar：你的设备属于支持的硬件组合，并且两台设备使用同一个 Apple ID；Sidecar 不需要额外安装 OpenDisplay。
    README 章节 Why OpenDisplay exists
  • Duet Display：你接受订阅模式，并希望使用 README Comparison 中列出的商业显示方案。
    README 章节 Why OpenDisplay exists、Comparison
  • Luna Display：你愿意购买 hardware dongle，并选择 README Comparison 中的商业方案。
    README 章节 Why OpenDisplay exists、Comparison

材料未说明

  • 材料未提供 macOS 14 发送端的具体硬件兼容列表。 / The materials do not provide the detailed hardware compatibility list for the macOS 14 sender.
  • 材料未提供 iPhone、iPad 的最低 iOS/iPadOS 版本。 / The materials do not specify the minimum iOS/iPadOS version.
  • 材料未提供预构建 Mac 下载方式、安装包大小或签名发布细节。 / The materials do not provide prebuilt Mac download instructions, package size, or signing details.
  • 材料未给出不同分辨率、帧率和 H.264 预设下的实际延迟与 CPU/GPU 占用。 / The materials do not give measured latency or CPU/GPU usage across resolutions, frame rates, and H.264 presets.
  • 材料未展开当前 WiFi-encryption caveat 的具体威胁模型与加密方式。 / The materials do not detail the threat model or encryption method behind the current WiFi-encryption caveat.
  • 材料未说明 iPhone 与 iPad 的最低硬件型号及各型号的性能差异。 / The materials do not specify minimum iPhone/iPad hardware models or performance differences by model.

💡 深度解析

6
不适合 我需要 Retina/HiDPI 的 iPad 第二屏，并且工作依赖 Apple Pencil 压感；OpenDisplay 能否替代我的专业绘图显示器？
适合读者： 需要高分辨率触控辅助屏、使用 iPad 和 Apple Pencil 做绘图的设计师

不适合把它当作专业绘图显示器替代品，因为 Retina 显示和基础触控已支持，但 Apple Pencil 与压感仍未实现。

  • Features 承诺 Retina/HiDPI、原生分辨率、横竖屏切换，以及 tap、drag、two-finger scroll 等触摸输入。
  • 同一节明确写着 Apple Pencil support is on the roadmap，说明它不是当前可用能力，尤其不能据此推断压感笔输入已传递到 macOS。
  • 项目洞察还把专业色彩管理、极低延迟绘图和高刷新率列为不能仅凭当前说明视为等同原生显示接口的场景。
  • 另外，当前主要使用 H.264；README 没有承诺专业色彩精度、笔输入时延或高刷新率。

它更适合代码、控制面板、参考窗口和普通触摸操作，而不是依赖笔压、色彩一致性和绘图响应的工作流。

  • Features："Retina / HiDPI"；支持 "tap to click"、"drag"、"two-finger scroll"
  • Features："Apple Pencil support is on the roadmap"
  • 项目洞察 usage_limitations：专业色彩管理、极低延迟绘图和高刷新率不能视为原生显示接口替代
  • 项目数据：description 提及 touch input，但未提及 Apple Pencil 或压感
材料未说明：README 未说明 Apple Pencil 路线图的交付时间或当前是否存在实验性实现。；README 未提供色彩空间、刷新率、编码延迟或笔输入延迟指标。
适合 我有一台 macOS 14+ 的 Mac 和一部 iPhone，设备使用不同 Apple ID；我想免费获得真正的扩展显示器，而不是镜像，OpenDisplay 适合吗？
适合读者： 维护 macOS 14+ 主机、拥有 iPhone 或 iPad、希望免订阅费和免额外硬件获得第二屏的个人开发者

适合，因为它正好覆盖 iPhone、不同 Apple ID 和真正扩展显示这三个约束。

  • README 的 Features 明确写着 macOS 会把设备识别为真实第二显示器，可拖动窗口并在系统设置中排列，而不是只能镜像。
  • Comparison 表列出 OpenDisplay 支持 iPhone 作为显示器、不同 Apple ID、USB 连接和自托管；项目目标也明确是 free、open source、no-account、no-dongle。
  • 官方应用要求 iOS 16.4+；Mac 端还需要 Screen Recording 和 Accessibility 权限，后者用于触摸输入。

如果你更重视低延迟，可走 USB；README 说明 USB 使用 macOS 内置 usbmuxd，不需要额外隧道工具。它不能替代音频同步或专业显示器，这些能力在提供的 README 内容中没有被承诺。

  • Features："True display extension"
  • Comparison：OpenDisplay 支持 "iPhone as display"、"Different Apple IDs"、"Wired (USB)"
  • Quick start / Install：官方 iOS 应用要求 iOS 16.4+；需要 Screen Recording 和 Accessibility 权限
  • 项目数据：description 为 "free, open-source ... true second monitor"
./run.sh
材料未说明：README 节选未说明具体 Mac 型号、iPhone 型号和目标刷新率是否满足你的工作负载。；README 节选未说明不同分辨率下的实际延迟和带宽数值。
适合 我希望用 USB 把 iPhone 接到 Mac，运行 Retina/HiDPI 第二屏，并尽量避免 WiFi 抖动；项目的传输设计是否符合这个约束？
适合读者： 需要在 USB 连接下运行高分辨率 Retina 第二屏、同时受限于带宽和交互延迟的远程办公工程师

适合，USB、Retina/HiDPI 和低延迟正是 README 明确覆盖的组合，但实际体验仍取决于线缆、设备和显示负载。

  • Features 将 USB 描述为 lowest latency，使用 Lightning/USB-C 与 macOS 内置 usbmuxd，不依赖网络、WiFi jitter 或 helper tools。
  • Retina/HiDPI 模式会按设备面板像素匹配；How it works 进一步说明 Mac 按设备原生面板尺寸创建 @2x 虚拟显示器。
  • 传输管线采用 VideoToolbox 硬件 H.264、实时模式、无 B 帧、TCP_NODELAY，以及帧丢弃背压和关键帧恢复，目标就是避免交互延迟持续累积。
  • Quick start 把 USB 标为 recommended，但首次连接需要可靠的数据线、解锁设备并确认 Trust This Computer，同时 Mac 仍需 Screen Recording 权限。

这适合办公、代码和辅助窗口；README 没有给出固定 FPS、端到端延迟或高刷新率保证。

  • Features："USB-wired for lowest latency"；使用内置 "usbmuxd"；"no WiFi jitter"
  • Features / How it works："Retina / HiDPI"、"@2x HiDPI" 和设备原生面板尺寸
  • Features："hardware H.264 encode"、"TCP_NODELAY"、"frame-drop backpressure with keyframe recovery"
  • Quick start (USB — recommended)：需要连接线、Trust This Computer 和 Screen Recording 权限
./run.sh
材料未说明：README 未说明 USB 模式支持的最大分辨率、帧率和端到端延迟。；README 未列出不同 Mac、iPhone 型号在硬件 H.264 编码上的性能差异。
视情况 我不接受屏幕内容经过项目服务器，也不想注册账户；同时我的 Mac 和 iPhone 只能走 WiFi。OpenDisplay 的隐私模型是否满足我？
适合读者： 在共享 WiFi 上处理敏感代码和客户资料、拒绝第三方云服务与账户注册的 macOS/iOS 用户

视情况：它满足无账户、无项目服务器和本地直连，但 README 对 WiFi 加密有明确限制，不能把共享网络视为安全传输。

  • Features 说明屏幕内容不会经过任何服务器；两端通过一个 TCP 连接直接通信，也不要求注册账户。
  • WiFi 模式使用 Bonjour 自动发现设备，且要求接收端在前台、双方处于同一网络；这降低配置成本，却意味着设备暴露在所在局域网的发现与连接环境中。
  • 项目洞察指出 WiFi 存在当前加密方面的注意事项，建议仅在可信本地网络使用，并结合防火墙和网络隔离。

因此，家庭或受控办公局域网可以满足“自托管、不上云”的约束；若是酒店、访客网或多人共享 WiFi，README 没有提供端到端加密保证，不适合直接承载敏感屏幕内容。

  • Features："your screen never touches anyone's server"；"Self-hosted & private"
  • How it works："The phone listens and the Mac connects"；单一 TCP 连接
  • Quick start (WiFi)：通过 Bonjour 自动发现，双方需处于同一网络
  • 项目洞察 usage_limitations / best_practices：WiFi 加密存在限制，应使用可信本地网络
Open the iPhone app, then pick **"iPhone (WiFi)"** from the Connection menu in the Mac app.
材料未说明：README 节选未说明 WiFi 连接是否使用 TLS、预共享密钥或其他认证机制。；README 未给出 Bonjour 服务是否可被同一局域网其他设备看到的详细边界。
适合 我使用 Swift 和 Xcode 15+，需要修改 VideoToolbox H.264 管线或增加控制消息；这个项目是否适合作为可扩展的代码基础？
适合读者： 负责 Swift、Xcode 15+ 和 Apple 开发者签名流程的开源贡献者，想修改视频传输或输入协议

适合，README 已经公开了主要数据通路和线协议，适合在原有 Swift 实现上扩展。

  • How it works 给出了 CGVirtualDisplay、ScreenCaptureKit、VideoToolbox H.264、TCP 和 AVSampleBufferDisplayLayer 的完整链路，发送、接收和输入回传边界清楚。
  • README 说明所有 socket 内容——帧格式、发现机制、视频格式和控制消息——都写在 PROTOCOL.md，协议跨版本规则在 COMPATIBILITY.md。
  • 项目主体语言是 Swift，Quick start 要求 Xcode 15+；因此你的工具链与项目技术栈直接匹配。

需要注意的是，虚拟显示依赖私有 CGVirtualDisplay API，项目不能上 App Store；如果你的改动要进入公开分发，还会受到签名、公证和 GPL-3.0 分发义务影响。README 没有保证协议新增字段对旧客户端的兼容行为。

  • How it works："CGVirtualDisplay → ScreenCaptureKit → VideoToolbox H.264 → TCP"
  • How it works："Everything that crosses the socket ... is specified in PROTOCOL.md"
  • Quick start："Xcode 15+"
  • 项目数据：main_language 为 Swift；license 为 GNU General Public License v3.0
brew install xcodegen   # project generation
材料未说明：README 节选未给出具体源码模块边界、测试覆盖率和协议新增消息的兼容策略。；README 节选未说明私有 API 在各个 macOS 小版本上的稳定性。
视情况 我有一台运行 macOS 12 的旧 Mac，想把它作为另一台 Mac 的第二显示器，并通过 Thunderbolt 或 Ethernet 连接；OpenDisplay 适合这个部署吗？
适合读者： 维护 macOS 12 的旧 Mac、希望把它作为接收端显示器，并通过 Thunderbolt 或 Ethernet 连接另一台 Mac 的开发者

视情况：接收端版本和连接方式符合 README，但发送端仍需满足 macOS 14+，两台 Mac 的角色不能混淆。

  • Features 明确支持在旧 Mac 上安装 OpenDisplay Receiver，并写明接收端要求 macOS 12+，可通过 WiFi 或 Thunderbolt/Ethernet 连接，使用原生 Retina 分辨率。
  • 项目安装说明区分 Mac sender 与 OpenDisplay Receiver；真正创建虚拟显示器的是发送端，因此发送端的系统要求更高。
  • README 说明 USB 的最低延迟路径主要面向 iPhone/iPad 的 Lightning/USB-C 线缆；两台 Mac 的示例连接是 WiFi 或 Thunderbolt/Ethernet，不应把 usbmuxd 当作 Mac-to-Mac 方案。

如果旧 Mac 只是接收端，方向上可行；如果你希望旧 Mac 同时作为发送端，提供内容没有确认 macOS 12 是否满足发送端要求。接收端键盘和鼠标也不是完整能力。

  • Features："A spare Mac as a display"；"macOS 12+"；支持 "Thunderbolt/Ethernet cable"
  • Install："Mac app (captures and sends)" 与 "OpenDisplay Receiver" 的角色区分
  • 项目洞察 usage_limitations：Mac 发送端要求 macOS 14+；接收端 Mac 要求 macOS 12+
  • 项目洞察 common_pitfalls：另一台 Mac 接收端的键盘和鼠标输入不是完整能力
材料未说明：README 节选未明确发送端 macOS 14+ 要求是否来自正式兼容性表，或是否存在例外。；README 未提供 Mac-to-Mac Thunderbolt/Ethernet 的实际带宽、延迟和刷新率数据。

✨ 核心亮点

  • 支持 USB 与 WiFi 的真实扩展显示
  • VideoToolbox 提供低延迟 H.264 编码
  • Retina @2x 与触控输入开箱可用
  • 无账号、无订阅、无硬件 dongle

🔧 工程化

  • Mac 端创建 CGVirtualDisplay，iPhone 接收 H.264 流。
  • USB 通过 macOS 内置 usbmuxd 连接，无需隧道工具。
  • WiFi 使用 Bonjour 自动发现 iPhone，支持触控与双指滚动。
  • 备用 Mac 可安装 OpenDisplay Receiver，运行 macOS 12+。

⚠️ 风险

  • CGVirtualDisplay 使用私有 API，macOS 更新可能导致故障。
  • WiFi 需要两端 Local Network 权限，否则会静默失败。
  • USB 必须使用支持数据的线，充电线无法连接。
  • 屏幕采集会显示 macOS 紫色录屏指示灯。
  • WiFi 加密存在当前隐患，详情需查看隐私页面。

👥 适合谁？

  • 拥有 iPhone、iPad 或备用 Mac 的 macOS 用户。
  • 需要 USB 低延迟副屏和 Retina HiDPI 的开发者。
  • 能接受 GPL-3.0、Screen Recording 与 Accessibility 权限的用户。
  • 希望自托管、屏幕内容不经服务器的隐私敏感团队。