MirageKit开发与贡献指南:如何构建项目并运行200+测试用例(含最佳实践)

原创2026-11-15 10:20:281,906 阅读

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 平台提供开箱即用的点对点窗口与桌面流式传输能力。作为开发者,你只需三步即可上路:

  1. 确认 macOS 26+ 与 Swift 6.2+ 环境,克隆仓库;
  2. swift build --package-path . 构建,swift test --package-path . 跑通 1800+ 测试用例;
  3. 遵循 AGENTS.md 的命名、并发与兼容性规范,把新测试放进对应目标目录,即可提交贡献。

祝你在 MirageKit 的世界里玩得开心!🎉

登录后查看全文
MirageKit