把手動環境做成「可控的手動」

可控的手動指的是一種中間狀態：資源還是手點的，但關鍵變更有痕跡、高風險操作有護欄、現實長什麼樣有紀錄。它的責任是降低兩種成本 — 當下出事的成本，以及未來把資源 import 進 IaC 的成本。手動起家是絕大多數服務的常態起點，從一個人驗證想法到小團隊接手都會經過這一階，把它當成需要管理的階段、而不是需要修正的錯誤。

判讀自己是否「可控」的訊號很具體：能不能在五分鐘內說出 production 有哪些對外開放的 port、上週誰動過資料庫參數、刪掉某台機器會不會連帶弄壞別的東西。任何一題答不出來，代表這個手動環境的不可見區域正在擴大，下面幾節就是把這些區域逐一收斂。

先守住代價最高的底線

護欄要先上在「一次失誤就難以挽回」的操作上，因為手動環境沒有 IaC 的 plan / diff 當預檢，人為操作直接生效。優先級看的是失誤的回退代價、不是操作頻率。

長期憑證外洩是回退代價最高的一類。手動環境常見的反模式是把長期 access key 寫進腳本、CI 變數或開發者筆電，一旦外流，攻擊者拿到的是不會過期的權限。在還沒有完整 IAM 設計之前，最低成本的護欄是：對人改用會過期的登入工作階段（如 AWS IAM Identity Center 的臨時憑證），對自動化盡量改用平台原生的角色綁定，把還在用的長期 key 列一張清單、設定定期輪替。身分與憑證的完整地基在「模組二：身分與憑證地基」展開，這裡先擋住最容易致命的那一個。

刪除 production 資源是第二類。手動操作沒有「先看會影響什麼」的步驟，刪一個 security group 或 volume 可能瞬間讓服務失聯。對承載狀態的資源（資料庫、儲存桶、有持久資料的磁碟）開啟平台的刪除保護（如 termination protection、deletion protection），讓誤點多一道阻力。網路規則的大改是第三類 — 調整 VPC 路由、subnet 或對外規則時，先確認回退方式存在再動手，網路地基的系統性設計在「模組三：網路地基」。

這三類的共同點是：護欄成本低、失誤代價高，所以即使還沒有 IaC，CP 值也足以先做。

讓變更留下痕跡

變更留痕的責任是讓「誰、在什麼時候、改了什麼、為什麼」事後可追溯，這是手動階段最接近版本控制的替代品。IaC 的 git history 天然提供這件事，手動環境得靠人為紀律補上。

最低限度是一份變更日誌，可以只是 repo 裡的一個 CHANGELOG 或團隊共用文件，每次動 production 就追加一行：時間、操作者、改了哪個資源、原因。它不需要漂亮，需要的是每次都寫。和它互補的是平台的稽核日誌（如 AWS CloudTrail），稽核日誌記錄 API 層級「發生了什麼」，人寫的日誌補上「為什麼」— 前者你查得到某個 security group 在幾點被改，後者你才知道那次改動是為了什麼需求。兩者一起，事故排查時才能從「哪裡變了」一路追到「能不能安全回退」。

常見陷阱是只在「大改動」時才記錄，結果真正出事的往往是某次以為無關緊要的小調整。判準簡化成一句：只要這個操作別人事後可能需要知道，就記。

命名與 tagging 從手動階段就開始

命名規範與資源標籤是降低未來 import 成本的最低成本投資，它的責任是讓每個資源自帶「我是誰、屬於哪個服務、誰負責、哪個環境」的身分資訊。手動點出來的資源若名稱是 test-2、new-db-final，日後納管時得靠人逐一辨認哪個還在用、屬於哪條業務線，這個考古成本遠高於當初多打幾個字。

從手動階段就固定一套規則：資源名稱帶上服務與環境（如 payments-api-prod），標籤至少包含 service、env、owner 三個維度。這套規則在還沒 IaC 時靠人手動填，等到導入 IaC，這些標籤直接成為 Terraform 把現有資源對應到程式碼的依據，也是模組八治理習慣裡成本歸因與批次操作的基礎（見「模組八：治理好習慣」的 tagging 段）。先建立規範的價值在於：早一天統一，需要回頭重命名的資源就少一批。

盤點現有資源作為納管輸入

資源盤點的責任是把「現實長什麼樣」寫成一份清單，它是日後納管的直接輸入 — 不知道有什麼，就無法決定先 import 什麼。手動環境最危險的是沒人記得還開著的資源。

盤點不必一次到位，先用平台工具把現況拉出來，存成可比對的形式：

1# 列出某區域所有 EC2 instance 與其關鍵標籤
2aws ec2 describe-instances \
3  --query 'Reservations[].Instances[].[InstanceId,Tags,State.Name]' \
4  --output table
5
6# 列出所有 security group 與開放規則，找出對外開放的 port
7aws ec2 describe-security-groups \
8  --query 'SecurityGroups[].[GroupId,GroupName,IpPermissions]' \
9  --output json

把輸出存進 repo，定期重跑比對差異，就能看出環境在背景悄悄長出了什麼。這份清單同時服務三件事：當下的安全盤查（有沒有不該開的對外 port）、未來 IaC import 的範圍界定、以及成熟度評估時「全手動到底有多少資源」的事實基礎（成熟度階梯的定位見「模組零：infra 是什麼」）。

資源與信任不足下的高槓桿取捨

當時間、人力或上層信任都不足，無法一次把上面每件事做齊時，取捨原則是先做「失誤代價高且護欄成本低」的少數幾件。在這個情境下，最划算的通常是兩件：先擋長期憑證外洩，因為一次外洩可能拖垮整個帳號；再開啟有狀態資源的刪除保護，因為資料一旦刪除多半無法復原。

變更日誌與資源盤點屬於累積型投資 — 越早開始，未來省的考古成本越多，但晚一週開始不會立刻出事，所以在資源極度受限時可以排在護欄之後。命名與 tagging 的取捨點在於：新建資源時順手套規則幾乎零成本，回頭重整存量資源才貴，所以策略是「新的一律照規範、舊的等有餘力再補」，而不是停下來先整理全部存量。資源不足時怎麼跟上層談這些工作的優先級，在「模組九：怎麼把 infra 推動起來」展開。

該開始導入 IaC 的訊號

手動環境到了某些訊號出現時，繼續手動的邊際成本會超過導入 IaC 的一次性成本，這就是該往模組一跨進去的時機。訊號是規模與協作的函數，不是時間的函數。

第一個訊號是環境數量變多：當你需要 dev、staging、production 三套幾乎一樣的環境，手動複製會在環境之間留下難以察覺的差異，而 IaC 的價值正是用同一份程式碼複製環境。第二個是多人同時動資源：一個人手動操作還能靠記憶維護，兩三個人並行時，沒有 plan / review 的手動變更會互相覆蓋、互相破壞。第三個是環境爆炸頻率上升：如果「改一個設定結果弄壞別的東西」這類事故開始每月發生，代表手動環境的隱性依賴已經超過人腦能追蹤的上限。

任一訊號穩定出現，就是把第一個資源納入 IaC 的起點 — 前面做的命名、tagging、資源盤點此時直接成為 import 的輸入，第一步怎麼跨進去在「模組一：最小可行 IaC」。在訊號出現前過早導入 IaC 也有代價：單人、單環境、低變更頻率時，IaC 的學習與維護成本可能高於它省下的手動工，所以這裡的判準是等訊號、不是趕進度。

章節文章

跨分類引用

• → 模組零：infra 是什麼：成熟度階梯上「全手動」這一階的定位
• → 模組一：最小可行 IaC：訊號出現後，第一步怎麼跨進 IaC
• → 模組二：身分與憑證地基：長期憑證護欄的系統性設計
• → 模組三：網路地基：手動階段網路大改的回退考量、之後的系統性設計
• → 模組八：治理好習慣：tagging 在成本歸因與批次操作的後續價值
• → 模組九：怎麼把 infra 推動起來：資源不足時怎麼跟上層談優先級
• → 接手維運：別人建的環境怎麼接管：接手前人的專案時的盤點與接管流程

這段地基平常被跳過，是因為多數人是在一台早就裝好的機器上開始管理 dotfile。但只要你換到全新環境——開一台 VM、租一台雲端主機、拿到一台空機器——就會直接撞上這層：安裝程式問你十幾個選項該怎麼選、裝完發現連 sudo 都沒有、想從本機連進去卻還沒有 SSH key。這些都不在編號模組的範圍，卻是跑 模組八的 bootstrap script 之前必須先過的關。

本系列的內容來自一次完整的 VM 實測：在 Apple Silicon 的 UTM 上從 archboot（Arch 的獨立網路安裝環境 ISO）裝 Arch Linux ARM、跑 dotfile 的 install.sh、一路把 Hyprland 桌面拉起來。實測中每個卡關點都被記錄下來，這裡把它們蒸餾成可重用的判讀與決策，不綁特定發行版或虛擬化軟體。

在學習路徑中的位置

模組零的操作順序指引 列出從 OS 安裝到桌面就緒的完整依賴鏈，但只把「安裝作業系統」標成一步。本系列是那一步的展開：安裝程式每個選項背後的取捨、裝完之後的驗證、以及連入機器的幾種路徑。

文章

機器裝好、能連入之後若出問題（連不上、終端機亂、程式行為怪），除錯與診斷自成一組，見同層的 Linux 除錯與診斷。

依情境的讀法

主線那幾篇照「安裝 → 驗證 → 連入 → 可除錯 → 無人值守」的順序，是「從零開一台新機器、到讓它自己跑活」的完整路線，但不是每個讀者都從零開始：

