macOS VirtualBox 一键安装完整指南：3 条命令与 10 次回车装好 macOS 虚拟机
【免费下载链接】macos-virtualboxPush-button installer of macOS Catalina, Mojave, and High Sierra guests in Virtualbox on x86 CPUs for Windows, Linux, and macOS项目地址: https://gitcode.com/gh_mirrors/ma/macos-virtualbox
需要 macOS 环境的场景并不少见：编译 Swift 包、跑 iOS 模拟器、验证一套跨平台 UI，但手头只有一台 Windows 或 Linux 机器。传统做法要自己拼安装镜像、配置 EFI、处理序列号，任何一步出错都得从头再来。macos-virtualbox 把这个过程收敛成一个 Bash 脚本：从 Apple 官方服务器拉取未经修改的 macOS 安装文件，自动创建、分区并启动 VirtualBox 虚拟机，默认安装全程只需要按不超过 10 次回车。
📌 项目定位与核心价值
一句话定位
macos-virtualbox 是一个 "push-button installer"（按钮式安装器）：一个 macos-guest-virtualbox.sh 脚本，在 Windows、Linux、macOS 三类主机的 x86 CPU 上，为 VirtualBox 创建可正常启动的 macOS 客户机。
核心能力
- 官方原始安装文件：直接从 Apple 的
swcdn.apple.com下载，不改动、不重打包，也不引入任何闭源启动器或 bootloader - 三个 macOS 版本：High Sierra (10.13)、Mojave (10.14)、Catalina (10.15)，安装后还可经 Software Update 升级至 Big Sur / Monterey
- 低交互：默认安装只需在脚本提示时按回车（少于 10 次），脚本期间明确要求用户不要手动操作虚拟机窗口
- 分阶段可恢复：安装被拆成 17 个 stage，失败后可指定阶段断点续跑，例如
./macos-guest-virtualbox.sh configure_vm and_all_subsequent_stages - 可选全自动：安装
tesseract-ocr（≥ 4，含 eng 语言包）后，脚本会用 OCR 识别虚拟机屏幕，自动完成语言选择、打开 Terminal 等步骤
✅ 环境自检清单
运行前对照下表逐项确认。脚本自带依赖检查（check_dependencies阶段），缺什么会给出具体提示，提前核对可以少跑几轮。
| 检查项 | 要求 | 备注 |
|---|---|---|
| CPU | x86，支持 VT-x 或 AMD-V | 必须是硬件虚拟化，NEM 回退模式下 macOS 安装会内存损坏，脚本检测到会直接退出 |
| 主机系统 | Windows / Linux / macOS | README 实测环境：macOS、CentOS 7、Windows（Cygwin）；主流 Linux 发行版应可用 |
| VirtualBox | ≥ 6.1.6 | 装 Catalina 至少要 6.1.4；5.2 可能可用但有 VISO 文件系统已知问题 |
| Shell | GNU Bash ≥ 4.3 或 zsh ≥ 5.5 | 需要交互式shell；macOS 自带 bash 3 不可用 |
| 基础工具 | coreutils ≥ 8.22、gzip ≥ 1.5、unzip ≥ 6.0、wget ≥ 1.14、xxd ≥ 1.11 | 需 GNU 版本；macOS 上建议用 Homebrew / MacPorts 安装 |
| dmg2img | ≥ 1.6.5 | Cygwin 下脚本会自动下载，其他平台需自行安装 |
| 可选 | tesseract-ocr ≥ 4 + tesseract-ocr-eng | 启用 OCR 自动操作，免手动回车 |
| 磁盘空间 | 约 50 GB 可用 | 其中约 25 GB 为临时安装文件，装完可删 |
Ubuntu / Debian 上补齐依赖：
sudo apt-get install virtualbox coreutils gzip unzip wget xxd dmg2img tesseract-ocr tesseract-ocr-eng特别注意：Windows 上 Hyper-V、Windows Sandbox、WSL2、内存完整性等功能会占用虚拟化接口，导致 VirtualBox 退到 NEM。脚本检测到 NEM 会报错退出——先关掉这些功能再跑。
🛠️ 搭建全过程
第 1 步：获取安装脚本
git clone https://gitcode.com/gh_mirrors/ma/macos-virtualbox cd macos-virtualbox第 2 步：补齐依赖
按上表安装缺失的包。脚本启动时会自动核对版本，不满足会打印明确的缺失项与最低版本，照装即可。
第 3 步：运行一键安装
chmod +x macos-guest-virtualbox.sh ./macos-guest-virtualbox.sh启动后脚本先展示当前配置（虚拟机名、macOS 版本、磁盘大小等），确认后开始执行。也可以先只看不装：
./macos-guest-virtualbox.sh documentation第 4 步：等待自动完成
脚本期间会两次与虚拟机"交互"（进入语言选择界面、在 Terminal 执行自动脚本），均由脚本模拟按键完成，你要做的只是在终端提示时按回车，全程不到 10 次。两个判断标准：
- 虚拟机 Terminal 里的进度计数器到 100% 并重启，出现 Apple 的 macOS 安装进度条——安装完成
- 脚本提示
prompt_delete_temporary_files阶段——临时文件（约 25 GB）可以删除
⚙️ 参数与调优手册
默认配置无需任何修改即可安装。想定制时，编辑 macos-guest-virtualbox.sh 顶部的set_variables()函数，或用外部变量文件覆盖（脚本支持macos_vm_vars_file机制）：
export macos_vm_vars_file=/path/to/vars.shvars.sh里每行一个变量赋值即可，不用改动主脚本。
关键变量速查
| 变量 | 默认值 | 取值范围 / 说明 |
|---|---|---|
vm_name | macOS | 虚拟机名称 |
macOS_release_name | Catalina | HighSierra/Mojave/Catalina |
storage_size | 80000 | 虚拟磁盘大小（MB），最小 22000；Catalina 要求 ≥ 25000 |
storage_format | vdi | vdi或vmdk。VDI 可被 VirtualBox 在线扩容；VMDK 便于之后导入 QEMU/KVM |
cpu_profile | host | CPU 型号伪装，启动失败时按"踩坑速查"切换 |
cpu_count | 2 | 最小 2 |
memory_size | 4096 | MB，最小 2048 |
gpu_vram | 128 | MB，范围 34–128 |
resolution | 1280x800 | 支持 11 档：5120x2880至640x480，如1920x1200、1440x900 |
三个实用的调优方向
- 磁盘扩容：装完后 VDI 可在 VirtualBox 里直接增大，然后在虚拟机终端执行
sudo diskutil repairDisk disk0，再让 APFS 容器占满（必要时sudo diskutil apfs resizeContainer disk1 0，可能要多试几次重启）。80 GB 的默认虚拟磁盘初始安装后在宿主机上只占约 25 GB。 - 为 QEMU/KVM 准备：把
storage_format设为vmdk（或装完后VBoxManage clonehd --format vmdk source.vdi target.vmdk），之后可以拿到 Linux 上用 KVM 获得接近原生的性能。 - iCloud / iMessage 连通性：脚本写入了一组"仿真 Apple 设备参数"（型号、序列号、主板 SN 等，存于 EFI 与 NVRAM），不设置也能正常安装使用；需要登录 iCloud 时才要关心这组
DmiSystem*/ROM/MLB变量。
📊 实测表现：用数字说话
这个项目的"表现"更多体现在确定性上——数字都来自 README.md 与脚本本身的实际行为，不是营销口径：
| 指标 | 数值 |
|---|---|
| 用户交互次数 | < 10 次回车（安装全程） |
| 安装流水线 | 17 个 stage，任一阶段失败可断点续跑 |
| 默认虚拟磁盘 | 80 GB（storage_size=80000MB） |
| 初始安装宿主机占用 | 约 25 GB（稀疏/动态磁盘） |
| 临时空间需求 | 约 50 GB（25 GB 临时文件装完可删） |
| 支持的 macOS 版本 | 3 个（10.13 / 10.14 / 10.15） |
| 支持的分辨率档位 | 11 档（640x480–5120x2880） |
| VirtualBox 版本跨度 | 5.2（可能）至当前 6.x/7.x，Catalina 需 ≥ 6.1.4 |
对新手来说，最有价值的其实是"可预期"：同样的硬件条件，流程会稳定地走到同一个进度点；卡住时脚本的报错信息本身就是下一步操作指南。
🎯 适合谁、怎么用
- iOS / macOS 开发：在 Windows/Linux 上编译 Swift、跑 xcodebuild、调试跨平台 UI，不必为每个项目申请一台 Mac
- 自动化与批量环境：脚本支持非交互 shell（需搭配 tesseract-ocr），配合
vars.sh变量文件可以脚本化地批量拉起同构 macOS 环境 - 学习与教学：单文件、1700+ 行、注释密集的脚本本身就是 VirtualBox
VBoxManage、EFI/NVRAM、macOS 安装流程的一份可执行教材 - QEMU/KVM 过渡方案：用
vmdk格式把虚拟机"养成"在 VirtualBox 里，再迁移到 Linux KVM 上获得硬件直通性能——README 明确推荐这条路径
🚨 踩坑速查
高频问题基本都写在脚本的报错和 README.md 里，按现象对照处理：
| 现象 | 原因 | 解法 |
|---|---|---|
| 脚本提示检测到 NEM 后退出 | Hyper-V、WSL2、内存完整性等占用了 VT-x/AMD-V | 关闭这些功能；Windows 上优先用 WSL1 或 Cygwin 跑脚本 |
启动卡在LoadKernelFromStream/EndRandomSeed/EXITBS | 较新的 CPU（2020 年后常见）不被 macOS 识别 | 关机状态下依次尝试--cpu-profile host+--cpuidremoveall，再逐个换预置 CPU profile（i7-2635QM、i7-5600U 等 6 种） |
| Catalina 装不上，脚本报版本错误 | VirtualBox < 6.1.4 | 升级 VirtualBox |
| 下载 Apple 文件失败，提示证书不受信任 | 宿主机缺 CA 证书 | 安装ca-certificates包 |
| 装完系统后磁盘空间不够 | 虚拟磁盘是 80 GB 上限 | 扩容 VDI 后执行diskutil repairDisk+ APFS 扩容（见调优手册） |
| 升级 Monterey 后反复重启 | 原地升级不稳定 | 挂第二块虚拟盘并选它作为安装目标 |
| 声音 / 显示缩放 / FileVault 密码提示不正常 | 属于 VirtualBox 与 macOS 的既有限制，不在脚本范围内 | 需要 OpenCore 等额外配置，脚本明确标注 out of scope |
排查时先跑./macos-guest-virtualbox.sh troubleshoot，会生成包含系统信息、VirtualBox 日志和安装文件校验和的诊断文件，方便定位。
🔍 项目内幕：一个脚本怎么干完所有事
仓库只有三个文件，结构极简：
| 文件 | 说明 |
|---|---|
| macos-guest-virtualbox.sh | 全部逻辑，1700+ 行，17 个 stage |
| README.md | 使用说明与已知限制 |
| LICENSE | GPL 2.0 或更高版本 |
工作原理可以拆成五条主线：
- 拿官方文件：先拉 Apple 的
swscan.apple.comsucatalog，解析出InstallAssistantAuto.smd的下载基址，再取回BaseSystem.dmg、InstallESDDmg.pkg等原始文件；超过 2 GB 的 pkg 会切成 1 GB 分卷，绕开 VirtualBox VISO 与 ISO9660 的单文件限制 - 造虚拟介质：用
dmg2img把BaseSystem.dmg转成磁盘镜像，再用 VirtualBox 的 VISO 机制把安装文件、EFI 启动脚本、NVRAM 二进制文件打包成虚拟光驱 - 写 NVRAM：用
xxd+gzip（crc32）手工构造MLB、ROM、system-id、csr-active-config四个 NVRAM 条目的二进制文件，启动后经 EFI Shell 的dmpstore写入，满足 iCloud 等设备识别需求 - 自动操作虚拟机：脚本内置了一张完整的 QWERTY 键盘 scancode 表，通过
VBoxManage controlvm keyboardputscancode逐键模拟输入，替你点语言选择、开 Terminal、执行分区与startosinstall脚本 - OCR 兜底全自动：装了 tesseract 后，脚本会定时截图虚拟机并识别屏幕文字（Language 界面、Utilities 菜单），匹配成功就自动按键，彻底免交互
整个流程以stages数组驱动，每个 stage 都是可独立调用的函数——这也是断点续跑能力的来源。
🤝 持续维护与贡献
- 版本与许可：当前脚本版本 0.99.2.4，GPL 2.0 or higher
- 维护者招募中：README 明确标注 "Maintainer wanted"，并在 issue #645 中征集新维护者。项目功能稳定但缺少活跃维护，这正是参与者能产生实际价值的窗口
- 贡献路径：克隆仓库 → 复现一个 issue（CPU 兼容性、WSL 路径问题、报错文案是常见方向）→ 修复后提交。脚本"大部分内容是文档、注释和可执行的错误信息"，阅读门槛比一般脚本低不少
- 边界提醒：OpenCore 音频/显示缩放、FileVault、QEMU/KVM 迁移、配置管理批量部署都在脚本声明的范围之外，做相关改进时建议作为独立文档或工具，而不是塞进主脚本
🚀 第一步行动建议
不用一次看完再动手，按这个顺序走最稳：
git clone https://gitcode.com/gh_mirrors/ma/macos-virtualbox cd macos-virtualbox ./macos-guest-virtualbox.sh documentation # 先通读文档 ./macos-guest-virtualbox.sh # 准备就绪后正式开跑跑之前花两分钟对照"环境自检清单"把 VirtualBox 版本和 50 GB 空间确认掉；跑的过程中如果卡住，把终端提示的 stage 名称记下来，配合troubleshoot命令基本就能对上"踩坑速查"表里的解法。
【免费下载链接】macos-virtualboxPush-button installer of macOS Catalina, Mojave, and High Sierra guests in Virtualbox on x86 CPUs for Windows, Linux, and macOS项目地址: https://gitcode.com/gh_mirrors/ma/macos-virtualbox
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考