macUSB开发者指南：如何为项目扩展新操作系统与镜像类型支持

【免费下载链接】macUSBThe all-in-one bootable USB creator for Mac项目地址: https://gitcode.com/gh_mirrors/mac/macUSB

macUSB 是一款面向 macOS 的一体化可启动 U 盘制作工具，支持将 macOS、Windows、Linux 的 ISO 镜像写入 USB。如果你想在项目中扩展一种新的操作系统或镜像类型支持，本文带你读懂它的架构分层与四大核心扩展点：分析识别、工作流路由、特权 Helper 守护进程，以及图标与文档契约。

一、先读懂 macUSB 的架构分层

macUSB 采用「主应用 + 特权守护进程」双层架构，扩展新系统时你需要同时理解这两层：

详细的文件职责映射见 FILE_STRUCTURE.md，文档总入口见 docs/reference/README.md。

💡 核心原则：分析阶段的识别标志（flags）是工作流分支选择的唯一事实来源。识别结果决定是否解锁安装流程，这是新增系统时必须遵守的第一契约。

二、核心扩展点 1：在分析阶段接入新的镜像识别

识别链路按固定的优先级执行：macOS 安装器 → Windows 回退 → Linux 回退。新增系统类型通常意味着在这条链上插入新的识别分支。

以 Linux 识别为例，它只在满足以下条件时触发：源文件为.iso、未被「已手动挂载」守卫拦截、且未检测到 macOS 安装器元数据。

识别实现必须遵守的性能契约：

• 有界白名单读取：只读取有限的元数据文件（如.treeinfo、boot/grub/grub.cfg、dists/*/Release），禁止递归解包 rootfs；
• 全局 20 秒超时：整个.iso分析会话受 20 秒超时保护，超时强制结束并卸载挂载；
• bsdtar兜底：挂载读取失败时，用bsdtar -tf/-xOf做带 10 秒超时的归档索引读取。

相关契约与实现：

• 识别与兼容性总契约：ANALYSIS_COMPATIBILITY.md
• Linux 识别流程细则：LINUX_ANALYSIS_FLOW.md
• Windows 识别流程细则：WINDOWS_ANALYSIS_FLOW.md
• 分析状态门面（UI 绑定入口）：AnalysisLogic.swift
• 各系统检测实现：AnalysisLogicLinuxDetection.swift、AnalysisLogicWindowsDetection.swift

识别成功后，还要产出标准化的检测结果：发行版/系列、版本、架构（32-bit/64-bit/ARM）与证据列表，供日志与 UI 展示使用。分类规则的两层结构值得借鉴：

• 高置信专用规则：为流行发行版写确定性规则（如 NixOS、Garuda、Gentoo），见 AnalysisLogicLinuxClassification.swift；
• 目录式信号匹配：对更多发行版基于有界元数据字段做信号匹配，未匹配到时降级为「未知发行版」而非识别失败。

三、核心扩展点 2：接入安装工作流与阶段映射

识别成功后，新系统要解锁共享安装流程：UniversalInstallationView（摘要确认）→CreationProgressView（进度）→FinishUSBView（收尾）。扩展工作包括：

1. 流程上下文与请求构造：参照 CreatorLinuxLogic.swift 与 CreatorWindowsHelperLogic.swift，为新系统构造 Helper 请求；
2. 阶段映射：把 Helper 返回的阶段名映射到共享进度 UI，参照 CreationProgressLinuxMapping.swift；
3. 容量与目标校验：按源文件大小计算所需 USB 容量（8/16/32 GB 三档），Windows 流程还需 FAT32/MBR 格式化与wimlib-imagex工具链探测；
4. 摘要屏信息卡片：如 Linux 流程提示「磁盘不可读弹窗点忽略」、Windows 流程提示「仅支持 UEFI 启动」。

完整阶段序列与不变量（如 Linux 必须整盘写入diskX、禁止分区节点）定义在 USB_CREATION_WORKFLOWS.md，USB 目标校验规则见 USB_VALIDATION_AND_CAPACITY.md。

四、核心扩展点 3：为 Helper 守护进程新增特权工作流

所有特权磁盘操作必须经由 Helper（SMAppService + XPC）执行，主进程禁止终端回退提权。Helper 端为每个系统维护独立的 Workflow 分支：

• Linux 分支（卸载目标盘 →dd原始写入 → SHA-256 校验）：macUSBHelper/Workflow/Linux/
• Windows 分支（ISO 拷贝 → 可选 WIM 拆分 → 启动文件校验）：macUSBHelper/Workflow/Windows/
• 工作流执行器入口：HelperWorkflowExecutor.swift

为 macOS 提供完整磁盘访问权限是 Helper 正常工作的前提：

新增工作流阶段时，请对照各阶段的进度解析（如 HelperWorkflowLinuxProgressParsing.swift）实现确定性进度上报，并保证 UI 阶段推进始终可预测。权限与启动门控契约见 PERMISSIONS_AND_BACKGROUND.md。

五、图标、别名与本地化收尾

🎨 新发行版/系统图标有成熟的接入路径：

• 将 PNG（512×512）放入 macUSB/Resources/Icons/Linux/Distros/；
• 在 AnalysisLogicLinuxLifecycle.swift 的LinuxDistroIconCatalog中把图标名加入names列表，并在aliases中补充「显示名 → 图标名」别名（如pop os→pop）；
• 运行时按「发行版图标 → 通用linux.icns→ SF Symbol」三级回退加载，未收录名称会自动降级，不会崩溃。

别忘了本地化目录 Localizable.xcstrings，新系统的所有用户可见文案都需入库，契约见 LOCALIZATION_CONTRACT.md。

六、提交前检查清单 ✅

1. 新识别分支是否遵守「有界读取 + 20 秒全局超时 + 已挂载守卫」？
2. 不支持的结果是否走明确的「unsupported」呈现，而非静默失败？
3. 阶段推进是否确定性？取消/失败/超时路径是否都释放了挂载与自动挂载守卫？
4. 日志是否包含：分支切换、解析细节、证据列表、清理结果？
5. 是否更新了受影响的 reference 文档？项目维护规则要求：行为变化时更新最小的相关 reference 文件，跨切面变化则更新所有受影响文件（见 docs/reference/README.md 的 Maintenance Rule）。

macUSB 每个特性文档都附有「Update Trigger」小节，明确告诉你哪些行为变化必须同步文档——照着它走，你的新操作系统支持就能与项目现有契约平滑共存。🚀

【免费下载链接】macUSBThe all-in-one bootable USB creator for Mac项目地址: https://gitcode.com/gh_mirrors/mac/macUSB