• 接手一台別人已裝好的機器：OS 已經在，從 最小安裝後的工具驗證與補足 切入，確認它缺不缺你流程要的工具。
• 雲端主機初始化：雲端主機多半已附 OS image、已有 sudo 與注入的 key，適用的是 外部連入、SSH key 與無 key 的 bootstrap 路徑 跟 可除錯的 bootstrap，前兩篇的 ISO 安裝可略過。
• bootstrap 失敗來 debug：直接讀 可除錯的 bootstrap，它也涵蓋「腳本不是你寫的、只想 debug 一次失敗」的情況。
• 讓機器無人值守跑活：機器已能連入操作，只想設好讓它在你離開後自己跑長任務或 agent，直接讀 讓機器跑無人值守的長任務。
• 遇到問題要除錯：機器已在跑但出狀況（連不上、終端機亂、程式行為怪），進 Linux 除錯與診斷，從 診斷心法 建立判讀紀律，再依症狀分流。
• 裝好後想讓它自己顧：服務跑起來後，主動確認這台有沒有在監控自己的服務死活（systemctl show sshd -p OnFailure），沒有就從最簡單的 OnFailure + ntfy 建起——遠端機器至少把 sshd 掛上，掛了就失聯。見 服務掛了怎麼自動知道。

跟其他模組的交叉引用

• 模組八：Bootstrap script 設計——本系列是它的前置；bootstrap 假設套件清單完整、機器可連入，本系列補「在那之前」。
• 模組五：Hyprland VM 測試——本系列的 VM 安裝是它的下游前置；裝好機器才能測 Hyprland。
• 模組七：日誌判讀與診斷工具——「可除錯的 bootstrap」與它呼應：前者談怎麼產生可診斷的 log，後者談怎麼讀。
• Linux 除錯與診斷——本系列裝好、連入之後的下游；出問題時的判讀紀律與情境分流。
• Linux 工具選單——安裝與除錯要用的工具（CLI / 圖形桌面 / 遠端）有哪些選擇、推薦用哪些。
• Infra 心智模型：拿到雲端帳號的第一天——雲端主機的機器初始化是本系列的上游情境；被指派 infra 工作、拿到一台雲端主機後，先過本系列的 OS 連入與 bootstrap 前置，再進 infra 的資源管理。

拍照：VM 快照與磁碟映像

第一種是拍照。VM 快照和磁碟映像（Clonezilla、dd）做的事是把整台機器某一刻的完整狀態凍結存檔——整個虛擬硬碟的 block-level 複製，有時連記憶體狀態都包含。還原就是把映像寫回去，系統回到那一刻，像時光倒流。Docker 的 docker commit 也屬於這個方向：把正在跑的 container 的檔案系統快照成一個 image。

拍照產出的是黑盒子。一個磁碟映像是二進制檔案，沒人能看出裡面到底做了什麼設定、裝了什麼、改過什麼。它大（動輒 GB 級）、跟硬體耦合（換不同架構或不同顯卡可能開不起來）、無法做 diff 或 code review。

重建指令：Dotfile repo + install script

第二種是重建指令。Dotfile repo + install script 描述的是「怎麼從一台空白機器組出這個環境」，每次都從零開始執行。Dockerfile 也是重建指令——一份「照著做就能重現」的食譜，描述每一步該安裝什麼、複製什麼、怎麼啟動。

重建指令產出的是白盒子。每一步都是可讀的文字——這行裝 zsh、那行設定 Hyprland 的 keybind——可以被 review、被 diff、被另一個人讀懂。它小（通常幾十 KB）、跨硬體（同一份 script 加 OS 判斷就能跑在不同機器）、可以進版控走 PR 流程。

dotfile 管理選的是重建指令這條路。代價是你必須把環境建構的過程記錄清楚——每裝一個新工具、每改一個配置都要同步更新 repo。回報是任何一台機器、任何時間點，都能用一份 Git repo 重現你的工作環境。

場景判讀

兩者不互斥——常見的組合是：用 dotfile 管理配置（長期可維護的基線），VM 快照用於短期實驗保護（改爛了可以秒回）。

判讀自己是否可控

可控的手動環境能在五分鐘內回答以下問題：

1. production 有哪些對外開放的 port？
2. 上週誰動過資料庫參數，動了什麼？
3. 刪掉某台機器會不會連帶弄壞別的東西？
4. 現在用了幾把長期 access key，每把用在哪裡？
5. 有沒有一份清單能對照 Console 上的資源，確認沒有漏掉的？

五題都能答的團隊不多，目標也不是一次全通。辨識出哪些區域不可見，按傷害代價從高到低逐一收斂，就是這一章的路線。

護欄先上在回退代價最高的操作

手動環境沒有 IaC 的 plan / diff 當預檢，人為操作直接生效。護欄的優先級看的是失誤的回退代價，不是操作頻率。回退代價最高的三類操作各自有最低成本的防線。

長期憑證外洩

長期 access key 一旦外流，攻擊者拿到的是不會過期的權限。回退代價高的原因不只是撤銷這把 key 本身，而是要找出所有使用它的地方同步更換 — 而「所有使用它的地方」在手動環境裡幾乎沒有完整清單。一把用了半年的 key 可能已經被複製到 CI 環境變數、某個同事的測試腳本、一個早已被遺忘但還在跑的 cron job 裡。

最低成本的護欄分三步。第一步是盤點：列出帳號裡所有長期 access key，記下建立時間、上次使用時間與對應用途。

1aws iam generate-credential-report
2aws iam get-credential-report --output text --query Content | base64 -d

第二步是替換路徑。對人類操作者，改用會過期的登入工作階段（如 AWS IAM Identity Center 的臨時憑證，幾小時後自動失效）。對跑在雲上的自動化（EC2 上的腳本、ECS task），改用平台原生的角色綁定 — instance profile 或 task role 會自動輪替短期憑證，程式碼不需要存任何 key。對跑在雲外的 CI/CD（如 GitHub Actions），改用 OIDC 聯合（見模組二：身分與憑證地基）。

第三步是輪替紀律。把還在用的長期 key 設定定期輪替提醒（60 天或 90 天，對齊 AWS IAM credential report 的建議週期），每次輪替時問自己：這把 key 能不能這次就換成臨時憑證，讓它成為最後一次輪替？

刪除 production 資源

在 Console 選中一個 security group 按刪除，平台可能只問「確定嗎？」就直接執行，不會告訴你有三個 EC2 instance 正在引用這個 group。EBS volume 被刪除後，上面的資料就不存在了 — 除非之前有做 snapshot，而手動環境裡有沒有做 snapshot 通常取決於某個人的記憶。

對承載狀態的資源，最低成本的護欄是開啟平台的刪除保護：

1aws rds modify-db-instance \
2  --db-instance-identifier payments-prod \
3  --deletion-protection \
4  --apply-immediately
5
6aws ec2 modify-instance-attribute \
7  --instance-id i-0abc123 \
8  --disable-api-termination

RDS 有 deletion_protection，EC2 有 termination_protection，S3 bucket 可以開 MFA delete。這些機制把「一鍵刪除」變成「先關保護再刪除」兩步操作，擋不住蓄意刪除，但能擋住手滑跟批次操作的誤傷。

刪除保護之外，備份是另一道防線。手動環境裡至少確認 RDS 的自動備份是開著的（預設保留 7 天），以及 S3 bucket 的 versioning 是開著的。S3 bucket 的 versioning 預設是關的，一個沒開 versioning 的 bucket，覆寫或刪除物件後就回不去了。

網路規則的大改

手動調整 VPC 路由、subnet 關聯的 route table、或 security group 的入站規則，影響範圍跨越多個服務，而且在手動環境裡沒有版本控制可以 diff 改了什麼。一條路由改錯，某些 private subnet 的服務可能瞬間失去出站能力。

最低成本的護欄是「改之前先把現況存下來」：

1aws ec2 describe-security-groups \
2  --group-ids sg-0abc123 \
3  --output json > sg-backup-$(date +%Y%m%d).json

用 CLI 把當前的 security group 規則、route table 設定匯出一份 JSON。改完後如果出問題，這份 JSON 就是回退的依據。這不是自動回退 — 手動環境沒有那個能力 — 但至少讓「改回去」有個明確的目標狀態。網路地基的系統性設計在模組三：網路地基展開。

該先做什麼

這三類護欄的共同判準是：護欄成本低（幾條 CLI 指令或 Console 設定）、失誤代價高（憑證外洩、資料遺失、服務中斷）。判讀某個資源該不該現在就加護欄，問自己一個問題：「這個資源出事的回退時間是分鐘級、小時級、還是不可回退？」不可回退的（資料刪除、key 外洩）優先加；分鐘級可回退的（重啟一個 stateless service）可以排後面。

讓變更留下痕跡

變更留痕的責任是讓「誰、在什麼時候、改了什麼、為什麼」事後可追溯。IaC 的 git history 天然提供這件事，手動環境得靠人為紀律補上。

人工變更日誌

最低限度是一份變更日誌，可以只是 repo 裡的一個 markdown 檔或團隊共用文件。一條記錄至少包含四個欄位：

1## 2026-06-20
2
3- **操作者**：alice
4- **資源**：sg-0abc123 (payments-api-prod)
5- **變更**：新增 ingress rule, port 8080 from 10.0.0.0/16
6- **原因**：內部監控服務需要存取 health check endpoint
7- **回退方式**：刪除該 ingress rule

格式不需要精美，需要的是「每次都寫」。常見陷阱是只在「大改動」時才記錄，結果真正出事的往往是某次以為無關緊要的小調整 — 改了一個 parameter group 的值、調了一條路由的目標、把某個 instance 的 security group 換了一個。判準簡化成一句：只要這個操作別人事後可能需要知道，就記。

平台稽核日誌

和人工日誌互補的是平台的稽核日誌（如 AWS CloudTrail、GCP Audit Log）。稽核日誌自動記錄 API 層級「發生了什麼」— 某個 IAM user 在某個時間對某個資源呼叫了哪個 API — 不依賴人為紀律、也不會漏。但它只記錄事實，不記錄意圖。它告訴你 security group 在幾點被改，卻不告訴你改的原因。人寫的變更日誌補上的正是「為什麼」這一段。

1aws cloudtrail describe-trails \
2  --query 'trailList[].{Name:Name,S3Bucket:S3BucketName}'
3
4aws cloudtrail lookup-events \
5  --lookup-attributes AttributeKey=EventName,AttributeValue=AuthorizeSecurityGroupIngress \
6  --max-items 10

CloudTrail 在 AWS 帳號裡預設開啟 management event 的 90 天查閱。手動環境裡至少確認 management event 的 trail 存在且在寫入 — 這是事後回推「到底誰動了什麼」的最後防線。兩者一起，事故排查時才能從「哪裡變了」一路追到「為什麼改、能不能安全回退」。

