MirageKit开发与贡献指南:如何构建项目并运行200+测试用例(含最佳实践)
MirageKit开发与贡献指南:如何构建项目并运行200+测试用例(含最佳实践)
MirageKit 是一个开源的点对点(P2P)屏幕共享框架,可以把 macOS 的桌面、窗口或应用流式传输到 iPadOS、visionOS 甚至另一台 macOS 设备上。本指南带你从零完成 MirageKit 项目的克隆、构建,并运行其 200+ 个测试文件、1800+ 个测试用例,最后分享项目贡献时的最佳实践,帮助你以正确姿势参与开发。
环境准备:一键检查你的开发环境
在开始构建 MirageKit 之前,先确认本地环境满足以下最低要求:
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS(宿主端需 macOS 26+;客户端 iOS 26+ / visionOS 26+) |
| Swift 版本 | Swift 6.2+(启用严格并发检查) |
| Xcode | Xcode 26.2(与官方 CI 环境一致) |
| 构建工具 | Swift Package Manager(Xcode 自带) |
MirageKit 的最低平台与工具链版本在 Package.swift 中声明,官方 CI 在 macos-26 上使用 Xcode 26.2 执行构建与测试,配置见 .github/workflows/ci.yml。
克隆仓库:
git clone https://gitcode.com/gh_mirrors/mi/MirageKit
cd MirageKit
如何构建项目:两条命令搞定
MirageKit 是一个标准 Swift Package,构建只需一条命令:
swift build --package-path .
首次构建会自动拉取唯一的外部依赖 Loom(P2P 传输层),稍后会有编译输出,属于正常现象。若涉及宿主端集成相关的修改,官方建议额外执行宿主应用的集成构建:
xcodebuild -project Mirage.xcodeproj -scheme 'Mirage Host' -configuration Debug -destination 'platform=macOS' build
💡 提示:构建报错大多来自 Swift 版本过低或平台版本不满足。MirageKit 基于 Swift 6.2 的严格并发(strict concurrency)基线开发,旧工具链会报出大量
Sendable相关错误,升级 Xcode 即可解决。
如何运行 200+ 测试用例
MirageKit 的测试全部基于 Swift Testing 框架编写。运行完整测试套件:
swift test --package-path .
测试代码按目标(target)组织在 Tests/ 目录下,共 4 个测试目标、248 个测试文件、1800+ 个 @Test 用例:
| 测试目标 | 文件数 | 覆盖范围 |
|---|---|---|
| Tests/MirageKitTests/ | 33 | 协议编解码、流几何、剪贴板分块、诊断策略等公共能力 |
| Tests/MirageKitHostTests/ | 105 | 捕获、编码、虚拟显示、流量灯保护、接收循环等宿主端逻辑 |
| Tests/MirageKitClientTests/ | 107 | 解码、帧重组、回放缓冲、恢复协调器、输入捕获等客户端逻辑 |
| Tests/MirageHostBootstrapRuntimeTests/ | 3 | 登录前引导守护进程状态机、网络探测、配置 |
也可以只跑某个目标,例如只验证宿主端:
swift test --filter MirageKitHostTests
理解包结构:先看 5 个产品再动手改代码
动手改代码前,先搞清楚 MirageKit 的分层。Package.swift 定义了 5 个可引用的产品(products):
- MirageKit:公共类型与协议(
MessageTypes、输入事件、编解码器等),自动随其他产品引入; - MirageKitClient:客户端——连接宿主、解码渲染、转发输入;
- MirageKitHost:宿主端——屏幕捕获、编码、对外提供服务;
- MirageBootstrapShared / MirageHostBootstrapRuntime:登录前引导与远程解锁支持。
源码布局遵循"公共 API 与实现分离"的约定(见 AGENTS.md):
Sources/
├── MirageKit/ # 公共协议与类型(Public/ + Internal/)
├── MirageKitClient/ # 客户端管线(Public/ + Internal/)
├── MirageKitHost/ # 宿主端管线(Public/ + Internal/)
├── MirageBootstrapShared/
└── MirageHostBootstrapRuntime/
以协议层为例,控制消息按领域拆分为多个扩展文件,位于 Sources/MirageKit/Internal/Protocol/ 目录,如 MessageTypes+Connection.swift、MessageTypes+Input.swift 等。阅读 README.md 可快速了解各产品职责。
贡献最佳实践:项目编码规范清单
MirageKit 的贡献门槛在于遵循 AGENTS.md 中约定的规范,以下是最常被检查的要点:
命名与组织
- 4 空格缩进;类型名
UpperCamelCase,成员名lowerCamelCase; - 公共 API 类型统一保留
Mirage前缀; - 一个文件优先只放一个主类型,大文件用
// MARK: -分区; - 文件尽量控制在约 500 行以内,超了就拆分职责;
- 新 Swift 文件需包含标准文件头(
Created by Ethan Lipnik与准确日期)。
并发与代码风格
- Swift 6.2 严格并发基线,
@Observable类必须是@MainActor; - 优先使用 Swift 并发(async/await)而非 GCD;
- 用
Task.sleep(for:)而非Task.sleep(nanoseconds:); - 避免强制解包和强制
try(除非失败确实不可恢复)。
兼容性红线
- 这是已发布的包:公共 API、线协议、持久化数据格式默认不可破坏,除非任务明确授权;
- 新增公共 API 要少而精,并附带文档;未经明确批准不得引入第三方依赖;
- 发布时 git tag 必须与
MirageKit.version完全一致。
📌 一个值得注意的友好约定:项目大部分代码由 AI 编码工具协助完成,官方明确欢迎使用 AI 辅助开发——前提是你理解并能解释所提交的内容。
测试规范:新测试该放在哪
新增测试必须使用 Swift Testing,并放入与被测目标匹配的位置(见 AGENTS.md):
- 改
Sources/MirageKit/→ 测试写入Tests/MirageKitTests/; - 改
Sources/MirageKitHost/→ 测试写入Tests/MirageKitHostTests/; - 改
Sources/MirageKitClient/→ 测试写入Tests/MirageKitClientTests/。
可以参考现成的测试写法,例如帧重组恢复逻辑 FrameReassemblerKeyframeRecoveryTests.swift、宿主端接收循环 HostReceiveLoopTests.swift。提交前务必本地跑通全量 swift test,与 CI 保持一致。
重要提醒:了解 PolyForm Shield 许可证
MirageKit 采用 PolyForm Shield 1.0.0 许可证(详见 LICENSE)。它对个人使用和修改非常友好,但有一条关键限制:
允许用于非竞争产品;禁止将其用于与 Mirage 或其他专用远程窗口/桌面/副屏/数位板流式传输应用相竞争的产品。
因此,如果你的目标是"做一个远程桌面产品",先确认自己的场景不落入竞争禁区,再开始基于 MirageKit 开发。
常见问题速查
| 现象 | 可能原因与处理 |
|---|---|
swift build 报大量 Sendable/并发错误 |
Swift 版本低于 6.2,升级 Xcode 至 26.2 |
构建找不到 ScreenCaptureKit 相关符号 |
需在 macOS 26+ 环境构建,Linux/旧系统不支持 |
| 依赖拉取缓慢或失败 | 检查网络;Loom 是外部依赖,首次构建需要联网 |
| 测试个别失败 | 先单独运行对应 --filter 目标,确认是否为环境差异 |
小结
MirageKit 为 Apple 平台提供开箱即用的点对点窗口与桌面流式传输能力。作为开发者,你只需三步即可上路:
- 确认 macOS 26+ 与 Swift 6.2+ 环境,克隆仓库;
swift build --package-path .构建,swift test --package-path .跑通 1800+ 测试用例;- 遵循 AGENTS.md 的命名、并发与兼容性规范,把新测试放进对应目标目录,即可提交贡献。
祝你在 MirageKit 的世界里玩得开心!🎉