SerenityOS 在 VMware 中安装与引导实战指南：从 GRUB 镜像转换到虚拟机启动

本篇指南基于 SerenityOS 官方文档 Documentation/VMware.md 编写，完整介绍如何在 VMware Player/Workstation 中运行 SerenityOS：从构建并生成 GRUB 磁盘镜像、使用 QEMU 工具转换为 VMDK 格式，到逐步创建虚拟机并成功引导。读完本文，你将掌握一套可复现的 VMware 部署流程，并了解该场景下已知的功能限制与内核级故障排查手段。

前置准备：构建 SerenityOS 并生成 GRUB 磁盘镜像

在接触 VMware 之前，必须先为本机构建出一份可用于实机/虚拟机引导的 SerenityOS 镜像。官方在 SerenityOS 安装指南 中给出了完整步骤，这里提炼其关键路径：

1. 构建操作系统：按照 构建指南 完成工具链与系统构建，执行到 ninja install（脚本入口为 Meta/serenity.sh image <arch>）为止。Meta/serenity.sh 支持 aarch64、x86_64、riscv64 等目标架构，默认取宿主架构。
2. 生成 GRUB 镜像：继续执行 ninja grub-image（传统 BIOS）或 ninja grub-uefi-image（UEFI），产物分别为 grub_disk_image 与 grub_uefi_disk_image。该命令依赖宿主机安装 parted 与 GRUB 2（如 Arch 上为 grub 包）。

从仓库根 CMakeLists.txt 可以看到，这两个自定义目标仅在 SERENITY_ARCH 为 x86_64 时注册，且分别调用 Meta/build-image-grub.sh 与 Meta/build-image-grub-uefi.sh。展开 build-image-grub.sh 的源码可以看到镜像生成的真实流程：

• 自动以 sudo 提升权限运行（脚本开头检测 grub-install 或 grub2-install 是否存在）；
• 用 dd 创建约 800 MiB（大小按 Base 目录与 Root 目录用量动态计算）的原始磁盘镜像；
• 通过 losetup 挂载为循环设备，用 parted 创建 MSDOS 分区表（默认/MBR 模式下 mkpart primary ext2 1MiB 100% 并设置 boot 标志；GPT 模式则创建 BIOS boot 分区与 OS 分区）；
• 以 mke2fs 格式化 ext2 文件系统，挂载后调用 build-root-filesystem.sh 写入系统文件；
• 用 grub-install --target=i386-pc --modules="ext2 part_msdos" 安装引导器，并将 Meta/grub-*.cfg 复制为 mnt/boot/grub/grub.cfg（或 grub2/ 目录）。

务必注意 VMware 场景下的两个关键约束：

• 跳过原安装指南的最后一步：BareMetalInstallation 文档中把镜像 dd 写入真实磁盘（如 sudo dd if=grub_uefi_disk_image of=/dev/sdx bs=64M && sync）的步骤只适用于物理机，VMware 场景不需要执行；
• 不能直接使用 QEMU 镜像：为 QEMU 生成的 _disk_image 不含可引导的 GRUB 引导器，直接挂载到 VMware 会立即停止并报错 FATAL: No bootable medium found! System halted.。必须使用上面的 GRUB 镜像作为转换源。

将 GRUB 磁盘镜像转换为 VMDK

官方推荐的镜像转换方式是借助 QEMU 自带的磁盘工具 qemu-img，一行命令即可完成格式转换：

qemu-img convert -O vmdk /path/to/grub_disk_image /path/to/output/serenityos.vmdk

参数说明：

• -O vmdk：指定输出格式为 VMware 的 VMDK 磁盘格式；
• 输入路径：上一步生成的 grub_disk_image（传统 BIOS 引导镜像，与 VMware 的 BIOS 固件配合最稳妥）；
• 输出路径：建议保存为 serenityos.vmdk，后续在 VMware 中直接挂载。

如果宿主机没有 QEMU，也可以参考同仓库的 VirtualBox 安装指南 使用 VBoxManage convertfromraw 等其他工具完成原始镜像到虚拟磁盘格式的转换，其思路完全一致：先得到 GRUB 镜像，再做格式转换。

在 VMware 中创建 SerenityOS 虚拟机

官方文档以 VMware Player 15 为例撰写（不同版本及 Workstation 的界面措辞可能略有差异），创建虚拟机的过程与普通虚拟机类似，核心差异在于挂载转换好的 VMDK 镜像。完整步骤如下：

1. 打开 Create a New Virtual Machine（创建新虚拟机） 向导，选择 I will install the operating system later（稍后安装操作系统）；
2. 在客户机操作系统类型中选择 Other（其他）；
3. 虚拟机名称与存放位置可随意设置；
4. 硬盘大小随意指定——这块临时硬盘稍后会被移除并替换为转换好的 GRUB 镜像；
5. 点击 Finish 完成虚拟机创建；
6. 选中新建的虚拟机，点击 Edit virtual machine settings（编辑虚拟机设置）；
7. 内存配置：Serenity 至少需要 512 MiB 内存，请将 Memory for this virtual machine 设为 ≥ 512 MiB，官方当前推荐 1 GiB；
8. 选中现有的 Hard Disk（硬盘） 并点击 Remove（移除）；
9. 点击 Add（添加） → 选择 Hard Disk（硬盘） → 选择 IDE (Recommended) → 选择 Use an existing virtual disk（使用现有虚拟磁盘）；
10. 点击 Browse（浏览） 定位到上一步转换好的 VMDK 镜像并添加，点击 Finish；
11. 最后点击 Save（保存），即可 Power On（开机） 启动虚拟机。