命名與 tagging 從手動階段就開始

命名規範與資源標籤讓每個資源自帶「我是誰、屬於哪個服務、誰負責、哪個環境」的身分資訊。手動點出來的資源若名稱是 test-2、new-db-final、temp-sg，日後納管時得靠人逐一辨認哪個還在用、屬於哪條業務線，考古成本遠高於當初多打幾個字。

命名規範

從手動階段就固定一套命名規則，讓名稱本身攜帶足夠的上下文。一個實用的格式是 {service}-{component}-{env}：

命名不需要完美或涵蓋所有維度，需要的是一致。同類資源都用同一套格式，人眼掃一頁 Console 就能分辨「這個屬於 payments 的 prod」跟「這個屬於 auth 的 dev」。不一致的命名（有些用底線、有些用連字號、有些帶 env 有些不帶）會在日後盤點時讓每個資源都變成需要考古的謎題。

最小 tag 集合

標籤至少包含三個維度：

手動階段的 tag 靠人工填。在 Console 建資源時順手加 tag 幾乎零成本 — 多打三行字而已。但如果沒有約定「哪些 tag 是必填」，多數人會跳過。最低限度的紀律是：在團隊文件裡寫下「建任何資源前先填這三個 tag」，並在每次盤點時檢查有沒有漏標的資源。

這套規則在導入 IaC 後直接升級成 Terraform 的 default_tags — 自動套用、不靠人記（見模組八：治理好習慣）。先在手動階段建立習慣，導入 IaC 時只是換一個強制機制，而不是從零學起一套分類法。

盤點現有資源作為納管輸入

資源盤點把「現實長什麼樣」寫成一份清單，它是日後納管的直接輸入。接手別人建的環境時，盤點的範圍和方法更完整的版本見接手維運模組。手動環境裡最難管理的是未標記的閒置資源 — 測試用的 EC2、實驗用的 RDS — 持續計費但沒有標籤，無法用查詢系統性找出，也無法確認是否仍有服務依賴。

盤點方法

按資源類型分批拉，每批存一份 JSON 或 CSV 進 repo：

 1aws ec2 describe-instances \
 2  --query 'Reservations[].Instances[].[InstanceId,InstanceType,State.Name,Tags[?Key==`Name`].Value|[0],Tags[?Key==`env`].Value|[0]]' \
 3  --output table
 4
 5aws rds describe-db-instances \
 6  --query 'DBInstances[].[DBInstanceIdentifier,Engine,DBInstanceClass,MultiAZ,DeletionProtection]' \
 7  --output table
 8
 9aws ec2 describe-security-groups \
10  --query 'SecurityGroups[].[GroupId,GroupName,IpPermissions]' \
11  --output json > security-groups-$(date +%Y%m%d).json
12
13aws s3api list-buckets --query 'Buckets[].Name'

盤點後的三件事

這份清單同時服務三個目的。

當下的安全盤查：security group 清單裡有沒有不該開的對外 port？有沒有 EC2 直接掛著公網 IP 卻不是 load balancer？用 0.0.0.0/0 搜一遍 security group 的輸出，命中的每一條都要能說出「這個全開是故意的、理由是什麼」。

未來 IaC import 的範圍界定：哪些資源該先 import。判準是「改動頻率」與「改錯代價」的乘積 — 頻繁改動且改錯代價高的（security group、IAM role）先排進來，很少動的（一個已經穩定的 S3 bucket）可以排後面。

成熟度評估的事實基礎：成熟度階梯的定位（見模組零：infra 是什麼）需要知道「全手動到底有多少資源、分布在幾個帳號、跨幾個 region」，這份清單就是評估的輸入。

盤點的節奏

第一次盤點最花時間，因為很多資源的用途需要考古。之後每月或每季重跑一次比對差異 — 重點是看「上次到這次之間長出了什麼新資源」。如果每次比對都發現大量未標記的新資源，這本身就是一個訊號：手動操作的可見性不足，該考慮導入 IaC 了。

資源與信任不足下的高槓桿取捨

當時間、人力或上層信任都不足，無法一次把上面每件事做齊時，取捨原則是先做「失誤代價高且護欄成本低」的少數幾件：

長期憑證盤點與刪除保護兩者加起來的實施時間可能不到一小時。命名與 tagging 的策略是「新的一律照規範、舊的等有餘力再補」，而不是停下來先整理全部存量。資源不足時怎麼跟上層談這些工作的優先級，在模組九：怎麼把 infra 推動起來展開。

該開始導入 IaC 的訊號

手動環境到了某些訊號出現時，繼續手動的邊際成本會超過導入 IaC 的一次性成本。訊號是規模與協作的函數，不是時間的函數 — 一個人運維一個簡單服務，手動可能撐很久；三個人同時動一個稍微複雜的環境，幾週內就會踩到手動的極限。

環境數量變多：當需要 dev、staging、production 三套幾乎一樣的環境，手動複製會在環境之間留下難以察覺的差異。某個人在 staging 加了一條 security group 規則，忘了在 prod 也加，結果 staging 測通了、prod 部署後服務連不上。IaC 用同一份程式碼複製環境，環境差異只存在於參數值。

多人同時動資源：一個人手動操作還能靠記憶維護，兩三個人並行時，沒有 plan / review 的手動變更會互相覆蓋。A 改了一個設定解了自己的問題，B 幾天後改了另一個設定把 A 的修正覆蓋掉，事故原因得靠翻 CloudTrail 才查得到。

環境爆炸頻率上升：如果「改一個設定結果弄壞別的東西」這類事故開始每月發生，代表手動環境的隱性依賴已經超過人腦能追蹤的上限。一個典型的隱性依賴：security group A 被 instance X 和 instance Y 同時引用，改 A 時只想著 X 的需求、忘了 Y 也依賴它，改完 Y 就斷了。

合規或稽核要求：外部稽核（SOC 2、ISO 27001）開始要求「列出所有對外暴露的服務」「提供存取權限的變更紀錄」「證明 production 環境的變更有經過審查」。手動環境回答這些問題時，每次都是一場考古工程。IaC 加上 PR 流程後，答案就在 repo 裡。

任一訊號穩定出現，就是把第一個資源納入 IaC 的起點 — 前面做的命名、tagging、資源盤點此時直接成為 import 的輸入。第一步怎麼跨進去在模組一：最小可行 IaC。

在訊號出現前過早導入 IaC 也有代價：單人、單環境、低變更頻率時，IaC 的學習與維護成本可能高於它省下的手動工 — 寫一份 HCL、配一個 state backend、設一條 pipeline 的固定成本，在只有三個資源的環境裡不一定划得來。這裡的判準是等訊號、不是趕進度。

跨分類引用

• → 接手維運：如果這個手動環境是接手來的，先走接手維運的盤點流程
• → 模組零：infra 是什麼：成熟度階梯上「全手動」這一階的定位
• → 模組一：最小可行 IaC：訊號出現後，第一步怎麼跨進 IaC
• → 模組二：身分與憑證地基：長期憑證護欄的系統性設計
• → 模組三：網路地基：手動階段網路大改的回退考量、之後的系統性設計
• → 模組八：治理好習慣：tagging 在成本歸因與批次操作的後續價值
• → 模組九：怎麼把 infra 推動起來：資源不足時怎麼跟上層談優先級

範例結構

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4DOTFILES_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 5
 6# --- 偵測 OS ---
 7OS="$(uname -s)"
 8
 9install_packages() {
10    if [[ "$OS" == "Darwin" ]]; then
11        command -v brew >/dev/null || {
12            echo "Installing Homebrew..."
13            /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
14        }
15        brew bundle --file="$DOTFILES_DIR/Brewfile"
16
17    elif [[ -f /etc/arch-release ]]; then
18        sudo pacman -Syu --noconfirm
19        sudo pacman -S --needed - < "$DOTFILES_DIR/packages.txt"
20        # AUR 套件需要 AUR helper（假設已安裝 yay）
21        if command -v yay >/dev/null && [[ -f "$DOTFILES_DIR/aur-packages.txt" ]]; then
22            yay -S --needed - < "$DOTFILES_DIR/aur-packages.txt"
23        fi
24
25    elif [[ -f /etc/debian_version ]]; then
26        sudo apt update
27        xargs -a "$DOTFILES_DIR/apt-packages.txt" sudo apt install -y
28    fi
29}
30
31deploy_configs() {
32    if ! command -v stow >/dev/null; then
33        echo "stow not found, skipping config deployment"
34        return 1
35    fi
36    cd "$DOTFILES_DIR"
37    for dir in zsh git nvim tmux hypr waybar; do
38        [[ -d "$dir" ]] && stow -v --target="$HOME" "$dir"
39    done
40}
41
42post_setup() {
43    # 切換預設 shell
44    if [[ "$SHELL" != "$(command -v zsh)" ]] && command -v zsh >/dev/null; then
45        chsh -s "$(command -v zsh)"
46    fi
47
48    # neovim plugin 安裝（headless 模式）
49    if command -v nvim >/dev/null; then
50        nvim --headless "+Lazy! sync" +qa 2>/dev/null || true
51    fi
52}
53
54echo "=== Installing packages ==="
55install_packages
56
57echo "=== Deploying configs ==="
58deploy_configs
59
60echo "=== Post-setup ==="
61post_setup
62
63echo "Done. Log out and back in for shell changes to take effect."

設計原則

冪等性是最重要的性質。跑一次和跑十次結果相同。pacman -S --needed 只安裝缺少的套件、stow 只建立不存在的 symlink、command -v 在工具已存在時跳過安裝（用 command -v 不用 which——後者在最小系統可能不存在）。冪等的 script 可以放心重跑——改了一個配置後重新 deploy，不會弄壞其他已經正確的部分。

失敗可診斷是這支範例為了聚焦結構而省略、但實際該有的性質。bootstrap 在陌生機器上失敗是常態，怎麼讓它在某一步掛掉時留下可定位的痕跡（全輸出 tee 落地 + ERR trap 點名出錯的行與指令），見 可除錯的 bootstrap——那篇是這支腳本的「失敗時看得見」那一層。

