在 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 文字檔自動取得目前路徑；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：

# 編輯 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. 參考資料#

官方文件#

工具與腳本#

社群支援#

延伸閱讀#

結語#

依據#

延伸閱讀