OpenCore Legacy Patcher 3.0.0 指南：旧 Mac 装上新版 macOS
项目地址: https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher OpenCore Legacy Patcher 是基于 OpenCorePkg 与 Lilu 的 Python 补丁工具，让 Apple 已停止支持的旧款 Intel Mac 能安装并运行 macOS Big Sur 至 Tahoe。它只覆盖全新安装与大版本升级两条路径：不支持 PowerPC 机型与 Apple Silicon，也接不了被 Patched Sur、bigmac 等其他补丁器改过、文件完整性已破坏的系统。3.0.0 版本新增 macOS Tahoe 支持，改进了无线与非 Metal 图形补丁，OpenCore 升至 1.0.5。读完本文，你能完成机型核验、EFI 分区写入、全新安装与系统卷根补丁的完整闭环。
环境核对与风险提示
动手前先核对运行环境，任一项不达标先补齐再继续。
| 项目 | 最低要求 | 不满足时的具体后果 |
|---|---|---|
| 补丁器运行系统 | macOS 10.10+ | 装不出 Python 源码运行环境，pip3 install 直接失败 |
| Python | 3.6+，须从 python.org 官方源安装（3.11 与构建服务器一致，更稳） | 系统预装或 Xcode 附带的 Python 明确不受支持，会因可靠性问题报错 |
| 芯片 | Intel，Penryn 及更新 | PowerPC 与 Apple Silicon 机型不在支持范围 |
| 机型标识 | 须见于 docs/MODELS.md 白名单 | 构建能完成，但写出的引导盘无法启动 |
| 内存 | 3GB+（目标系统为 Sonoma 及以上时） | 2GB 机型无法安装 Sonoma/Sequoia，Sequoia 可能无法启动 |
| 网络 | 首次根补丁需下载 KDK、MetallibSupportPkg | 离线时可能只先装上 Wi-Fi 驱动，其余补丁缺失 |
⚠️ 本流程会写入目标磁盘的 EFI 分区与系统根卷，分区写错数据无法找回。执行任何写入前，先用 Time Machine 或 ASR 备份重要数据。
核心操作流程
拉取源码并装齐依赖
做什么：拿到可运行的源码环境，10 个 Python 依赖全部就位。
怎么做：
git clone https://gitcode.com/GitHub_Trending/op/OpenCore-Legacy-Patcher
cd OpenCore-Legacy-Patcher
pip3 install -r requirements.txt
requirements.txt 列了 10 个依赖，核心是 wxpython、pyobjc、py_sip_xnu。安装报错时，换 Python 3.11 重装再试；完整流程见 SOURCE.md。
怎么确认：pip 输出以 Successfully installed 收尾；pip3 show wxpython 返回已安装版本号。查不到版本说明依赖未装上，后续 GUI 会直接崩溃，先解决依赖再继续。
机型标识对进白名单
做什么：确认本机机型标识在支持名单内，避免后续写入 EFI 后返工。
怎么做：
sysctl -n hw.model
把输出（形如 iMac12,2）拿到 docs/MODELS.md 的机型表中对号，顺带记下该机型标注的可用系统与已知问题。
怎么确认：终端打印出机型标识，且能在 MODELS.md 表中查到对应行及其系统版本区间。查不到就到此为止，不要再碰 EFI 分区——不在名单的机型强行写入只会得到无法启动的盘。
构建 OpenCore 并写入 EFI 分区
做什么：生成与本机绑定的引导配置，把引导器写进目标磁盘的 EFI 或 FAT32 分区。
怎么做：
python3 OpenCore-Patcher-GUI.command
python3 OpenCore-Patcher-GUI.command --build --model iMac12,2 --hide_picker --verbose
GUI 主菜单弹出后，先核对界面显示的 macOS 版本、机型与 GPU 是否与 sysctl 输出一致，再进入 Build 菜单选盘写入。常用参数：--model iMac12,2 指定目标机型，--hide_picker 隐藏启动选择器，--verbose 开详细日志，-h 查看全部参数。
⚠️ 生成的配置与这台机器绑定，机型选错时写出的引导配置可能根本起不来。
怎么确认：按提示选盘、选分区后写入成功，所选分区中出现 OpenCore 引导文件；重启后出现 OpenCore 启动选择器。看不到选择器说明写错分区或 NVRAM 未指向引导器，回到本阶段重选分区，并保留 --verbose 日志定位。
全新安装后给系统卷打根补丁
做什么：替换系统里缺失的图形等组件，重建内核缓存，恢复硬件加速。
怎么做：全新安装进入桌面后执行：
python3 OpenCore-Patcher-GUI.command --patch_sys_vol
python3 OpenCore-Patcher-GUI.command --unpatch_sys_vol # 回退用
首次打补丁若需联网下载 KDK、MetallibSupportPkg 等包，可能只先装上 Wi-Fi 驱动，联网后重跑一次 --patch_sys_vol 补全其余补丁。2.5.0 起对"脏根卷"的重复打补丁有拦截，防止半覆盖补丁引发故障。
怎么确认：界面提示补丁应用完成、内核缓存重建成功；重启后 system_profiler SPDisplaysDataType 显示显卡加速可用。若图形仍无加速，先确认已重启，再重跑一次补丁命令。
工作原理速览
全程不碰固件、不动硬件。UEFI 阶段，OpenCore 把老机器的 SMBIOS 伪装成受支持机型，骗过系统机型校验，这一步只写 EFI 分区；内核启动后，Lilu 在内存里补回被移除的符号，只动内存不落盘；payloads/Kexts/ 携带图形、音频、无线等内核扩展补齐缺失驱动；根补丁则重建内核缓存、替换根卷框架，把图形加速能力写回磁盘——这是整条链路中唯一动根卷的一步。
| 组件 | 作用 | 是否持久化 |
|---|---|---|
| OpenCore | UEFI 阶段注入受支持机型 SMBIOS | 写入 EFI 分区 |
| Lilu + WhateverGreen | 内存中补回缺失符号与框架 | 仅内存，重启失效但自动重装 |
| payloads/Kexts | 提供图形、音频、无线、网络扩展 | 写入 EFI 分区 |
| 根补丁 | 重建内核缓存、替换根卷框架 | 写入根卷 |
完成后的验证与常见问题
装完先跑一遍自查，再处理异常。
| 检查项 | 命令 | 期望看到的关键输出 |
|---|---|---|
| 引导器是否生效 | nvram -p | 输出中能看到 OpenCore 引导器版本信息 |
| 图形与运行时扩展 | kextstat | 列表中出现 Lilu、WhateverGreen |
| Wi-Fi 驱动 | kextstat | 列表中出现 AirPortBrcmFixup |
| 图形加速 | system_profiler SPDisplaysDataType | 显卡信息显示加速可用 |
重启后没进新系统，直接落回旧系统 → NVRAM 读不到引导器信息，引导器没跑起来，多半是写错了分区。 → 重跑 python3 OpenCore-Patcher-GUI.command --build 重选分区写入，并加 --verbose 拿详细日志定位。
Wi-Fi 图标灰着不可用 → kextstat 里没有 AirPortBrcmFixup，无线芯片没被正确识别。 → 重跑 python3 OpenCore-Patcher-GUI.command --build，让程序重新检测无线芯片后再生成配置。
大版本 OTA 更新后图形掉回无加速 → OTA 更新重建了根卷，根补丁随之失效。 → 重跑 python3 OpenCore-Patcher-GUI.command --patch_sys_vol 一条命令即可恢复加速。
更多排障条目见 docs/TROUBLESHOOT-MISC.md 与 docs/TROUBLESHOOTING.md。
收束
OpenCore Legacy Patcher 只覆盖全新安装与升级，不改固件，也接不了其他补丁器留下的环境；目标系统为 Sonoma 及以上时内存须达到 3GB+。满足机型白名单的前提下，先备份，再从机型核验阶段开始动手。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