偵測 OS 分流處理的是跨平台差異。macOS 用 Homebrew、Arch 用 pacman、Debian 系用 apt——套件管理器不同、套件名稱有時也不同（macOS 的 coreutils 在 Linux 是預裝的）。分流邏輯集中在 bootstrap script 裡，配置檔本身盡量保持跨平台一致。

最少依賴原則：script 本身只依賴 bash 和 curl（幾乎所有系統預裝），其他工具由 script 自己安裝。這確保你可以在一台只有 base system 的機器上直接跑 script。不過「base system 直接跑」有個前提——最小安裝可能連 sudo 都沒有，而 script 裝套件正要靠它。跑這支 script 之前該驗證並補齊的前置工具，見 最小安裝後的工具驗證與補足。

交付完整可用的環境：script 的職責是讓部署完的配置「能直接用」，所以它必須裝齊配置實際引用的每一樣東西，而不是假設它們已經在。一個常見的破綻是把依賴寫進 README 的「dependencies」清單、卻沒在 script 裡實作安裝——例如 .zshrc 引用了 oh-my-zsh、主題、外掛，但 install script 只裝了 zsh 本身，結果 stow 部署完、第一次開 shell 就因為找不到那些東西而報錯。README 列依賴是給人看的、不會被執行；要讓配置真的能用，那些依賴得由 script 自己裝（例如把外掛 git clone 進對應位置）。檢查方式是反過來從配置出發：把每個 config 會 source 或引用的外部東西列出來，逐一確認 script 有沒有負責把它裝上。

可部分執行的結構：拆成 function，允許只跑某一段。除錯時只想重新 deploy 配置、不想重裝套件，直接呼叫 deploy_configs 就好。進一步可以把每段拆成獨立 script（scripts/install-packages.sh、scripts/deploy-configs.sh），bootstrap 入口只是依序呼叫它們。

套件清單管理

dotfile repo 管的是「配置」，但配置的前提是軟體已安裝。沒有附帶套件清單的 dotfile repo 是不完整的重建指令——你 clone 下來卻不知道該先裝什麼。

macOS：Brewfile

 1# Brewfile
 2tap "homebrew/cask-fonts"
 3
 4# CLI 工具
 5brew "git"
 6brew "neovim"
 7brew "tmux"
 8brew "stow"
 9brew "ripgrep"
10brew "fd"
11brew "fzf"
12brew "zsh"
13
14# GUI app
15cask "wezterm"
16cask "rectangle"
17cask "font-jetbrains-mono-nerd-font"

brew bundle dump 從當前系統產生 Brewfile、brew bundle 照 Brewfile 安裝。Brewfile 區分三種來源：brew（CLI formula）、cask（GUI app）、tap（第三方 repo）。把 Brewfile 放在 dotfile repo 根目錄，bootstrap script 用 brew bundle --file=./Brewfile 安裝。

Arch Linux：packages.txt

1# 匯出已安裝的 explicitly installed 套件
2pacman -Qqe > packages.txt
3
4# AUR 套件另外記
5pacman -Qqem > aur-packages.txt

-Qqe 只列出使用者主動安裝的套件（不含被依賴自動拉進來的），這是你實際需要管理的範圍。-Qqem 進一步篩出外部來源（AUR）。還原時用 pacman -S --needed - < packages.txt，--needed 跳過已安裝的。

Ubuntu/Debian

apt 的匯出格式比較雜。務實做法是手動維護一份清單檔（apt-packages.txt），每行一個套件名，用 xargs -a apt-packages.txt sudo apt install -y 安裝。比起 apt list --installed 的完整匯出（包含大量系統依賴），手動維護的清單更乾淨、更容易讀懂。

為什麼套件清單要進 repo

一個常見的失敗模式：dotfile repo 裡有完整的 neovim 配置，clone 到新機器後發現 neovim 沒裝、ripgrep 沒裝、字型沒裝，配置跑起來全是 error。套件清單跟配置檔放在同一個 repo，bootstrap script 才能先裝套件再 deploy 配置，形成完整的重建鏈路。

這層落差最常在你跑自動化腳本時引爆。一支 bootstrap script 的第一行可能就是 sudo pacman -S ...，在一台連 sudo 都沒有的機器上，它連第一步都跨不過去。所以裝好系統後、跑任何自動化之前，先過一輪工具驗證，把缺的補上。

sudo：先有雞還是先有蛋

sudo 是最容易被假設存在、卻最常缺席的工具，而且它的缺席有一個結構性的麻煩：補它的動作本身需要 root 權限。最小安裝通常不含 sudo。某些安裝程式（如本例的 archboot）即使你勾了「把這個使用者設為管理員」，那個動作也往往只是把使用者加進 wheel 群組，並沒有真的裝上 sudo、也沒有啟用 sudoers 裡 wheel 群組的授權行。結果就是使用者「名義上是管理員」，但系統裡並沒有 sudo 這支指令。

這形成一個先有雞還是先有蛋的關卡：bootstrap script 要靠 sudo 來裝套件，但 sudo 自己得先存在。它的解法不能是「把 sudo 寫進套件清單」——那份清單正是靠 sudo 來安裝的。sudo 只能是「跑 bootstrap 之前的前置」，用 root 身分手動補上（su - 成為 root、echo > 檔案 重導向、chmod 設權限這些基礎操作不熟的話，見 安裝過程用到的基礎操作）：

1su -                                          # 切到 root（輸入 root 密碼）
2pacman -S --needed sudo                        # root 身分裝 sudo，不需要 sudo
3echo '%wheel ALL=(ALL:ALL) ALL' > /etc/sudoers.d/10-wheel   # 啟用 wheel 群組授權
4chmod 440 /etc/sudoers.d/10-wheel
5visudo -c                                      # 驗證 sudoers 語法，印 parsed OK 才安全
6exit

切回一般使用者後用 sudo -v 確認——能輸入密碼、沒報「不在 sudoers 檔」就成。這一步揭示一條通則：凡是 bootstrap 自身要依賴的工具，都不能由 bootstrap 來裝，必須當成前置先備好。sudo 是這類前置最典型的一個。

上面的指令以 Arch 的 pacman 為例。Fedora 用 dnf、Debian/Ubuntu 用 apt；而 Debian 系的桌面與伺服器映像多半預設就裝了 sudo、也設好了授權，這個缺口主要出現在刻意精簡的 minimal 安裝。換句話說「sudo 是前置」這條判讀軸跨發行版成立，但「你這台到底缺不缺」要靠驗證、不是假設。

which：腳本裡的隱形地雷

which 是另一個最小系統常缺、卻被腳本大量引用的指令，它的缺席會以一種隱晦的方式讓腳本出錯。很多腳本用 $(which zsh) 之類的寫法取一支程式的完整路徑；在沒有 which 的系統上，這個命令替換會吐出空字串，而下游拿到空字串的指令可能不會立刻報「找不到 which」，而是報一個看似無關的錯。實測中就遇過 chsh -s "$(which zsh)" 因為 which 不存在而變成 chsh -s ""，最後報的是 chsh: shell must be a full path name——錯誤訊息完全沒提到真正的元兇。

正確的做法是用 command -v 取代 which。command -v 是 POSIX 規範的 shell 內建，不依賴任何外部套件，在最小系統上一定存在。

1command -v zsh        # 印出 /usr/bin/zsh；找不到則回傳非零、不印東西

這條判讀對你自己寫的腳本是「把 which 全換成 command -v」，對別人的腳本是「在缺 which 的系統上，先補 which 套件或改腳本」。它跟 sudo 的差別在於：which 的缺席會悄悄製造一個誤導性的下游錯誤，而不是當場大聲報錯，所以更值得在驗證階段主動排掉。

其他常缺的工具

除了 sudo 與 which，最小系統還常缺幾類在自動化裡會用到的工具，各有各的補法。它們不像 sudo 是硬前置，但缺了會在特定步驟卡住。

rsync 的缺席要特別點出，因為它常被當成理所當然的傳輸工具。最小系統沒有它時，第一次把檔案弄進機器可以用兩邊都有的 tar 搭配 SSH 過渡：

1tar czf - --exclude '.git' . | ssh user@host 'mkdir -p ~/dest && tar xzf - -C ~/dest'

這條的好處是不依賴目標機有 rsync；缺點是它每次都傳全部、沒有 rsync 的增量。在反覆同步的工作流裡，值得早點把 rsync 補進套件清單換取增量傳輸。

ca-certificates 最容易在下一步咬人。最小系統可能沒有 CA 信任根，這時任何 HTTPS 連線——包括下一篇主推的「公開 repo 用 HTTPS clone」——會在 TLS 憑證驗證直接失敗，而錯誤訊息常指向 SSL handshake 而非「缺信任根」，容易誤判成網路問題。打算走 HTTPS 取得 dotfile 的機器，先確認 ca-certificates 在。git 與 curl 同理：它們是 bootstrap 取得程式碼的基本工具，下面的驗證迴圈也會檢查，最小系統若沒有要一併補。

剩下兩項的缺席各有觸發時機。hostname 只在腳本明確呼叫它取主機名時才會浮現缺失，而用 hostnamectl 或直接讀 /etc/hostname 可以繞過，所以它常被當成「補了省事、不補也有替代」的軟缺口。編譯工具鏈則是在你要從原始碼或社群套件庫編譯時才需要——純跑預編譯套件的機器可以不裝，但只要你的 dotfile 流程會編譯任何東西（例如從社群套件庫裝桌面元件），它就得進清單。

系統性的驗證

裝好系統後先跑一輪集中驗證、把缺口一次盤出來，比等腳本跑到一半才逐一踩雷省事。驗證的對象是「你接下來的流程會用到、但最小系統可能沒有」的工具。

1for cmd in sudo git curl rsync tar zsh; do
2  if command -v "$cmd" >/dev/null 2>&1; then
3    echo "OK   $cmd"
4  else
5    echo "缺   $cmd"
6  fi
7done

這段刻意用 command -v 來檢查（而不是 which），因為要檢查的對象之一正是「外部工具在不在」，用一個一定存在的內建來檢查才不會自己先掛掉。盤出來的缺口分兩類處理：bootstrap 自身依賴的（如 sudo）當前置手動補；其餘的（如 rsync、編譯工具）進套件清單，交給 bootstrap 一起裝。

