在 Apple Silicon Mac 上安装 Gentoo Linux（M1/M2）

本页导航

适用范围 本指南适用于在 Apple Silicon Mac（M1/M2 系列）上安装原生 ARM64 Gentoo Linux。 硬件兼容性 支持设备：M1 和 M2 系列 MacBook、Mac mini 等。 暂不支持：M3、M4 和 M5 系列芯片；请等待 Asahi Linux 项目更新。 Asahi Linux 项目团队，尤其是 chadmed，的工作促成了官方 Gentoo Asahi 安装指南。安装流程已大幅简化。 本文采用的流程：

基于 2025.10 的官方流程
使用官方 Gentoo Asahi Live USB，无需 Fedora 中转
区分必选和可选步骤
简化流程，包含加密选项已验证至 2025 年 11 月 20 日。 目标平台：Apple Silicon Mac（M1/M2 系列）ARM64 架构。初始设置使用 Asahi Linux 引导程序。之后切换到完整的 Gentoo 环境。

安装流程总览（简化版）
#

必选步骤：

下载官方 Gentoo Asahi Live USB 镜像
通过 Asahi 安装程序设置 U-Boot 环境
从 Live USB 启动
分区并挂载文件系统
展开 Stage3 并进入 chroot
安装 Asahi 支持软件包（自动化脚本）
重启完成安装 可选步骤：

LUKS 加密（建议但非必须）
自定义内核配置（默认 dist-kernel 即可）
音频设置（按需配置 PipeWire）
桌面环境选择

整个流程会在 Mac 上建立 macOS 和 Gentoo Linux ARM64 的双启动环境。自动化脚本 asahi-gentoosupport 自动化脚本可完成大部分配置。
#

事前准备与注意事项
#

硬件需求
#

Apple Silicon Mac（仅 M1/M2 系列芯片，M3/M4/M5 暂不支持）
至少 80 GB 可用磁盘空间（建议 120 GB 以上）
稳定的网络连接（Wi-Fi 或以太网）
备份重要数据

重要警告
#

安装过程包含进阶操作：

会调整分区表
需要与 macOS 共存
涉及磁盘加密操作
Apple Silicon 对 Linux 的支持仍在开发中 已知可用功能：
CPU、内存和存储设备
Wi-Fi（通过 Asahi Linux 固件）
键盘、触控板和电池管理
显示输出（内置屏幕和外接显示器）
USB-C / Thunderbolt 已知限制：
Touch ID 无法使用
macOS 虚拟化功能受限
部分新硬件功能可能未完全支持
M1/M2 的 GPU 支持状态为 linux-asahi，表示支持大致稳定；个别功能限制请参阅 Asahi 的 M1 和 M2 功能支持矩阵。

补充说明： 本指南假定读者具备基本的 Linux 知识。遇到问题时，请查阅官方 Gentoo Asahi Wiki。

0. 准备 Gentoo Asahi Live USB
#

运行安装程序前，macOS 必须为 13.5 或更高版本。若当前版本较低，先升级 macOS。

0.1 下载官方 Gentoo Asahi Live USB
#

官方流程：直接使用 Gentoo 提供的 ARM64 Live USB，无需通过 Fedora。下载最新版本：

curl -fLO https://chadmed.au/pub/gentoo/install-arm64-asahi-latest.iso

提示：官方正在将 Asahi 支持整合到标准 Live USB。当前使用 chadmed 维护的版本。

0.2 制作启动 USB
#

在 macOS 中运行：

# 查看 USB 设备名
diskutil list
# 卸载 USB（假设为 /dev/disk4）
diskutil unmountDisk /dev/disk4
# 写入镜像（使用 rdisk 较快）
sudo dd if=install-arm64-asahi-latest.iso of=/dev/rdisk4 bs=4m status=progress
# 写入完成后弹出 USB
diskutil eject /dev/disk4

1. 设置 Asahi U-Boot 环境
#

1.1 执行 Asahi 安装程序
#

在 macOS 终端中运行：该命令要求 macOS 13.5 或更高版本；请先满足第 0 节的前置条件。

curl https://alx.sh | sh

安全提示 先前往 https://alx.sh 查看脚本内容。确认安全后再运行。

1.2 跟随安装程序步骤
#

在安装程序中：

选择操作：输入 r (Resize an existing partition to make space for a new OS)
选择分区空间：为 Linux 分配至少 80 GB 的空间
- 可使用百分比（如 50%）或绝对大小（如 120GB）

