环境变量

相关源文件

• Dockerfile
• Dockerfile.auto
• Dockerfile.naked
• Dockerfile.naked-auto
• README.md

此页面提供了 Docker-OSX 所有可用环境变量的全面参考。环境变量允许您在不修改底层代码的情况下自定义 macOS 虚拟机的行为、配置和功能。

有关序列号生成的信息，请参阅序列号生成。

概述

Docker-OSX 使用环境变量作为自定义容器行为的主要机制。这些变量控制从硬件分配（RAM、CPU）到网络配置、显示设置和系统身份参数的所有内容。

来源：Dockerfile284-334 Dockerfile.naked120-164 Dockerfile.auto152-206

硬件配置变量

这些变量控制分配给 macOS 虚拟机的硬件资源。

可变	默认	描述
内存	4	分配给虚拟机的 RAM GB 数。可以是数字、max（所有可用资源）或half（可用 RAM 的一半）。
CPU	Penryn	要模拟的 CPU 模型
CPUID_FLAGS	vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,...	传递给 QEMU 的 CPU 识别标志
SMP	4	CPU 插槽数量
CORES	4	每个 CPU 插槽的核心数
CPU_STRING	-	可选的自定义 CPU 拓扑字符串（覆盖 SMP/CORES）
KVM	accel=kvm:tcg	KVM 加速设置

示例

来源：Dockerfile185-217 README.md737-748

系统身份变量

这些变量控制虚拟机的身份，包括对 iMessage、iCloud 和其他 Apple 服务至关重要的序列号和硬件标识符。

可变	默认	描述
GENERATE_UNIQUE	false	生成一组随机的唯一机器标识符
GENERATE_SPECIFIC	false	使用变量中提供的特定机器标识符
DEVICE_MODEL	iMacPro1,1	Apple 设备型号标识符
SERIAL	-	设备序列号
BOARD_SERIAL	-	主板序列号
UUID	-	系统 UUID
MAC_ADDRESS	52:54:00:09:49:17	网络接口的 MAC 地址
MASTER_PLIST_URL	https://raw.githubusercontent.com/...	OpenCore 配置文件模板的 URL

示例

来源：Dockerfile242-250 Dockerfile376-399

网络变量

这些变量控制网络配置和端口转发。

可变	默认	描述
NETWORKING	vmxnet3	要模拟的网络适配器类型
INTERNAL_SSH_PORT	10022	容器使用的内部 SSH 端口
SCREEN_SHARE_PORT	5900	VNC/屏幕共享端口
ADDITIONAL_PORTS	-	其他端口转发（逗号分隔的 QEMU 语法）
MAC_ADDRESS	52:54:00:09:49:17	网络接口的 MAC 地址

示例

来源：Dockerfile212-214 Dockerfile.naked162-167 Dockerfile.auto198-203

显示和图形变量

这些变量控制显示配置和图形设置。

可变	默认	描述
DISPLAY	:0.0 或 :99	使用的 X11 显示
WIDTH	1920	屏幕宽度分辨率（以像素为单位）
HEIGHT	1080	屏幕高度分辨率（以像素为单位）
HEADLESS	false	在没有图形显示的情况下运行（在 naked/auto 镜像中）
AUDIO_DRIVER	alsa	使用的音频驱动程序

示例

来源：Dockerfile190-193 Dockerfile.naked162-167 Dockerfile.auto198-203

启动配置变量

这些变量控制启动过程和相关配置。

可变	默认	描述
BOOT_ARGS	-	其他 CPU 启动参数
BOOTDISK	-	自定义启动磁盘的路径
NOPICKER	false 或 true	跳过启动时的磁盘选择菜单（在 naked/auto 镜像中始终跳过）
EXTRA	-	额外的 QEMU 命令行参数
BASESYSTEM_FORMAT	qcow2	macOS 基础系统镜像的格式
SHORTNAME	sequoia	macOS 版本简称（high-sierra, mojave, catalina, big-sur, monterey, ventura, sonoma, sequoia）

示例

来源：Dockerfile371-376 Dockerfile399-400

存储和镜像变量

这些变量控制磁盘映像和存储相关的配置。

可变	默认	描述
IMAGE_PATH	/home/arch/OSX-KVM/mac_hdd_ng.img	macOS 磁盘镜像的路径
IMAGE_FORMAT	qcow2	磁盘镜像的格式
BASESYSTEM_IMAGE	BaseSystem.img	基础系统镜像文件的名称

示例

来源：Dockerfile312-313 Dockerfile359-363

自动化变量

这些变量支持自动化和自定义。

可变	默认	描述
USERNAME	user	自动登录的用户名（在 auto/naked-auto 镜像中）
PASSWORD	alpine	自动登录的密码（在 auto/naked-auto 镜像中）
OSX_COMMANDS	-	启动后要在 macOS 中运行的命令（在 auto/naked-auto 镜像中）
ENV	/env	用于存储序列信息的环境变量路径
TERMS_OF_USE	i_agree	同意使用条款（auto/naked-auto 镜像必需）

示例

来源：Dockerfile.auto187-191 Dockerfile.auto205-207 Dockerfile.auto257-284

环境变量继承

Docker-OSX 环境变量在不同的镜像变体之间遵循继承模式。

:latest 镜像定义了基础环境变量集。:naked、:auto 和 :naked-auto 变体继承这些变量，但可能具有针对其特定用例的不同的默认值或附加变量。

来源: Dockerfile284-334 Dockerfile.naked120-164 Dockerfile.auto152-206 Dockerfile.naked-auto128-177

常见用例和示例

基本配置

自定义 macOS 版本

iMessage/iCloud 兼容性

VNC 无头运行

使用自定义磁盘镜像

来源: README.md62-152 README.md211-231

环境变量处理流程

以下图表说明了容器启动过程中环境变量的处理方式。

来源: Dockerfile364-400 Dockerfile.naked177-217 Dockerfile.auto217-284

技巧与最佳实践

1. RAM 分配：为您的工作负载分配足够的 RAM

   • 基本用法: -e RAM=4
   • Xcode 开发: -e RAM=8 或更高
   • 最大性能: -e RAM=half 或 -e RAM=max

2. CPU 配置：根据主机能力调整 CPU 分配

   • 使用 -e EXTRA='-smp 6,sockets=3,cores=2' 进行精细控制

3. 序列号生成：用于 iCloud/iMessage 功能

   • 使用 -e GENERATE_UNIQUE=true 创建随机标识符
   • 使用 -e GENERATE_SPECIFIC=true 配合特定标识符以实现可复现的构建

4. OpenCore 配置：自定义引导加载程序行为

   • 使用 -e NOPICKER=true 跳过引导选择屏幕
   • 使用自定义 MASTER_PLIST_URL 进行专门配置

5. 镜像管理：磁盘镜像的最佳实践

   • 使用 qcow2 格式以实现高效存储
   • 在 naked 容器中使用 -v "${PWD}/disk.img:/image" 挂载现有镜像

来源: README.md737-748 README.md791-818