跟 Bootstrap 套件清單的界線

這篇的驗證跟 模組八的 bootstrap script 設計 是兩件互補的事，界線在「假設」上。bootstrap script 的套件清單假設一個前提：機器已經有能力執行安裝（有 sudo、有 package manager、清單裡的東西都能被裝上）。這篇處理的正是那個前提成立之前的階段——最小系統到底有沒有滿足那些假設，缺的補上，讓 bootstrap 的假設變成事實。

換句話說，套件清單回答「這台機器最終要有哪些套件」，工具驗證回答「這台機器現在夠不夠資格開始跑那份清單」。把兩者分清楚，才不會把 sudo 這種前置誤塞進靠 sudo 安裝的清單裡。

下一步

工具補齊、機器有能力執行安裝之後，你還困在一個地方：擠在機器的主控台手打。怎麼從舒適的本機終端機操作它，以及還沒有 SSH key 時怎麼把 dotfile 弄進去，外部連入、SSH key 與無 key 的 bootstrap 路徑 處理這兩件事。

SSH key 是典型例子：管理工具和 shell 配置的知識在模組一和模組二，但實際操作時 SSH key 比這兩者都早——因為 git clone git@github.com:... 本身就需要 SSH key。如果照模組順序走，到模組二才發現 dotfile repo clone 不下來。

這篇是路線圖，告訴你每一步做什麼、為什麼這個順序、以及去哪個模組看具體操作。

階段一：基礎設施（後續所有步驟的前提）

這些步驟在任何配置之前完成，因為它們是 Git、遠端存取、dotfile clone 的前提。

1. 安裝作業系統 + 建立使用者帳號

macOS：開箱即用。Linux：選發行版（Arch 如果要用 Hyprland）、完成安裝、建立非 root 使用者。安裝程式每個選項該怎麼判讀、裝完最小系統缺哪些必要工具（連 sudo 都可能沒有），見 Linux 安裝選項判讀 與 最小安裝後的工具驗證與補足——這一步是整個系列展開最深、卻最常被一句帶過的地基。

2. 生成 SSH key pair

1ssh-keygen -t ed25519 -C "your-email@example.com"

為什麼這麼早做：

• Git 操作：GitHub / GitLab 的 SSH 認證需要 public key。dotfile repo 通常用 SSH URL（git@github.com:...），clone 前要先把 key 部署到 GitHub。用 HTTPS URL 可以繞過 SSH key，但長期來看 SSH key 是更省事的認證方式。還沒有 key、或想用 HTTPS / PAT 把 dotfile 弄進一台新機器的幾種路徑，見 外部連入、SSH key 與無 key 的 bootstrap 路徑。
• 遠端救援：模組七的場景三（GPU hang）依賴 SSH 作為桌面凍結時的救生通道。key 提前設好，出問題時才有路可走。
• 跨機器操作：筆電連桌機、桌機連 VM、VS Code Remote SSH——都靠這把 key。

3. 部署 public key

把 ~/.ssh/id_ed25519.pub 加到需要的服務：

1# 加到 GitHub
2cat ~/.ssh/id_ed25519.pub
3# 複製輸出，貼到 GitHub → Settings → SSH and GPG keys → New SSH key
4
5# 加到另一台機器（可選，用於跨機器 SSH）
6ssh-copy-id user@target-machine

4. Package manager + Git

macOS：先裝 Homebrew（macOS 的套件管理器，後續安裝 stow、tmux 等工具都靠它），再裝 Git：

1# 安裝 Homebrew
2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3
4# 安裝 Git（或用 xcode-select --install，會一併裝 Apple 的 Git）
5brew install git

Arch：pacman 隨 OS 安裝已可用，直接裝 Git：pacman -S git。

5. Clone dotfile repo

1git clone git@github.com:yourname/dotfiles.git ~/dotfiles

如果是第一次建 dotfile repo（還沒有 repo），先建一個空的再開始往裡面加配置。具體做法見模組一：管理工具與目錄結構。

階段二：Shell 與終端機（日常操作的基礎）

Shell 是所有操作的介面，終端機是 shell 的容器。這兩層配置好，後續的安裝、設定、除錯效率會高很多。

6. 安裝管理工具（stow / chezmoi）

把 dotfile repo 裡的配置 symlink 到正確位置。具體選型和操作見模組一。

7. Shell 配置（.zshrc / .bashrc）

模組化拆分、PATH 設定、alias、prompt。做完這一步，終端機操作才順手。見模組二：Shell 配置。

8. 終端機 + 編輯器

Terminal emulator 選型、tmux/zellij、neovim 基礎配置。見模組三：終端機與編輯器。

macOS 用戶到階段二完成後就有一個完整的工作環境。下一步依序讀模組一（管理工具選型）、模組二（shell 配置）、模組三（終端機），然後跳到階段四的 bootstrap script。階段三是 Linux 桌面環境的設定，macOS 用戶跳過。

階段三：桌面環境（Linux 限定）

macOS 用戶到階段二就有一個完整的工作環境了。以下步驟是 Linux 桌面環境的設定，macOS 用戶可以跳到階段四。

9. 視窗管理器

平鋪式 vs 浮動式的選型，Hyprland 安裝和核心配置。見模組四和模組五。

10. 桌面配套工具 + Rice

waybar、wofi、mako、配色系統。見模組六：桌面 Rice 設計。

11. 啟用 SSH server + 預防措施

桌面環境可用之後，設定遠端救援通道和預防性配置：

 1# SSH server（出問題時可以從另一台機器救援）
 2sudo systemctl enable sshd
 3sudo systemctl start sshd
 4
 5# 停用密碼登入（確保 SSH key 已設好）
 6# 編輯 /etc/ssh/sshd_config：PasswordAuthentication no
 7
 8# swap（OOM 緩衝）
 9sudo fallocate -l 4G /swapfile
10sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
11
12# systemd-oomd
13sudo systemctl enable systemd-oomd

為什麼放在桌面設定之後：SSH server 和 swap 是預防措施，桌面能用了才有東西要保護。但 SSH key pair（階段一步驟 2-3）要提前做——key pair 是認證基礎設施，server 只是把門打開。

詳細的故障場景和預防措施見模組七：桌面環境維護與故障排除。

階段四：同步與可攜性

環境建好之後，確保這份配置能搬到下一台機器。

12. Bootstrap script

把階段一到三的操作自動化成 script，下次換機器跑一次就好。見模組八：同步、Bootstrap 與環境重建。

13. Secret 管理

哪些東西該進 repo、哪些要排除（SSH private key、API token、密碼）。同樣見模組八。

依賴關係速查

 1OS 安裝
 2  └─ SSH key pair ← 後續所有 Git / SSH 操作的前提
 3       └─ Git 安裝
 4            └─ dotfile repo clone
 5                 └─ 管理工具（stow link）
 6                      ├─ Shell 配置
 7                      ├─ 終端機 + 編輯器
 8                      └─ 桌面環境（Linux，macOS 到此為止 → 直接跳階段四）
 9                           └─ SSH server + 預防措施
10                                └─ Bootstrap script 自動化

可以亂序的步驟

依賴圖裡同一層級的步驟可以調換順序。具體來說：

• Shell 配置、終端機配置、編輯器配置三者互不依賴，先做哪個都行
• 視窗管理器和桌面配套工具可以交替設定（先裝 Hyprland 再裝 waybar，或反過來）
• swap 和 SSH server 互不依賴，先做哪個都行

跨層級的依賴必須按順序：SSH key 是 clone repo 的前提，repo 是 stow link 的前提，stow link 是 shell 配置生效的前提。

多台機器共用 dotfile repo 時，需要一套同步策略來處理「改了配置後怎麼讓其他機器也更新」。

Git push/pull（手動）

最基本的做法：改了就 commit + push，另一台機器 pull + 重新 apply。優點是簡單、沒有額外依賴。缺點是容易忘記——在公司機器上改了一個 alias，回家忘記 push，隔天公司又改了一版，兩邊 diverge。

適合只有一兩台機器、改動不頻繁的人。

自動同步

chezmoi 內建 chezmoi update 指令（pull + apply 一步完成），搭配 cron 或 systemd timer 定期執行：

 1# ~/.config/systemd/user/chezmoi-update.timer
 2[Unit]
 3Description=Update dotfiles daily
 4
 5[Timer]
 6OnCalendar=daily
 7Persistent=true
 8
 9[Install]
10WantedBy=timers.target

1# ~/.config/systemd/user/chezmoi-update.service
2[Unit]
3Description=chezmoi update
4
5[Service]
6Type=oneshot
7ExecStart=/usr/bin/chezmoi update --no-tty

自動同步減少手動操作，但要注意衝突處理——如果兩台機器同時改了同一個檔案且都 push，後面那台的自動 pull 會遇到 merge conflict。實務上 dotfile 很少有真正的衝突（兩台機器同時改同一行的機率低），但偶爾發生時需要手動介入。

機器差異的處理

推薦的模式是 main branch 放所有共用配置，機器差異用條件判斷處理。

用 shell 的 OS 判斷：

1# ~/.zshrc
2if [[ "$(uname -s)" == "Darwin" ]]; then
3    export PATH="/opt/homebrew/bin:$PATH"
4    alias ls="ls -G"
5else
6    alias ls="ls --color=auto"
7fi

用 chezmoi template（Go template 語法）：

1# chezmoi 管理的 .zshrc.tmpl
2{{ if eq .chezmoi.os "darwin" -}}
3export PATH="/opt/homebrew/bin:$PATH"
4{{ end -}}
5
6{{ if eq .chezmoi.hostname "work-laptop" -}}
7export HTTP_PROXY="http://proxy.corp:8080"
8{{ end -}}

chezmoi template 的優勢是條件判斷發生在 apply 階段，產出的檔案裡看不到 template 語法，乾淨且不依賴 shell 的 runtime 判斷。

不推薦每台機器一個 branch 的做法。短期可行，長期一定 diverge——main 加了新配置，各 branch 要 rebase 或 merge，忘了就漂移。一份 main + template 條件判斷是長期可維護的結構。