提示：保留 macOS 分区，以便更新固件。

选择操作系统：选择 UEFI environment only (m1n1 + U-Boot + ESP)
```
» OS: <选择 UEFI only 选项>
```

官方建议：选择 UEFI only，无需安装完整发行版。 4. 设置名称：输入 Gentoo 作为操作系统名称

» OS name: Gentoo

完成安装：记下屏幕提示，然后按 Enter 关机。

1.3 完成 Recovery 模式设置（关键步骤）
#

重启步骤：

等待 25 秒，确保系统完全关机
按住电源键，直到看到“Loading startup options...”或旋转图标
释放电源键
等待音量列表出现，然后选择 Gentoo
会显示 macOS Recovery 界面：
- 若要求“Select a volume to recover”，选择 macOS 音量并点击 Next
- 输入 macOS 用户密码（FileVault 用户）
按屏幕提示完成设置 故障排除 若启动循环或提示重新安装 macOS，按住电源键使系统完全关机，然后从步骤 1 重新开始。也可以启动 macOS，运行 curl https://alx.sh | sh 并选择 p 选项重试。

2. 从 Live USB 启动
#

2.1 连接 Live USB 并启动
#

插入 Live USB（可通过 USB Hub 或 Dock）
启动 Mac
U-Boot 自动启动：
- 选择“UEFI environment only”后，U-Boot 会自动从 USB 启动 GRUB
- 等待 2 秒，自动启动序列开始
- 若有多个系统，可能需要中断并手动选择

提示：若需手动指定 USB 启动，在 U-Boot 提示符下运行：

setenv boot_targets "usb"
setenv bootmeths "efi"
boot

2.2 设置网络（Live 环境）
#

Gentoo Live USB 内置网络工具： 连接 Wi-Fi：

net-setup

按交互提示配置网络。完成后检查：

ping -c 3 www.gentoo.org

提示：Apple Silicon 的 Wi-Fi 已包含在内核中。若网络不稳定，尝试连接 2.4 GHz 网络。 （可选）通过 SSH 远程操作：

passwd                     
# 设置 root 密码
/etc/init.d/sshd start
ip a | grep inet          
# 获取 IP 地址

3. 分区与文件系统设置
#

3.1 识别磁盘与分区
#

重要警告 不要修改现有的 APFS 容器、EFI 分区或 Recovery 分区！ 只能操作 Asahi 安装程序预留的空间。查看分区结构：

lsblk
blkid --label "EFI - GENTO"  
# 显示 EFI 分区

通常会看到：

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0         7:0    0 609.1M  1 loop /run/rootfsbase
sda           8:0    1 119.5G  0 disk /run/initramfs/live
|-sda1        8:1    1   118K  0 part 
|-sda2        8:2    1   2.8M  0 part 
`-sda3        8:3    1 670.4M  0 part 
nvme0n1     259:0    0 465.9G  0 disk 
|-nvme0n1p1 259:1    0   500M  0 part 
|-nvme0n1p2 259:2    0 307.3G  0 part 
|-nvme0n1p3 259:3    0   2.3G  0 part 
|-nvme0n1p4 259:4    0   477M  0 part 
`-nvme0n1p5 259:5    0     5G  0 part 
nvme0n2     259:6    0     3M  0 disk 
nvme0n3     259:7    0   128M  0 disk 

EFI 分区识别（不要动这个分区！）：

livecd ~ 
# blkid --label "EFI - GENTO" 
/dev/nvme0n1p4  
# 不要修改 EFI 分区

建议 cfdisk 能识别 Apple 分区类型，并会保护系统分区。

3.2 建立根分区
#

假设空白空间从 /dev/nvme0n1p5 开始： 方法 A：简单分区（无加密）

# 使用 cfdisk 建立新分区
cfdisk /dev/nvme0n1

你会看到类似以下的分区表：

                                            Disk: /dev/nvme0n1
                         Size: 465.92 GiB, 500277792768 bytes, 122138133 sectors
                       Label: gpt, identifier: 6C5A96F2-EFC9-487C-8C3E-01FD5EA77896
    Device                      Start            End       Sectors        Size Type
    /dev/nvme0n1p1                  6         128005        128000        500M Apple Silicon boot
    /dev/nvme0n1p2             128006       80694533      80566528      307.3G Apple APFS
    /dev/nvme0n1p3           80694534       81304837        610304        2.3G Apple APFS
    /dev/nvme0n1p4           81304838       81426949        122112        477M EFI System