其中第 9 步选择 IDE 控制器 是官方明确推荐的做法，这与 SerenityOS 当前对磁盘控制器的支持范围直接相关（详见下文配置要点）。

配置要点解析：内存与磁盘控制器

对照 VirtualBox 安装指南 中“控制器必须为 AHCI(SATA) 或 NVMe，否则无法启动”的约束可以看出，SerenityOS 对虚拟化平台的外设支持是逐步完善的，VMware 场景下的官方配置遵循其最保守、最兼容的路径：

• 内存：SerenityOS 内核在实机要求最低 256 MB RAM（见 BareMetalInstallation.md），但虚拟机环境下官方将 VMware 的最低内存门槛定为 512 MiB，推荐 1 GiB，以给图形栈与 WindowServer 留足余量；
• 磁盘控制器：官方要求挂载 VMDK 时选择 IDE (Recommended) 接口。如果沿用默认的 SCSI/SAS 控制器，GRUB 与内核可能无法枚举到引导分区，表现为开机即停或进入不了系统；
• 固件类型：由于文档指定的是 grub_disk_image（BIOS 版 GRUB 镜像），虚拟机应保持默认的 BIOS 固件而非 UEFI 引导。

已知限制：音频与网络

官方文档明确说明，截至撰写时 VMware 中音频与网络均不可用。这意味着：

• 声卡设备（Intel AC'97 / HDA 等 Serenity 已支持的型号）在 VMware 虚拟化环境下无法被正确驱动或没有可用输出；
• 网卡方面，Serenity 目前主要支持 Intel e1000 与 Realtek 8168 芯片组（见 BareMetalInstallation.md），但 VMware 虚拟网卡的兼容情况并不理想。

这与 VirtualBox.md 中“音频和网络同样不可用”的描述一致：SerenityOS 对虚拟化平台的外设支持仍处于持续开发阶段。官方在 VMware.md 开头也挂有 NOTICE 提示，指出目前存在若干已知问题，凡是当前不可用的功能都会在文档中注明，读者应以该文档及对应 issue 追踪列表为准。

故障排查：GRUB 菜单与内核命令行参数

如果在 VMware 中出现无法引导、黑屏或启动卡死，可以从 GRUB 菜单与内核参数两个层面着手。

灵活使用 GRUB 菜单项

GRUB 镜像内嵌的菜单配置位于仓库 Meta/grub-gpt.cfg（BIOS 版对应 Meta/grub-mbr.cfg），默认提供四个启动项，每个都带有可复用的内核参数：

菜单项	内核参数	适用场景
SerenityOS (normal)	默认	标准图形模式启动
SerenityOS (text mode)	graphics_subsystem_mode=off	禁用图形子系统，纯文本模式
SerenityOS (No ACPI)	acpi=off	关闭 ACPI，应对 VMware 的 ACPI 兼容问题
SerenityOS (with serial debug)	serial_debug	开启串口调试输出

图形子系统模式：graphics_subsystem_mode

若虚拟机启动后屏幕无输出或卡在图形初始化阶段，可在 GRUB 菜单按 e 编辑内核命令行，追加 graphics_subsystem_mode=limited 强制内核不初始化任何帧缓冲设备，从而以纯控制台模式引导；SystemServer 检测到该条件后不会启动 WindowServer（详见 BareMetalInstallation.md）。

该参数在内核源码中有完整的三态实现（Kernel/Boot/CommandLine.cpp）：取值为 on（默认）、limited、off，非法值会触发内核 PANIC。图形设备管理层（Kernel/Devices/GPU/Management.cpp）在 Disabled 模式直接跳过所有 GPU 初始化，Limited 模式则仅使用引导帧缓冲，这正是上述故障排查命令的底层原理。

无串口环境下的引导排错

如果屏幕完全没有输出，说明内核可能在视频初始化之前就已崩溃。此时可尝试：

• 使用 PC 扬声器辅助定位：内核初始化序列中会通过蜂鸣提示当前进度，可据此判断卡死位置；
• 若改用串口调试，请参考 BareMetalInstallation.md 中关于 cu/screen 连接串口（如 cu -s 57600 -l /dev/ttyUSB0）以及加入 dialout 用户组的说明；
• 若涉及根分区/引导设备找不到的问题，可查阅 Boot Device Addressing 了解 root= 引导参数的寻址规则；
• 更多通用排错信息见官方 故障排查文档。

总结

在 VMware 中运行 SerenityOS 的核心链路是：构建系统 → 生成 GRUB 磁盘镜像（ninja grub-image）→ qemu-img convert 转换为 VMDK → 按官方 11 步创建虚拟机（IDE 控制器 + ≥512 MiB 内存）→ 开机引导。相比 QEMU 与 VirtualBox，VMware 的差异化体验在于：必须使用 GRUB 镜像而非 QEMU 镜像，磁盘必须挂在 IDE 控制器上，且音频、网络在 VMware 下暂不可用。若遇到引导问题，优先从 Meta/grub-gpt.cfg 的四个菜单项与 graphics_subsystem_mode 内核参数入手，结合 Kernel/Boot/CommandLine.cpp 的实现理解其行为，即可快速定位并恢复启动。