Secret 排除與管理

dotfile repo 通常是 public 或至少多人可見的。以下東西進了 repo 等於把鑰匙掛在門口：

• SSH 私鑰（~/.ssh/id_*、*.pem）
• API token、password、.env 檔案
• GPG 私鑰
• cloud provider 的 credential 檔案（~/.aws/credentials、~/.config/gcloud/application_default_credentials.json）
• browser profile 裡的 cookie / session

.gitignore 是第一道防線

# SSH 私鑰
*.pem
id_*
known_hosts
authorized_keys

# 環境變數
.env
.env.*

# Cloud credentials
credentials
application_default_credentials.json

但 .gitignore 只防「不小心 add」，不防「故意 add -f」。更重要的是建立習慣：repo 裡永遠只放「看到了也沒關係」的東西。

SSH config 的特殊處理

~/.ssh/config（host alias、ProxyJump 設定、port forwarding）本身不含 secret，可以進 repo——它記錄的是「連線要怎麼走」而不是「憑證是什麼」。但同一個 ~/.ssh/ 目錄下的私鑰絕對排除。

stow 管理時的目錄結構範例：

1dotfiles/
2└── ssh/
3    └── .ssh/
4        └── config        # 進 repo
5        # id_rsa 不放這裡
6        # known_hosts 不放這裡

三個層級的 secret 管理

層級一：手動。.gitignore 排除 secret 檔案，在 README 記錄「這些東西需要在新機器手動設定」。最低成本、對只有一兩台機器的人足夠。

層級二：密碼管理器整合。chezmoi 支援從 1Password、Bitwarden、pass（Unix password manager）等拉取 secret：

1# chezmoi template 語法
2{{ (onepasswordRead "op://Personal/SSH Key/private key").value }}

配置檔的 template 裡引用密碼管理器的條目，apply 時自動填入。secret 不在 repo 裡，但 repo 知道去哪拉。

層級三：加密存放。用 age 或 sops 把 secret 加密後直接存在 repo 裡。解密需要對應的 key。chezmoi 原生支援 age 加密：

1# 加密一個檔案
2chezmoi add --encrypt ~/.ssh/id_rsa
3
4# repo 裡看到的是加密後的內容
5cat ~/.local/share/chezmoi/private_dot_ssh/id_rsa.age

加密存放的好處是 secret 跟著 repo 走、不用另外設密碼管理器。風險是加密 key 本身變成唯一的依賴——丟了 key，加密的 secret 就拿不回來。

層級選擇取決於安全需求和便利需求的平衡。多數情況從層級一開始，覺得手動處理太煩再往上升級。

環境重建的實際流程

假設拿到一台全新的 Arch Linux 機器，要從零重建完整的 Hyprland 桌面環境。以下是 end-to-end 的步驟，對應 bootstrap script 的每個階段。

階段一：最小可用環境

1# Arch 安裝完成後，base system 只有 bash 和基本工具
2sudo pacman -S git base-devel

這是 bootstrap script 的唯一外部前提：有 Git 能 clone repo、有 base-devel 能編譯 AUR 套件。其他一切由 script 處理。

階段二：取得 dotfile repo

1git clone https://github.com/you/dotfiles ~/dotfiles
2cd ~/dotfiles

如果 repo 是 private，這一步需要先設定 SSH key 或用 HTTPS + token。這是前面提到的 secret 雞生蛋問題——clone 含有 SSH config 的 repo 本身就需要 SSH key。解法通常是：第一次用 HTTPS clone，deploy 完 SSH config 後把 remote 改成 SSH。

階段三：執行 bootstrap

1./scripts/install.sh

script 依序：安裝套件（Hyprland、waybar、rofi、wezterm、zsh、neovim、stow 等）、用 stow 部署配置到 $HOME、執行初始化（換 shell、安裝 neovim plugin）。

階段四：手動處理

bootstrap 處理不了（或不該處理）的部分：

• SSH 私鑰：從備份或密碼管理器取回，放到 ~/.ssh/，設定正確權限（chmod 600）
• Git 簽署用的 GPG key：如果有用 commit signing
• 密碼管理器登入：如果 secret 管理用了層級二或三

階段五：硬體相關調整

Hyprland 的 monitor 設定（解析度、縮放、排列位置）跟實際接的螢幕有關，這部分配置每台機器都不同：

1# ~/.config/hypr/hyprland.conf 的 monitor 段
2# 這幾行在每台機器上都要調
3monitor=DP-1, 2560x1440@144, 0x0, 1
4monitor=HDMI-A-1, 1920x1080@60, 2560x0, 1

處理方式有兩種：把 monitor 設定拆成獨立的 monitor.conf，主配置用 source 引入，monitor.conf 不進 repo（加進 .gitignore）、每台機器本地維護；或者用 chezmoi template 按 hostname 判斷。

顯卡驅動（Intel/AMD 通常自動、NVIDIA 需要額外安裝 nvidia-dkms 和設定環境變數）也是硬體相關的步驟，可以放在 bootstrap script 的 OS 判斷裡，但通常 Arch 安裝階段就已經處理。

階段六：驗證

1# 登出 TTY，重新用 Hyprland 登入
2# 或者直接在 TTY 執行
3Hyprland

登入後確認：視窗管理器正常運作、keybind 正確、狀態列出現、字型正確渲染、終端機配色正常。如果某個元件沒反應，通常是套件沒裝或配置路徑不對——回去檢查 bootstrap 的套件清單和 stow 的 symlink。

時間預估

整個流程在網路順暢的情況下，大約 30 分鐘到 1 小時，取決於套件數量和下載速度。主要時間花在套件安裝（pacman 下載 + 編譯 AUR 套件）。配置 deploy 本身是秒級操作（stow 只建 symlink）。

對比沒有 dotfile 管理時的重建：邊想邊裝、裝了忘記某個工具的名稱、配置靠記憶手打、兩天後還在調某個快捷鍵為什麼不對。差距在「可預期 vs 碰運氣」。

維護節奏

環境重建能力需要持續維護，不是設定完就一勞永逸。

日常習慣：新裝一個工具時，順手更新套件清單（brew bundle dump 或手動加一行到 packages.txt）。改了一個配置後，commit + push。這個習慣的建立成本低，但需要刻意練幾週才會變成反射動作。

定期檢查：每隔幾個月在 VM 或 container 裡跑一次完整的 bootstrap，驗證 script 還能從零跑通。配置會演進、套件會改名或被取代、script 裡硬寫的路徑可能失效——定期驗證才能確保「這份重建指令真的能重建」，而不是一份過期的紀錄。

這篇處理三件事：把 sshd 跑起來並從本機連入、設 SSH key 達到免密碼、以及一個容易被卡住的情境——你還沒有 SSH key 時，怎麼把 dotfile 弄進機器、跑完基礎安裝。

啟用 sshd 並從本機連入

讓機器能被 SSH 連入只需要兩步：裝 SSH 伺服器、啟動它的服務。

1pacman -S openssh             # 剛裝好的系統套件資料庫是新的，-S 不必先 -Sy
2systemctl enable --now sshd   # enable 開機自啟、--now 立刻啟動

指令以 Arch 為例。換發行版時套件管理器不同（Fedora dnf、Debian/Ubuntu apt），服務名也可能不同——Debian 系的 OpenSSH 服務叫 ssh 不是 sshd，那邊要 systemctl enable --now ssh。

從本機連的時候用一般使用者、不要用 root：

1ssh user@<機器 IP>            # IP 來自機器上的 ip -brief a

用一般使用者是因為多數發行版的 sshd 預設擋 root 密碼登入（PermitRootLogin prohibit-password）——root 只能用 key、不能用密碼。這個預設是好的安全姿態，順著它走、用你裝系統時建的一般使用者連即可。連進去之後，後續所有需要長指令、需要貼上的操作都在這個 session 裡做，不再回主控台手打。

這裡啟用 sshd 是為了 bootstrap 期間從本機連入操作，跟 操作順序指引 後段把 sshd 當「桌面就緒後的常駐遠端救援通道」是兩個不同的時間點與目的——同一個 systemctl enable sshd 動作，這裡是為了「現在好操作」，那裡是為了「之後好救援」。

SSH key 免密碼

每次連線都打密碼很快會變成阻力，尤其當你要反覆同步檔案或跑自動化時。SSH key 讓本機免密碼連入，做法是生一把金鑰、把公鑰放進機器、本機用私鑰認證。

生 key 時建議生一把專用的、不要佔用本機的預設金鑰槽，並在 SSH 設定裡給它一個好記的別名：

1ssh-keygen -t ed25519 -f ~/.ssh/vm_arch -N "" -C "vm_arch host->target"
2# 在 ~/.ssh/config 加一段別名：
3#   Host vm
4#       HostName <機器 IP>
5#       User <你的使用者>
6#       IdentityFile ~/.ssh/vm_arch
7#       IdentitiesOnly yes

專用 key 的好處是它的權限範圍清楚——這把只給這台機器用，跟你其他身分的金鑰互不牽連。設好別名後，ssh vm 就免密碼連入，後面的 rsync、scp 也跟著免密碼。

把公鑰放進機器有兩條路。標準工具是 ssh-copy-id，它會在本機跑、要你輸入一次目標機的密碼。另一條省一次切換的路是：當你已經用密碼連進機器、且這個 session 在真終端機裡（貼上可用），直接把公鑰內容貼進機器的 authorized_keys：

1mkdir -p ~/.ssh && chmod 700 ~/.ssh
2echo "ssh-ed25519 AAAA... 你的公鑰內容" >> ~/.ssh/authorized_keys
3chmod 600 ~/.ssh/authorized_keys

兩條路等價，選哪條看你當下在哪——還沒連上就用 ssh-copy-id，已經連上就直接貼，少一次切換。

還沒有 SSH key 時，怎麼把 dotfile 弄進去

設 SSH key 是讓「之後」連線變方便，但 bootstrap 的第一步——把 dotfile repo 弄進機器——並不一定需要 key。常見的卡點是把「clone repo」跟「有 SSH key」綁在一起，但 clone 有不需要 key 的路徑。怎麼把 dotfile 弄進去，取決於這份 dotfile 放在哪。