>>  Free space               81427200      120827418      39400219      150.3G                            
    /dev/nvme0n1p5          120827419      122138127       1310709          5G Apple Silicon recovery
                        [   New  ]  [  Quit  ]  [  Help  ]  [  Write ]  [  Dump  ]
                                   Create new partition from free space

操作步骤：

选择 Free space → New
使用全部空间（或自定义大小）
Type → 选择 Linux filesystem
Write → 输入 yes 确认
Quit 离开 格式化分区：

# 格式化为 ext4 或 btrfs
mkfs.ext4 /dev/nvme0n1p6
# 或
mkfs.btrfs /dev/nvme0n1p6
# 挂载
mount /dev/nvme0n1p6 /mnt/gentoo

方法 B：加密分区（可选，建议）

# 创建 LUKS2 加密分区
cryptsetup luksFormat --type luks2 --pbkdf argon2id --hash sha512 --key-size 512 /dev/nvme0n1p6
# 输入 YES 确认，设置加密密码
# 打开加密分区
cryptsetup luksOpen /dev/nvme0n1p6 gentoo-root
# 格式化
mkfs.btrfs --label root /dev/mapper/gentoo-root
# 挂载
mount /dev/mapper/gentoo-root /mnt/gentoo

参数说明

argon2id：抵抗 ASIC/GPU 暴力破解
aes-xts：M1 的 AES 指令集提供硬件加速
luks2：使用 LUKS2 格式

3.3 挂载 EFI 分区
#

mkdir -p /mnt/gentoo/boot
mount /dev/nvme0n1p4 /mnt/gentoo/boot

4. Stage3 与 chroot
#

从此处起，遵循 AMD64 Handbook，直到“Installing the kernel”章节；Asahi 支持软件包步骤将取代该核心章节。

4.1 下载并展开 Stage3
#