repo 是公開的（在 GitHub 之類）：用 HTTPS clone，公開 repo 的唯讀 clone 不需要任何認證。

1git clone https://github.com/<帳號>/dotfiles ~/dotfiles
2cd ~/dotfiles && ./scripts/install.sh

這是最直接的路——機器只要能上網就能拉到 dotfile，完全繞過 key 的問題。clone URL 裡的帳號要對；用錯帳號（例如把 email handle 當成 GitHub 帳號）會 clone 失敗或抓到別的 repo，這類筆誤在只看 README 範例時很容易漏掉。SSH key 在這個情境只有「之後要從機器 push 回去」才需要，純粹跑部署用不到。

repo 是私有的、但機器能上網：機器可以直接 clone，用 GitHub Personal Access Token（PAT）走 HTTPS——這是私有 repo 免 SSH key 的標準解。clone 時把 PAT 當密碼填進認證，機器就拉得到，一樣不必在它上面設 SSH key。

repo 還沒推到任何遠端、或機器離線：從本機把檔案傳進去。如果本機到機器的 SSH 已經能用（即使只是密碼登入），用 tar over SSH 一次傳進去（跟 scp -r 等價，差別只在 tar 能一次打包、又好控制要不要帶 .git）：

1tar czf - --exclude '.git' . | ssh user@host 'mkdir -p ~/dotfiles && tar xzf - -C ~/dotfiles'

這條只需要兩邊都有的 ssh 跟 tar，不依賴目標機有 rsync。從 macOS 傳的時候要關掉 AppleDouble 中繼檔，否則會夾帶一堆 ._ 開頭的中繼檔到 Linux 上：在指令前加 COPYFILE_DISABLE=1。完全離線、連 SSH 都還沒通時，最後手段是把 repo 放進 USB、掛載到機器上複製出來。

把 dotfile 弄進去之後，跑它的 install.sh 完成基礎安裝。如果安裝腳本一開始就要用 sudo，記得 sudo 必須在工具驗證階段就備好——它是 最小安裝後的工具驗證與補足 的前置，bootstrap 自身補不了。

換一台新機器（或重裝）時，SSH 為什麼突然連不上

SSH 的別名、金鑰、known_hosts 都是綁在「某一台特定機器」上的，所以當你重裝、或換一台新 VM，先前設好的 ssh <別名> 往往會以看似無關的錯誤失敗——那套設定是為舊機器建的，而重裝後是另一台機器：不同的 IP、不同的 SSH host key、還沒裝 sshd、authorized_keys 也是空的。判讀的起點是把重裝後的機器當成全新的一台，重做第一次連線的設定，而不是沿用舊別名。

失敗會以三種形式出現，各對應不同層、各有各的修法：

Permission denied (publickey) 是認證被拒，代表 sshd 有在跑、連線有到（這是進度），卡在金鑰這關。常見於你用的別名設了 IdentitiesOnly yes 只送某一把 key，而新機器的 authorized_keys 還沒有它。修法是改用帳號加 IP 直連、走密碼，繞過那個鎖死金鑰的別名：ssh user@<新 IP>，密碼是「這次安裝」為該使用者設的（每次重裝各自獨立，不是舊機器那個）。連進去後再把公鑰貼回新機器的 authorized_keys、把別名的 HostName 更新成新 IP，免密碼才會恢復。

Host key verification failed（或 REMOTE HOST IDENTIFICATION HAS CHANGED）發生在新機器剛好拿到跟舊機器一樣的 IP 時：你本機 known_hosts 存的是舊機器的 host key，SSH 偵測到同一個 IP 換了 key、當成可能的中間人攻擊而拒連。修法是刪掉那筆舊紀錄，再重連時接受新 key：

1ssh-keygen -R <IP>       # 刪掉該 IP 的舊 host key
2ssh-keygen -R <別名>     # 有用別名的話一併刪

Connection refused 代表沒有 sshd 在監聽，也就是新機器還沒把 SSH server 起來。修法回到最開始——在新機器的 console 裝 openssh、啟動服務（見本篇開頭「啟用 sshd」），這一步在每台全新機器上都要重做。

三個症狀的共同根因是同一件事：SSH 的便利設定（別名、金鑰、host key 快取）綁的是機器身分、不會跟著「重裝」自動轉移。把它們當成「為某一台機器設好的」，換機器就重做第一次連線，能省下對著看似無關的錯誤瞎猜的時間。

連入後可能遇到的兩個終端機問題

SSH 連線本身通了之後，互動 shell 還可能因為終端機環境不對而出現「打字變亂碼、prompt 重繪錯位」。這類問題在你用現代終端機（如 Ghostty、Kitty）連進一台剛裝好的最小 Linux、又跑了 unicode 較重的 prompt（如 Powerlevel10k）時最容易出現，根源是兩個跟字元處理有關的終端機設定，跟你的 shell 配置無關。

第一個是 locale。macOS 的終端機 SSH 連線時常把 LC_CTYPE=UTF-8 送到遠端，但 UTF-8 不是合法的 Linux locale 名稱，Linux 收到後 fallback 成 POSIX/C locale——於是 shell 的行編輯器把輸入當單位元組處理，配上 unicode 字元的 prompt 就重繪成一個字母重複好幾次的累加亂碼。判讀方式是在遠端跑 locale，看 LANG 是不是空的、LC_CTYPE 是不是 POSIX。修法是在 shell 設定裡強制一個合法的 UTF-8 locale（前提是該 locale 已生成，見 安裝選項判讀 的 locale 段）：

1export LANG=en_US.UTF-8
2export LC_CTYPE=en_US.UTF-8

第二個是 terminfo。現代終端機會把 TERM 設成自己的值（Ghostty 是 xterm-ghostty、Kitty 是 xterm-kitty），而一台剛裝好的 Linux 的 terminfo 資料庫沒有這些條目，shell 的行編輯器做「清行重繪」時找不到對應的控制序列、就把畫面畫壞。判讀方式是在遠端 echo $TERM 看是哪個值、toe | grep <值> 看遠端認不認得。修法有兩條：把你終端機的 terminfo 灌進遠端（保留完整功能），或退而求其次強制一個遠端一定有的 TERM：

1# 把本機終端機的 terminfo 灌進遠端的 ~/.terminfo（推薦）
2infocmp -x "$TERM" | ssh remote 'tic -x -'
3
4# 或：連線時強制遠端一定有的 TERM（功能略降，但保證能用）
5ssh -t remote 'TERM=xterm-256color exec zsh -l'

這兩個問題的共同點是：它們在你裝了 unicode 較重的互動 shell 之後才浮現，而陽春的 shell（ASCII prompt）即使 locale 跟 terminfo 都不對也照樣能用。所以排查時，先確認是不是這層、而不是去懷疑剛裝的 shell 配置壞了。

連入、傳輸、安裝的順序

這三件事有一個固定的先後，順序錯了會在中間卡住。先把 sshd 跑起來、從本機連入，取得一個能貼上、可捲動的 session；再把 dotfile 弄進機器（公開 repo 走 HTTPS clone、私有或本地走傳輸）；最後在機器上跑 install.sh 完成安裝。SSH key 是讓「連入」從每次打密碼變成免密碼的優化，可以在任何時候補，不是這條鏈的必要環節、也不是 bootstrap 的前置。

模組零的操作順序指引 把「生成 SSH key、部署公鑰」列為標準流程的一環，那是預設你會建 key 的主路徑。這篇補的是它沒展開的另一面：當你手上還沒有 key、或這台機器的 dotfile 根本不需要 key 就能取得時，怎麼一樣把 bootstrap 跑完。

下一步

連入、傳輸、安裝都跑通之後，真正的考驗是當 install.sh 中途失敗時——而它遲早會撞到失敗——你能不能快速看出哪裡錯了。這取決於安裝腳本有沒有把可觀測性內建進去，可除錯的 bootstrap 談的就是怎麼內建。

可觀測性要事先設計，是因為失敗發生的當下，你能拿到的資訊就已經定型了。如果腳本只把輸出丟到終端機、失敗時只留下一句通用的錯誤，那當下你就只有那句話可看；如果它一路把帶時間戳的紀錄寫進檔案、失敗時主動印出出錯的位置，那同一個失敗就變得可定位。差別不在失敗本身，在失敗前你準備了什麼。如果你寫的是自己的 bootstrap（例如部署 dotfile 的那支 install.sh），這層要在你第一次跑它之前就設計進去，而不是等它出事才回頭加；就算腳本不是你寫的、你只是來 debug 一次失敗，下一段「找程式自己的 log」一樣適用。

為什麼會瞎找

不可觀測的腳本失敗時，你手上只有終端機捲動過的那些輸出，而那往往不足以定位真正的原因。終端機的輸出是易逝的、會被後續輸出沖掉、多個來源的訊息交錯在一起；更麻煩的是，很多失敗的「表面錯誤」離「真正原因」隔了好幾層。一個指令因為前面某個變數是空的而失敗，但它報出來的錯可能完全沒提到那個空變數——你看著一個誤導性的症狀，往上游找不到源頭。

破解這種瞎找的，常常是一份你一開始沒看的 log。很多程式在終端機只印一段摘要，卻同時把詳細的執行紀錄寫進一個 log 檔；當終端機的訊息不足以定位時，那份程式自己寫的 log 裡往往就有答案。除錯時養成「找程式自己的 log，而不是只盯著終端機捲動」的習慣，是把瞎找變成定位的關鍵一步——這也是 模組七日誌判讀 的核心。而對你自己寫的 bootstrap，你可以更進一步：在設計時就讓它產生這樣一份 log。

三個內建可觀測性的手法

讓一支 bootstrap 腳本可診斷，有三個低成本、效果明顯的手法，它們合起來把「失敗了」變成「失敗在第幾行、哪個指令、什麼狀態」。

log 落地：把全部輸出 tee 進帶時間戳的檔案

第一個手法是讓腳本的全部輸出同時進終端機跟一個 log 檔，而不是只進終端機。終端機的捲動是易逝的，log 檔是持久的——可以事後 grep、可以貼給別人看、可以比對前後兩次跑的差異。在 bash 裡，一行 exec 就能把後續所有 stdout 與 stderr 都導去 tee：

1LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles"
2mkdir -p "$LOG_DIR"
3LOG_FILE="$LOG_DIR/install-$(date +%Y%m%d-%H%M%S).log"
4exec > >(tee -a "$LOG_FILE") 2>&1

帶時間戳的檔名讓每次跑各留一份、不互相覆蓋，事後可以回溯「上一次成功跟這次失敗差在哪」。log 檔放在 XDG_STATE_HOME（狀態資料的標準位置）底下，符合慣例、也不污染家目錄。

錯誤定位：用 ERR trap 印出出錯的行與指令

第二個手法是讓腳本在中斷的瞬間，主動報出「是哪一行、哪個指令、什麼結束碼」失敗的。配合 set -e（出錯即停）的腳本，預設只會默默地停，不告訴你停在哪。加一個 ERR trap，就能在 set -e 中斷之前先印出定位資訊：

1set -Eeuo pipefail   # -E 讓 ERR trap 在函式/子 shell 也生效
2trap 'log "ERROR line $LINENO: [$BASH_COMMAND] exit=$?"' ERR

$LINENO 是出錯的行號、$BASH_COMMAND 是當下正在執行的那條指令、$? 是它的結束碼。三者合起來，輸出會長這樣：

1[00:06:51] ERROR line 40: [sudo pacman -S --needed stow git zsh] exit=1

範例裡的 pacman 換發行版會不同，這裡只是示意 trap 輸出的格式——手法本身（行號 + 指令 + 結束碼）跟發行版無關。這一行直接點名元兇。前面提過的那類「表面錯誤離真正原因隔好幾層」的情況——例如某個指令因為 which 不存在而拿到空字串、最後報一個看似無關的錯——有了這行，你會直接看到是哪一行的哪條指令掛了，不必從誤導性的症狀往回猜。set -E（-E 旗標）是為了讓 trap 在函式跟子 shell 裡也照樣觸發，少了它，包在函式裡的錯誤會漏掉。

步驟標記：用帶時間戳的 log 函式標出進度

第三個手法是在關鍵步驟前印一行帶時間戳的標記，讓你能看出腳本跑到哪、哪一步慢。一個極簡的 log 函式就夠：

1log() { printf '[%s] %s\n' "$(date +%H:%M:%S)" "$*"; }
2
3log "install.sh start | OS=$OS"
4log "Installing base packages..."
5log "Stowing configs..."

時間戳的價值在於它同時給你「進度」跟「效能」兩種資訊：失敗時，最後一行成功的 log 告訴你它跨過了哪些步驟、卡在哪一步之後；正常時，相鄰兩行的時間差告訴你哪一步耗時最久。這比沒有標記、只能從一堆套件下載輸出裡猜「現在到底在幹嘛」清楚得多。

失敗可診斷是設計目標

把這三個手法合起來，一支原本「失敗時只留一句通用錯誤」的腳本，會變成「每次跑都留一份完整 log、失敗時直接點名第幾行哪個指令、過程中每步都有時間戳」。成本是腳本開頭多幾行，回報是把未來每一次除錯從瞎找變成定位。這層可觀測性是 模組八 bootstrap script 設計 的延伸——那篇給安裝腳本的骨架與套件清單，這篇給它加上失敗時的診斷能力，兩篇處理的是同一支腳本的兩個層面。

這是設計階段的決定，不是事後能補的。當一支沒有可觀測性的腳本在一台陌生機器上失敗，你沒辦法回到過去讓它記錄當時的狀態——資訊在失敗的瞬間就已經流失了。所以「失敗可診斷」要跟功能一起設計進去，把它當成 bootstrap 的基本屬性，而不是出事之後才想加的補丁。

回到系列

這幾篇合起來，是把一台機器從「空的」帶到「能接收 dotfile、且部署過程可診斷」的完整地基：安裝選項判讀 處理 OS 怎麼裝、工具驗證與補足 處理裝完缺什麼、外部連入與無 key bootstrap 處理怎麼連進去把 dotfile 弄進來，這一篇處理當部署失敗時怎麼快速看出原因。再往前一步，把這套地基用在無人值守的長任務上、讓機器在你離開後自己跑完工作，見 讓機器跑無人值守的長任務——無人盯著的任務尤其依賴這篇談的可觀測性。地基打好，後面 模組一到八 的 dotfile 管理才有立足點。

章節文章

跨分類引用

• → 模組一：管理工具與目錄結構：stow / chezmoi 選型與跨平台三層模型
• → 模組五：Hyprland 配置：環境重建流程裡 monitor 設定的硬體相關調整
• → 模組九：從個人到團隊：個人 bootstrap 的思想怎麼延伸到團隊 onboarding

差異的四個層次

套件管理器：每個平台各有原生解

macOS 用 Homebrew、Arch 用 pacman、Debian/Ubuntu 用 apt、Fedora 用 dnf。安裝指令、確認旗標、資料庫同步模型都不同，其中兩個差異會直接咬到自動化腳本：

• 非互動旗標不對稱：apt 的慣例是 -y，pacman 是 --noconfirm。腳本只寫了其中一邊，換平台就會卡在確認提示——非 TTY 環境下（SSH 一行式、CI、無人值守）沒人回答 [Y/n]，pacman 直接以錯誤結束。
• 資料庫同步模型不同：Arch 是 rolling release 且鏡像不保留舊版檔案，裝機當下的套件資料庫幾天內就會指向已被輪替掉的檔名，安裝時收到 404（failed retrieving file）。修法是安裝前先 pacman -Syu 同步資料庫並全系統升級——只 -Sy 不 -u 會造成 partial upgrade（新資料庫裝新套件、舊系統缺新依賴）。Debian stable 的套件庫凍結、沒有這個時序問題，但代價是版本舊。

套件名稱：同一個工具、各發行版各叫各的

Debian 的重命名還會連執行檔一起改（fdfind、batcat），所以連 shell alias 與腳本內的指令呼叫都要跟著分歧。維護跨發行版清單的可靠做法是逐台實測建立——憑印象抄一份對照表，漂移只是時間問題。

套件存在性：有些概念只存在於特定平台

Hyprland 在 Arch 官方 repo、Fedora 要 COPR、Debian stable 沒有；Quickshell 只有 Arch 打包。反過來，macOS 的 cask app（GUI 應用程式）概念在 Linux 對應的是各桌面環境自己的生態。這層差異沒有翻譯的空間——桌面層的清單是平台專屬的維護對象。

存在性差異還有一個容易漏看的軸：CPU 架構。發行版 repo 有這個工具、不代表它在你的架構上存在——尤其是專有軟體的二進位發行。實測案例：Arch aarch64（ALARM）的 repo 有 spotify-launcher（工具本身有 aarch64 建置），但它要下載的 Spotify 官方 client 只發 x86_64/i386 deb，實跑直接回報 There are no packages for your cpu's architecture (cpu="aarch64", supported=["amd64", "i386"])。這類失敗的判讀重點是分清「工具沒打包」跟「工具打包了、它依賴的專有 blob 沒有這個架構」——前者可能有 AUR / 第三方 repo 補、後者只能找替代路徑（Spotify 的替代是 Web Player + 從 ChromeOS 鏡像抽出的 arm64 Widevine CDM）。DRM、GPU driver、印表機 driver 這類含專有二進位的軟體，在非 x86_64 架構上都要先查架構支援再排進安裝清單。

版本節奏：rolling 與 stable 的行為差

Arch rolling 永遠最新，Debian stable 的同名工具可能舊兩年。版本差會讓 config 語法對不上（新版工具的設定選項在舊版不存在）、也會讓「照著文件做卻失敗」——文件寫的是新版行為。除錯時看到「同一份 config 在 A 機器能跑、B 機器報錯」，先比對兩邊的工具版本再懷疑 config 本身。

除錯前先定平台

跨平台差異對除錯的意義：判讀工具與修法都是平台相依的，先確認自己站在哪，再開始查。 三條指令建立座標：

1cat /etc/os-release        # 發行版與版本（Linux）
2uname -m                   # CPU 架構：x86_64 / aarch64（套件生態差很多）
3command -v pacman apt-get dnf brew   # 哪個套件管理器在場

架構那條容易被忽略：aarch64（ARM）的套件生態比 x86_64 小——Homebrew on Linux 對 aarch64 沒有預編譯 bottle、AUR 部分套件不支援 ARM。在 ARM 機器上照 x86 的教學走，會在意想不到的地方碰壁。

Bootstrap 的分歧設計判準

把差異收進腳本架構的三條判準，決定每段邏輯住在哪：

1. 安裝手段跨平台一致（git clone、curl installer、stow 部署）→ 進共通層，一份邏輯全平台用
2. 只是套件名或套件管理器不同 → 各平台一份安裝腳本 + 一份套件清單，獨立維護、分歧不寫進共通層的 if/else
3. 概念只存在於某平台（Hyprland、cask）→ 只出現在該平台清單的桌面層

這個切法的維護成本結構：共通層改一次全平台生效；平台層只在你真的用那個平台時才付維護成本。沒有實測機器的發行版不預先建清單——那種清單沒有實測支撐、注定漂移。

統一層的誘惑與代價

「用一個跨平台套件管理器統一所有機器」聽起來能消掉整個分歧層，實際的適用邊界很窄。Homebrew 支援 Linux，但它在 Arch 上會建一套與 pacman 平行的套件世界（獨立 prefix、重複的函式庫、PATH 互搶），而且對 aarch64 Linux 沒有 bottle、全部從原始碼編譯。它真正的適用場景是「發行版套件太舊」（如 Ubuntu LTS 上要新版工具）或「沒有 root 權限」。Nix 能做到真正的跨平台一致，代價是整套心智模型重學。判準是：分歧層的維護成本（每個發行版一份清單）低於統一層的引入成本時，保持原生套件管理器 + 分平台清單。

下一步路由

• Bootstrap 腳本本身的設計（log 落地、錯誤定位）見可除錯的 bootstrap
• 最小系統缺什麼、怎麼驗證見最小安裝後的工具驗證與補足
• 出問題時的判讀紀律見 Linux 除錯與診斷
• dotfile repo 怎麼同時服務 macOS 與 Linux 見一個 repo 管理跨平台環境