cd /mnt/gentoo
chronyd -q
date
# 通过官方 latest-stage3 txt 文件自动获取当前路径；wget 不支持远程通配符，必须采用此方式
STAGE3=$(wget -qO- https://distfiles.gentoo.org/releases/arm64/autobuilds/latest-stage3-arm64-desktop-systemd.txt | grep -m1 -E '^[0-9]{8}T[0-9]{6}Z/stage3-arm64-desktop-systemd-[0-9]{8}T[0-9]{6}Z\.tar\.xz ' | cut -d' ' -f1)
wget "https://distfiles.gentoo.org/releases/arm64/autobuilds/${STAGE3}"
wget "https://distfiles.gentoo.org/releases/arm64/autobuilds/${STAGE3}.asc"
# 验证签名
gpg --verify stage3-*.tar.xz.asc stage3-*.tar.xz
# 解压并保留属性
tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner

4.2 设置 Portage
#

mkdir --parents /mnt/gentoo/etc/portage/repos.conf
cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

4.3 同步系统时间
#

进入 chroot 前，确认系统时间正确，避免出现编译或 SSL 证书问题：原因

编译软件包需要正确的时间戳
SSL/TLS 证书验证依赖准确的系统时间
时间不正确可能导致 emerge 失败或证书错误

4.4 进入 chroot 环境
#

挂载必要的文件系统：

cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
mount --types proc /proc /mnt/gentoo/proc
mount --rbind /sys /mnt/gentoo/sys
mount --make-rslave /mnt/gentoo/sys
mount --rbind /dev /mnt/gentoo/dev
mount --make-rslave /mnt/gentoo/dev
mount --bind /run /mnt/gentoo/run
mount --make-slave /mnt/gentoo/run

进入 chroot 环境：

chroot /mnt/gentoo /bin/bash
source /etc/profile
export PS1="(chroot) ${PS1}"

4.5 基本系统配置
#

设置 make.conf（针对 Apple Silicon 优化）：编辑 /etc/portage/make.conf：

nano -w /etc/portage/make.conf

添加或修改以下内容：

# vim: set language=bash;
CHOST="aarch64-unknown-linux-gnu"
# Apple Silicon 优化编译参数
COMMON_FLAGS="-march=armv8.5-a+fp16+simd+crypto -mtune=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"
RUSTFLAGS="-C target-cpu=native"
# 保持构建输出为英文（报告错误时保留此设置）
LC_MESSAGES=C
# 按硬件调整（例如 M2 Max 的核心数较多）
MAKEOPTS="-j4"
# Gentoo 镜像（推荐使用 R2 镜像，速度较快）
GENTOO_MIRRORS="https://gentoo.rgst.io/gentoo"
# Emerge 默认选项（最多同时编译 3 个软件包）
EMERGE_DEFAULT_OPTS="--jobs 3"
# Asahi GPU 驱动
VIDEO_CARDS="asahi"
# 中文本地化支持（可选）
L10N="zh-CN zh-TW zh en"
# 文件末尾保留换行符

同步 Portage：

emerge-webrsync

设置时区：

# 设置为台湾时区（或改为你所在的时区）
ln -sf /usr/share/zoneinfo/Asia/Taipei /etc/localtime

设置区域设置：

# 编辑 locale.gen，取消所需 locale 的注释
nano -w /etc/locale.gen
# 取消 en_US.UTF-8 UTF-8 的注释
# 如需中文，取消 zh_CN.UTF-8 UTF-8 的注释
# 生成 locale
locale-gen
# 选择系统默认 locale
eselect locale set en_US.utf8
# 重新加载环境
env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

创建用户并设置密码：

# 创建用户（将 <用户名称> 替换为用户名）
useradd -m -G wheel,audio,video,usb,input <用户名称>
# 设置用户密码
passwd <用户名称>
# 设置 root 密码
passwd root

5. 安装 Asahi 支持软件包（核心步骤）
#

官方简化流程 本节取代 Handbook 中的“安装内核”章节。

5.1 方法 A：自动化安装（推荐）
#

步骤 1：安装 git

# 首次同步 Portage 仓库
emerge --sync
# 安装 git（下载脚本所需）
emerge --ask dev-vcs/git

步骤 2：使用 asahi-gentoosupport 脚本（官方提供）：

cd /tmp
git clone https://github.com/chadmed/asahi-gentoosupport
cd asahi-gentoosupport
./install.sh

该脚本会自动完成：

启用 Asahi overlay
安装 GRUB bootloader
设置 VIDEO_CARDS="asahi"
安装 asahi-meta（包含内核、固件、m1n1、U-Boot）
运行 asahi-fwupdate 和 update-m1n1

USE flag 冲突 脚本运行期间可能会提示变更 USE flag。处理方法：

# 脚本提示 USE flag 冲突时，按 Ctrl+C 中断脚本
# 然后运行：
emerge --autounmask-write <出现冲突的软件包>
# 更新配置文件
etc-update
# 在 etc-update 中选择适当选项，通常为 -3 自动合并
# 重新运行安装脚本
cd /tmp/asahi-gentoosupport
./install.sh

脚本完成后，执行：

emerge --ask --update --deep --changed-use @world

完成后，进入步骤 5.3 配置 fstab。
#

5.2 方法 B：手动安装（进阶用户）
#

步骤 1：安装 git 并配置 Asahi overlay

# 首次同步 Portage 仓库
emerge --sync
# 安装 git（用于 Git 同步）
emerge --ask dev-vcs/git
# 删除旧 Portage 数据库并切换至 Git 同步
rm -rf /var/db/repos/gentoo
tee /etc/portage/repos.conf/gentoo.conf << 'EOF'
[DEFAULT]
main-repo = gentoo
[gentoo]
location = /var/db/repos/gentoo
sync-type = git
sync-uri = https://mirrors.bfsu.edu.cn/git/gentoo-portage.git
auto-sync = yes
sync-depth = 1
EOF
# 使用 Git 同步配置 Asahi overlay
tee /etc/portage/repos.conf/asahi.conf << 'EOF'
[asahi]
location = /var/db/repos/asahi
sync-type = git
sync-uri = https://github.com/chadmed/asahi-overlay.git
auto-sync = yes
EOF
# 同步所有仓库
emerge --sync

镜像源说明 简体中文用户：可将上面的 sync-uri 改为北外源 https://mirrors.bfsu.edu.cn/git/gentoo-portage.git 以加快同步。更多镜像源选项参考：镜像列表 步骤 2：配置 package.mask 防止 Gentoo 官方 dist-kernel 覆盖 Asahi 版本：

mkdir -p /etc/portage/package.mask
cat > /etc/portage/package.mask/asahi << 'EOF'
# 屏蔽上游 dist-kernel virtual，避免其强制内核升级
virtual/dist-kernel::gentoo
EOF

步骤 3：配置 package.use

mkdir -p /etc/portage/package.use
# Asahi 专用 USE flag
cat > /etc/portage/package.use/asahi << 'EOF'
dev-lang/rust-bin rustfmt rust-src
dev-lang/rust rustfmt rust-src
EOF
# 设置 VIDEO_CARDS
echo 'VIDEO_CARDS="asahi"' >> /etc/portage/make.conf
# 必须设置 GRUB 平台
echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf

步骤 4：配置固件许可证

mkdir -p /etc/portage/package.license
echo 'sys-kernel/linux-firmware linux-fw-redistributable no-source-code' > /etc/portage/package.license/firmware

步骤 5：安装 rust-bin（必须先安装）

emerge -q1 dev-lang/rust-bin

步骤 6：安装 Asahi 软件包

# 一次安装所有必需软件包
emerge -q sys-apps/asahi-meta virtual/dist-kernel:asahi sys-kernel/linux-firmware

提示：如果 etc-update 出现配置文件冲突，选择 -3 自动合并。软件包说明：

rust-bin：编译 Asahi 内核组件所需，必须先安装
asahi-meta：包含 m1n1、asahi-fwupdate、U-Boot 等工具
virtual/dist-kernel:asahi：包含未上游补丁的 Asahi 内核
linux-firmware：提供 Wi-Fi 等硬件固件

步骤 7：更新固件与引导程序

asahi-fwupdate
update-m1n1

后续更新 更新内核、U-Boot 或 m1n1 后，必须运行 update-m1n1。 步骤 8：安装并配置 GRUB

# 安装 GRUB
emerge -q grub:2
# 将 GRUB 安装到 ESP（必须使用 --removable 标志）
grub-install --boot-directory=/boot/ --efi-directory=/boot/ --removable
# 生成 GRUB 配置
grub-mkconfig -o /boot/grub/grub.cfg

关键配置

--removable 标志是必须的，确保系统能从 ESP 启动
--boot-directory 和 --efi-directory 都必须指向 /boot/
必须在 make.conf 中设置 GRUB_PLATFORMS="efi-64" 步骤 9：更新系统（可选）

emerge --ask --update --deep --changed-use @world

5.3 配置 fstab
#

获取 UUID：

# 未加密安装（ext4 或 btrfs）的根分区
blkid /dev/nvme0n1p6
# 加密安装的解密后根文件系统
blkid /dev/mapper/gentoo-root
# boot 分区
blkid --label "EFI - GENTO"

编辑 /etc/fstab：

nano -w /etc/fstab

# 根分区（依你的配置调整）
UUID=<your-root-uuid>  /      ext4   defaults  0 1
# 或加密版本：
# UUID=<your-btrfs-uuid>  /      btrfs  defaults  0 1
UUID=<your-boot-uuid>  /boot  vfat   defaults  0 2

5.4 配置加密支持（仅限加密安装）
#

适用条件 仅在步骤 3.2 中配置了加密分区时，才运行本节命令。 步骤 1：启用 systemd cryptsetup 支持

mkdir -p /etc/portage/package.use
echo "sys-apps/systemd cryptsetup" >> /etc/portage/package.use/fde
# 重新编译 systemd，启用 cryptsetup 支持
emerge --ask --oneshot sys-apps/systemd

步骤 2：获取 LUKS 分区 UUID

# 获取 LUKS 加密容器的 UUID，而非其中的文件系统 UUID
blkid /dev/nvme0n1p6

示例输出：

/dev/nvme0n1p6: UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" TYPE="crypto_LUKS" ...

记下 LUKS UUID，例如 a1b2c3d4-e5f6-7890-abcd-ef1234567890。 步骤 3：配置 GRUB 内核参数

nano -w /etc/default/grub

添加或修改以下内容：将 <LUKS-UUID> 替换为 blkid /dev/nvme0n1p6 显示的 UUID，将 <decrypted-fs-UUID> 替换为 blkid /dev/mapper/gentoo-root 显示的 UUID。

# 完整示例：将两个 UUID 占位符替换为实际值
GRUB_CMDLINE_LINUX="rd.luks.uuid=<LUKS-UUID> rd.luks.allow-discards root=UUID=<decrypted-fs-UUID> rootfstype=btrfs"

参数说明

rd.luks.uuid=<LUKS-UUID>：LUKS 加密分区 UUID，通过 blkid /dev/nvme0n1p6 获取
rd.luks.allow-discards：允许 SSD TRIM 命令传递至加密层，提高 SSD 性能
root=UUID=<decrypted-fs-UUID>：解密后的 btrfs 文件系统 UUID，通过 blkid /dev/mapper/gentoo-root 获取
rootfstype=btrfs：根文件系统类型；使用 ext4 时改为 ext4

步骤 4：安装并配置 dracut

# 安装 dracut（尚未安装时）
emerge --ask sys-kernel/dracut

步骤 5：配置 dracut 以解锁 LUKS 创建 dracut 配置文件：

nano -w /etc/dracut.conf.d/luks.conf

添加以下内容：

# 不要在此设置 kernel_cmdline，GRUB 会覆盖它
kernel_cmdline=""
# 添加支持 LUKS 和 btrfs 所需的模块
add_dracutmodules+=" btrfs systemd crypt dm "
# 添加所需工具
install_items+=" /sbin/cryptsetup /bin/grep "
# 指定文件系统；使用其他文件系统时修改
filesystems+=" btrfs "

配置说明

crypt 和 dm 模块提供 LUKS 解密支持
systemd 模块用于 systemd 启动环境
btrfs 模块支持 btrfs 文件系统；使用 ext4 时改为 ext4 步骤 6：配置 /etc/crypttab（可选，建议）

nano -w /etc/crypttab

添加以下内容，并将 UUID 替换为 LUKS UUID：

gentoo-root UUID=<LUKS-UUID> none luks,discard

提示：配置后，系统会自动识别并提示解锁加密分区。 步骤 7：重新生成 initramfs

# 获取当前内核版本
dracut --kver $(make -C /usr/src/linux -s kernelrelease) --force

更新内核后 每次更新内核后，都需要重新运行此命令生成 initramfs。 步骤 8：更新 GRUB 配置

grub-mkconfig -o /boot/grub/grub.cfg
# 确认 initramfs 被正确引用
grep initrd /boot/grub/grub.cfg

6. 完成安装与重启
#

6.1 最后设置
#

设置主机名：

echo "macbook" > /etc/hostname

启用 NetworkManager（桌面系统）：

emerge --ask net-misc/networkmanager
systemctl enable NetworkManager

设置 root 密码（尚未设置时）：

passwd root

6.2 离开 chroot 并重启
#

exit
umount -R /mnt/gentoo
# 使用加密时：
cryptsetup luksClose gentoo-root
reboot

6.3 首次启动
#

U-Boot 会自动启动
GRUB 菜单出现后，选择 Gentoo
使用加密时，输入 LUKS 密码
系统应进入登录提示 基本系统安装完成。

7. 安装后配置（可选）
#

7.1 网络连接
#

# Wi-Fi
nmcli device wifi connect <SSID> password <密码>
# 或使用 nmtui
nmtui

7.2 安装桌面环境（可选）
#

提示安装桌面环境前，切换至对应的系统 profile。该操作会自动设置许多必要的 USE flag。

步骤 1：查看并选择系统 profile
#

# 列出所有可用 profile
eselect profile list

在当前输出中找出目标 profile 的完整名称，并记下其前面的编号。profile 编号会随 Portage 树变化。

选择合适的 profile：

# GNOME 桌面：选择名称以 desktop/gnome/systemd 结尾的条目
eselect profile set <profile-number>
# KDE Plasma 桌面（推荐）：选择名称以 desktop/plasma/systemd 结尾的条目
eselect profile set <profile-number>
# 通用桌面环境（Xfce 等）：选择名称以 desktop/systemd 结尾的条目
eselect profile set <profile-number>

Profile 说明

desktop/gnome/systemd：自动启用 GNOME 相关 USE flag（gtk、gnome、wayland 等）
desktop/plasma/systemd：自动启用 KDE 相关 USE flag（qt6、kde、plasma 等）
desktop/systemd：基础桌面 USE flag（X、dbus、networkmanager 等）

步骤 2：更新系统以应用新 profile
#

切换 profile 后，重新编译受影响的软件包：

# 更新所有软件包以应用新的 USE flag
emerge -avuDN @world

步骤 3：安装桌面环境
#

选项 A：KDE Plasma（推荐）

# 安装 KDE Plasma 桌面
emerge --ask kde-plasma/plasma-meta kde-apps/kate kde-apps/dolphin
# 启用显示管理器
systemctl enable sddm
# 安装常用应用（可选）
emerge --ask kde-apps/konsole \
             kde-apps/okular \
             www-client/firefox

选项 B：GNOME

# 安装完整 GNOME 桌面
emerge --ask gnome-base/gnome gnome-extra/gnome-tweaks
# 启用显示管理器
systemctl enable gdm
# 安装常用应用（可选）
emerge --ask gnome-extra/gnome-system-monitor \
             gnome-extra/gnome-calculator \
             www-client/firefox

选项 C：Xfce（轻量级）

# 切换至名称以 desktop/systemd 结尾的通用桌面 profile
eselect profile set <profile-number>
# desktop/systemd
# 更新系统
emerge -avuDN @world
# 安装 Xfce
emerge --ask xfce-base/xfce4-meta xfce-extra/xfce4-pulseaudio-plugin
# 安装并启用显示管理器
emerge --ask x11-misc/lightdm
systemctl enable lightdm

步骤 4：优化桌面性能（可选）
#

启用视频加速（Asahi GPU）：

# 检查 VIDEO_CARDS 设置
grep VIDEO_CARDS /etc/portage/make.conf
# 应包含：VIDEO_CARDS="asahi"
# 安装 Mesa 和 Asahi 驱动（通常已安装）
emerge --ask media-libs/mesa

启用字体渲染：

# 安装基础字体
emerge --ask media-fonts/liberation-fonts \
             media-fonts/noto \
             media-fonts/noto-cjk \
             media-fonts/dejavu
# 启用字体微调
eselect fontconfig enable 10-sub-pixel-rgb.conf
eselect fontconfig enable 11-lcdfilter-default.conf

配置中文输入法：

# 安装 Fcitx5 中文输入法
emerge --ask app-i18n/fcitx-chinese-addons

注意当前版本中，app-i18n/fcitx-rime 实测无法正常使用。建议以 app-i18n/fcitx-chinese-addons 替代。

首次安装桌面环境预计需要 2–4 小时，取决于 CPU 性能
建议使用 --jobs 3 或更少，避免内存不足
可在 /etc/portage/make.conf 设置 EMERGE_DEFAULT_OPTS="--jobs 3 --load-average 8"

7.3 音频配置（可选）
#

Asahi 音频由 PipeWire 提供。以 root 身份安装软件包：

# 安装 Asahi 音频支持
emerge --ask media-libs/asahi-audio

重启后，以创建的桌面用户登录桌面会话。在该会话中运行：

# 启用 PipeWire 服务
systemctl --user enable --now pipewire-pulse.service
systemctl --user enable --now wireplumber.service

8. 系统维护
#

8.1 定期更新流程
#

# 更新 Portage 树（包含 Asahi overlay）
emerge --sync
# 或手动同步 Asahi overlay：
emaint -r asahi sync
# 更新所有软件包
emerge -avuDN @world
# 清理不需要的软件包
emerge --depclean
# 更新配置文件
dispatch-conf

8.2 更新内核后必做
#

内核更新后 每次更新内核后，都必须运行：

# 更新 m1n1 Stage 2（包含 devicetree）
update-m1n1
# 重新生成 GRUB 配置
grub-mkconfig -o /boot/grub/grub.cfg

原因：m1n1 Stage 2 包含 devicetree blob，内核通过它识别硬件。未更新时，系统可能无法启动或缺少功能。 自动化 sys-apps/asahi-scripts 提供 installkernel hook，自动运行这些步骤。

8.3 更新固件
#

macOS 系统更新包含固件更新。建议保留 macOS 分区，以便获取最新固件。
#

9. 常见问题与故障排除
#

无法从 USB 启动
#

可能原因：U-Boot 的 USB 驱动仍有限制。 解决方法：

尝试不同的 USB 闪存盘
使用 USB 2.0 设备，兼容性较好
通过 USB Hub 连接

启动停滞或黑屏
#

原因：m1n1、U-Boot 和内核不匹配。 解决方法：

在 macOS 中重新运行 Asahi 安装程序
选择 p 选项重试 Recovery 流程
确认在 chroot 中运行了 update-m1n1

加密分区无法解锁
#

原因：dracut 配置错误或 UUID 不正确。 解决方法：

检查 /etc/default/grub 中的 GRUB_CMDLINE_LINUX
确认 LUKS UUID 正确：blkid /dev/nvme0n1p6
重新生成 GRUB 配置：grub-mkconfig -o /boot/grub/grub.cfg

Wi-Fi 不稳定
#

原因：可能是 WPA3 或 6 GHz 频段问题。 解决方法：

连接 WPA2 网络
使用 2.4 GHz 或 5 GHz 频段，避免 6 GHz

触控板无法使用
#

原因：固件未加载或驱动问题。 解决方法：

# 检查固件
dmesg | grep -i firmware
# 确认已安装 asahi-meta
emerge --ask sys-apps/asahi-meta

10. 进阶技巧（可选）
#

10.1 刘海（Notch）配置
#

默认情况下，刘海区域显示为黑色。根据所用内核版本，在 GRUB 内核参数中添加对应参数：

# 内核 6.17 及更早版本
apple_dcp.show_notch=1
# 内核 6.18 及更高版本
appledrm.show_notch=1

KDE Plasma 优化：

在顶部新增全宽面板，高度对齐刘海底部
左侧：Application Dashboard、Global menu、Spacer
右侧：System Tray、Bluetooth、Power、时钟

10.2 自定义内核（进阶）
#

默认的 Distribution kernel 即可。需要自定义时：

emerge --ask sys-kernel/asahi-sources
cd /usr/src/linux
make menuconfig
make -j$(nproc)
make modules_install
make install
update-m1n1  
# 必须运行
grub-mkconfig -o /boot/grub/grub.cfg

保留可用内核作为备用。

10.3 多内核切换
#

可以并存多个内核：

eselect kernel list
eselect kernel set <number>
update-m1n1  
# 切换后必须运行

11. 参考资料
#

官方文档
#

Gentoo Wiki: Project:Asahi/Guide：官方指南
Asahi Linux Official Site
Asahi Linux Feature Support
Gentoo AMD64 Handbook（流程相同）

工具与脚本
#

asahi-gentoosupport：自动化安装脚本
Gentoo Asahi Releng：Live USB 构建工具

社区支持
#

Gentoo 中文社区：

Telegram 群组：@gentoo_zh
Telegram 频道：@gentoocn
GitHub 官方社区：
Gentoo Forums
IRC：#gentoo 和 #asahi @ Libera.Chat
Asahi Linux Discord

结语
#

依据
#

本指南基于官方 Project:Asahi/Guide。 三个关键点：

使用官方 Gentoo Asahi Live USB，无需 Fedora 中转。
asahi-gentoosupport 脚本可自动完成大部分配置。
每次内核更新后，都必须运行 update-m1n1。

安装流程总览（简化版）#

整个流程会在 Mac 上建立 macOS 和 Gentoo Linux ARM64 的双启动环境。 自动化脚本 asahi-gentoosupport 自动化脚本 可完成大部分配置。#

事前准备与注意事项#

硬件需求#

重要警告#

0. 准备 Gentoo Asahi Live USB#

0.1 下载官方 Gentoo Asahi Live USB#

0.2 制作启动 USB#

1. 设置 Asahi U-Boot 环境#

1.1 执行 Asahi 安装程序#

1.2 跟随安装程序步骤#

1.3 完成 Recovery 模式设置（关键步骤）#

2. 从 Live USB 启动#

2.1 连接 Live USB 并启动#

2.2 设置网络（Live 环境）#

3. 分区与文件系统设置#

3.1 识别磁盘与分区#

3.2 建立根分区#

3.3 挂载 EFI 分区#

4. Stage3 与 chroot#

4.1 下载并展开 Stage3#

4.2 设置 Portage#

4.3 同步系统时间#

4.4 进入 chroot 环境#

4.5 基本系统配置#

5. 安装 Asahi 支持软件包（核心步骤）#

5.1 方法 A：自动化安装（推荐）#

完成后，进入步骤 5.3 配置 fstab。#

5.2 方法 B：手动安装（进阶用户）#

5.3 配置 fstab#

5.4 配置加密支持（仅限加密安装）#

6. 完成安装与重启#

6.1 最后设置#

6.2 离开 chroot 并重启#

6.3 首次启动#

7. 安装后配置（可选）#

7.1 网络连接#

7.2 安装桌面环境（可选）#

步骤 1：查看并选择系统 profile#

步骤 2：更新系统以应用新 profile#

步骤 3：安装桌面环境#

步骤 4：优化桌面性能（可选）#

7.3 音频配置（可选）#

8. 系统维护#

8.1 定期更新流程#

8.2 更新内核后必做#

8.3 更新固件#

macOS 系统更新包含固件更新。建议保留 macOS 分区，以便获取最新固件。#

9. 常见问题与故障排除#

无法从 USB 启动#

启动停滞或黑屏#

加密分区无法解锁#

Wi-Fi 不稳定#

触控板无法使用#

10. 进阶技巧（可选）#

10.1 刘海（Notch）配置#

10.2 自定义内核（进阶）#

10.3 多内核切换#

11. 参考资料#

官方文档#

工具与脚本#

社区支持#

延伸阅读#

结语#

依据#

延伸阅读