本文分享兩個重點：

1. 讓 Caps Lock 切換輸入法「立刻生效、沒有延遲」
2. 讓這個設定「開機自動套用」，不用每次重開機都重打指令

一、立即取消 Caps Lock 切換延遲

1. 打開「終端機」（Terminal）

2. 在終端機貼上以下指令並按 Enter：

   hidutil property --set '{"CapsLockDelayOverride":0}'
   

3. 測試 Caps Lock 切換中英文，應該會變得非常即時、沒有慢半拍的感覺。

注意：這個設定在重開機後常常會失效，因此建議再做下面的「開機自動套用」設定。

二、讓 Caps Lock 零延遲在開機時自動套用（LaunchAgent）

這一段會建立一個 LaunchAgent，在你登入 macOS 時自動執行上面的 hidutil 指令。

步驟 1：建立自動啟動的 plist 設定檔

在終端機貼上以下整段指令（包含 EOF 那行），然後按 Enter：

cat > ~/Library/LaunchAgents/com.user.capslockdelay.plist << 'EOF'  
<?xml version="1.0" encoding="UTF-8"?>  
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  
<plist version="1.0">  
<dict>  
  <key>Label</key>  
  <string>com.user.capslockdelay</string>  
  <key>ProgramArguments</key>  
  <array>  
    <string>/usr/bin/hidutil</string>  
    <string>property</string>  
    <string>--set</string>  
    <string>{"CapsLockDelayOverride":0}</string>  
  </array>  
  <key>RunAtLoad</key>  
  <true/>  
</dict>  
</plist>  
EOF

這會在 ~/Library/LaunchAgents/ 底下建立一個 com.user.capslockdelay.plist 設定檔。

步驟 2：載入設定讓它生效

接著在終端機執行：

launchctl load ~/Library/LaunchAgents/com.user.capslockdelay.plist

之後每次登入 macOS，系統就會自動執行 hidutil property --set {"CapsLockDelayOverride":0}，讓 Caps Lock 零延遲自動生效。

檢查檔案是否建立成功

ls ~/Library/LaunchAgents/com.user.capslockdelay.plistl

如果看得到這個檔案路徑，代表設定檔已經建立。

三、如何移除／還原預設設定

如果之後想恢復系統預設（不再自動套用零延遲），可以在終端機執行：

launchctl unload ~/Library/LaunchAgents/com.user.capslockdelay.plist  
rm ~/Library/LaunchAgents/com.user.capslockdelay.plist  

完成後，重開機後就不會再自動修改 Caps Lock 延遲設定。

用 Calibre 管理電子書庫的人大概都經歷過這個流程：匯入一本書，點「下載元資料與封面」，然後看著搜尋結果轉圈圈，最後跳出來的不是空白就是一堆不相關的英文書。

這不是 Calibre 的問題。Calibre 的元資料架構設計得很好，它支援多個來源同時搜尋，讓你挑最完整的那筆。問題在於，內建的來源幾乎都是英文世界的資料庫，找不到繁體中文書。

現有方案為什麼不夠用

目前 Calibre 內建能用的來源大概就這些：

• Google Books — 偶爾能找到中文書，但資料經常殘缺。簡介只有一兩句、標籤沒有、封面模糊，有時候連作者名字都是拼音。

• Goodreads — 繁中書目少得可憐，大部分台灣出版的書根本搜不到。

• Kobo Metadata Plugin — 社群有人開發了一個從 Kobo 抓資料的外掛，設定台灣區之後確實能用。不過它不是每次都能找到資料，覆蓋率有限。

有更多適合台灣讀者的來源，總是一件好事。所以我決定自己動手。

三個外掛，三個台灣電子書平台

我寫了三個 Calibre metadata source plugin，分別對應台灣三個主要電子書平台：

• Readmoo — 台灣最大的繁中電子書平台，書目豐富。能抓到書名、作者、出版社、出版日期、ISBN、標籤、完整簡介、封面。

• HyRead — 圖書館系統常用的電子書平台，學術和一般書籍都有。除了基本欄位之外，它有專門的 ISBN 搜尋功能，精確度很高。也能抓到集叢名（系列）資訊。

• Pubu — 另一個台灣電子書平台，同樣支援系列資訊。如果你的書屬於某個系列，HyRead 和 Pubu 都能幫你自動帶入系列名稱。

三個外掛彼此獨立，可以同時啟用。Calibre 會自動整合所有來源的結果，讓你挑選最完整的那筆。跟既有的 Google Books、Kobo 等來源也不衝突，多裝一個就是多一個機會找到資料。

安裝與使用

安裝很簡單。從 GitHub Release 頁面下載三個 .zip 檔，然後在 Calibre 裡：

偏好設定 → 外掛 → 從檔案載入外掛

三個都裝完之後重啟 Calibre 就好。

使用方式就跟平常一樣：選書、右鍵、下載元資料與封面。你會在來源清單裡看到 Readmoo Books、HyRead Books、Pubu Books 三個新來源。不需要額外設定，裝了就能用。

試試看吧

這三個外掛都開源在 GitHub 上，GPL v3 授權：

https://github.com/chiahsien/calibre-tw-ebook-metadata

Release 頁面有打包好的 .zip 可以直接下載安裝。如果遇到問題或有建議，歡迎開 issue 讓我知道。

我自己用 Obsidian 管理所有筆記，一直想把 KOReader 的 highlight 也整合進來，卻找不到現成的工具。手動複製貼上太慢，寫腳本又要處理 KOReader 那套 Lua 格式的 metadata。

所以我寫了 KOHi，一個 Obsidian plugin，專門解決這件事。

KOHi 做什麼

USB 接上閱讀器，在 Obsidian 裡執行一個指令，就能把 KOReader 的 highlight 和筆記匯入 vault。每本書產生一份 Markdown 筆記，包含書籍資訊和所有標註。

核心功能：

• 自動偵測儲存模式 — KOReader 有三種存放 metadata 的方式（book folder / koreader/docsettings / koreader/hashdocsettings），KOHi 全部支援，不用自己去找檔案在哪裡。
• 模板自訂 — 產生的筆記格式完全可控。用 Nunjucks 模板語法，可以自訂 frontmatter、章節分組、頁碼、highlight 顏色等所有欄位。也提供預設模板，不想自己寫也能直接用。
• 選擇性匯入 — 可以一次匯入全部，也可以用模糊搜尋挑特定幾本書。
• 重複匯入覆蓋 — 重新匯入同一本書時，可以選擇是否要自動覆蓋舊筆記，不會產生重複檔案。

匯入後的筆記長什麼樣

假設你讀了一本書，畫了一些重點，匯入後會產生這樣的 Markdown 筆記：

---
title: "原子習慣"
author: "James Clear"
language: zh
pages: 320
imported: 2026-05-01
---

## 第一章 原子習慣的驚人力量

> 習慣是自我改善的複利。
>
> — p.16

> 如果你每天都能進步百分之一，一年後你會進步三十七倍。
>
> — p.18

> [!note]
> 這跟投資的複利概念一樣，重點不是單次的幅度，而是持續性。

標註按章節分組，包含頁碼，你寫的筆記會以 callout 形式呈現。所有格式都可以透過模板調整。

安裝方式

KOHi 目前還在 Obsidian Community Plugins 的審核中，暫時可以用以下方式安裝。

透過 BRAT（推薦）

BRAT 是一個專門用來安裝尚未上架的 Obsidian plugin 的工具。

1. 在 Obsidian 的 Community Plugins 裡搜尋並安裝 BRAT
2. 進入 BRAT 設定 → Add Beta Plugin → 貼上 chiahsien/obsidian-kohi
3. 回到 Community Plugins 列表，啟用 KOHi

手動安裝

1. 從 GitHub Releases 下載 main.js、manifest.json、styles.css
2. 在 vault 裡建立 .obsidian/plugins/kohi/ 資料夾
3. 把下載的檔案放進去
4. 重啟 Obsidian，在 Community Plugins 裡啟用 KOHi

設定與使用

• 安裝後到 Settings → KOHi，設定幾個必要欄位：

設定完成後，打開 Command Palette，執行：

• KOHi: Import all highlights — 匯入所有書籍的標註
• KOHi: Import selected highlights — 用模糊搜尋選擇特定書籍

筆記會出現在你設定的 output folder 裡。

連結

• GitHub：chiahsien/obsidian-kohi

歡迎試用。有問題或建議可以直接到 GitHub 開 issue，或是在這裡留言。

Swift Package 在多國語言會遇到什麼問題

問題現象

假設你正在開發一個 Swift Package，並且已經正確配置了多語言支援：

let package = Package(
    name: "MyFeatureKit",
    defaultLocalization: "en",
    targets: [
        .target(
            name: "MyFeatureKit",
            resources: [.process("Resources")]
        )
    ]
)

Package 的資料夾結構如下：

MyFeatureKit/
└── Sources/
    └── MyFeatureKit/
        └── Resources/
            ├── en.lproj/Localizable.strings
            ├── es.lproj/Localizable.strings
            ├── ja.lproj/Localizable.strings
            └── de.lproj/Localizable.strings

在 Package 內部測試時，你使用 Bundle.module 來載入本地化字串：

Text("welcome_message", bundle: .module)

一切運作正常。但當你將這個 Package 整合到主 App 中時，日文和德文的本地化突然失效了，系統只會回退到預設的英文。

問題根源

這個問題的核心在於 iOS 系統的本地化載入機制：系統預設只允許 Swift Package 使用主 App Bundle 中明確支援的語言。

換句話說：

• 主 App 透過 .lproj 資料夾或 CFBundleLocalizations 宣告它支援哪些語言
• Swift Package 雖然有自己的 Bundle (Bundle.module) 和本地化資源
• 但在執行時，系統會檢查主 App 支援的語言清單
• 如果 Package 嘗試使用主 App 未宣告支援的語言，該語言會被忽略

這個設計的原意是確保整個應用程式的本地化體驗一致，避免出現部分介面是語言 A，部分介面是語言 B 的混亂情況。然而，這也造成了 Swift Package 無法獨立提供更多語言支援的限制。

CFBundleLocalizations：明確宣告支援的語言

什麼是 CFBundleLocalizations

CFBundleLocalizations 是 Info.plist 中的一個鍵值，用於明確告訴系統你的應用程式支援哪些語言。它的資料型態是字串陣列，每個元素代表一種語言代碼。

解決 Swift Package 本地化問題

假設你的主 App 只有英文和西班牙文的本地化檔案（只有 en.lproj 和 es.lproj），但你的 Swift Package 支援英文、西班牙文、日文和德文。

不加 CFBundleLocalizations 的情況：

• 英文使用者：看到英文（正常）
• 西班牙文使用者：看到西班牙文（正常）
• 日文使用者：看到英文（Package 的日文被忽略）
• 德文使用者：看到英文（Package 的德文被忽略）

加入 CFBundleLocalizations 後：

<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>es</string>
    <string>ja</string>
    <string>de</string>
</array>

現在的結果：

• 英文使用者：看到英文
• 西班牙文使用者：看到西班牙文
• 日文使用者：看到日文（Package 的日文正常載入）
• 德文使用者：看到德文（Package 的德文正常載入）

重要特性與限制

優點：

• 即使主 App 沒有對應的 .lproj 資料夾，只要在 CFBundleLocalizations 中宣告，Swift Package 就能使用該語言
• 實作簡單，只需修改 Info.plist

限制：

• App Store 會顯示你宣告的所有語言為「支援語言」
• 使用者可能會期待整個 App 都支援該語言，但實際上只有 Package 部分支援
• 容易造成使用者體驗不一致：主 App 介面是英文，但 Package 提供的功能是日文

適用情境：

• 你計劃在主 App 中也加入這些語言的支援，只是還沒完成
• 你的 App 結構簡單，大部分內容都在 Package 中
• 你願意接受 App Store 顯示更多支援語言

CFBundleAllowMixedLocalizations：允許混合本地化

什麼是 CFBundleAllowMixedLocalizations

CFBundleAllowMixedLocalizations 是一個布林值設定，用於明確告訴系統：「允許我的依賴項（包括 Swift Package、Framework 等）使用它們自己支援的任何語言，不受主 App 宣告語言的限制。」

解決 Swift Package 本地化問題

使用相同的情境：主 App 只有英文和西班牙文，Swift Package 支援英文、西班牙文、日文和德文。

加入 CFBundleAllowMixedLocalizations 後：

<key>CFBundleAllowMixedLocalizations</key>
<true/>

結果：

• 英文使用者：主 App 顯示英文，Package 顯示英文
• 西班牙文使用者：主 App 顯示西班牙文，Package 顯示西班牙文
• 日文使用者：主 App 顯示英文（或回退到基礎語言），Package 顯示日文
• 德文使用者：主 App 顯示英文（或回退到基礎語言），Package 顯示德文

重要特性與優勢

優點：

• App Store 只顯示主 App 實際支援的語言（英文、西班牙文）
• Swift Package 可以獨立提供更多語言支援
• 使用者不會對整體語言支援有錯誤期待
• 對於只使用特定 Package 功能的使用者，可以獲得更好的本地化體驗

限制：

• 可能造成介面語言不一致（主 App 和 Package 顯示不同語言）
• 需要確保這種混合語言的體驗在 UI/UX 上是可接受的

適用情境：

• 主 App 只支援少數語言，但整合的 Swift Package 提供更豐富的多語言支援
• Package 是功能型模組（如支付、地圖、社交分享），語言不一致不影響整體體驗
• 希望 App Store 只顯示主 App 實際完整支援的語言數量

實際案例：不同語言配置的影響

讓我們用一個具體的案例來說明這兩個設定的實際差異。

案例設定

主 App (Main Bundle)：

• 實際本地化檔案：英文 (en)、西班牙文 (es)、繁體中文 (zh-Hant)
• 有完整的 UI 翻譯、App 名稱本地化等

Swift Package (第三方支付 SDK)：

• 本地化檔案：英文 (en)、西班牙文 (es)、繁體中文 (zh-Hant)、日文 (ja)、德文 (de)
• 包含支付流程的 UI 和訊息

方案一：不做任何設定

Info.plist：

<!-- 空白，不加任何設定 -->

各語言使用者的體驗：

App Store 顯示： 支援 3 種語言

問題： 日文和德文使用者無法使用 Package 內建的本地化，即使 Package 已經準備好這些語言。

方案二：使用 CFBundleLocalizations

Info.plist：

<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>es</string>
    <string>zh-Hant</string>
    <string>ja</string>
    <string>de</string>
</array>

各語言使用者的體驗：

App Store 顯示： 支援 5 種語言

問題：

• 日文和德文使用者在 App Store 看到「支援日文/德文」
• 下載後發現只有支付流程是日文/德文，主 App 介面仍是英文
• 可能造成使用者困惑或負評

方案三：使用 CFBundleAllowMixedLocalizations

Info.plist：

<key>CFBundleAllowMixedLocalizations</key>
<true/>

各語言使用者的體驗：

App Store 顯示： 支援 3 種語言

優勢：

• 日文和德文使用者在 App Store 知道 App 主要支援 3 種語言
• 下載後發現支付流程有日文/德文支援，這是額外的驚喜
• 使用者期待管理更合理

決策指南：何時使用哪一種設定

根據不同的開發情境，選擇合適的設定策略：

特殊情境處理

情境 A：同時使用兩個設定

<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>es</string>
</array>
<key>CFBundleAllowMixedLocalizations</key>
<true/>

結果： CFBundleAllowMixedLocalizations 會覆蓋 CFBundleLocalizations 的限制，Package 可以使用任何它支援的語言。此設定組合通常沒有必要。

情境 B：Package 的 defaultLocalization 與主 App 不同

// Package.swift
let package = Package(
    defaultLocalization: "ja"  // 主 App 的基礎語言是 "en"
)

問題： 當系統找不到合適的語言時，Package 會回退到日文，而主 App 會回退到英文，造成體驗不一致。

解決方案： 確保 Package 的 defaultLocalization 與主 App 的基礎語言（CFBundleDevelopmentRegion）一致。

實作檢查清單

在實作 Swift Package 多語言支援時，使用此檢查清單確保一切配置正確：

Swift Package 端

• Package.swift 中設定了 Package.swift 中設定了 `defaultLocalization`
• 所有語言的資料夾使用正確的命名格式（如 en.lproj、zh-Hans.lproj 所有語言的資料夾使用正確的命名格式（如 `en.lproj`、`zh-Hans.lproj`）
• Localizable.strings `Localizable.strings` 檔案使用 UTF-16 編碼
• 在程式碼中使用 Bundle.module 而非 在程式碼中使用 `Bundle.module` 而非 `Bundle.main`
• 在 Package 內部測試過所有語言的載入

主 App 端

• 決定使用 CFBundleLocalizations 或 決定使用 `CFBundleLocalizations` 或 `CFBundleAllowMixedLocalizations`
• 在 Info.plist 中正確加入選擇的設定
• 如果使用 CFBundleLocalizations 如果使用 `CFBundleLocalizations`，確認所有語言代碼正確
• Package 的 defaultLocalization Package 的 `defaultLocalization` 與主 App 的基礎語言一致
• 在實際裝置上測試各種語言環境

測試驗證

• 切換系統語言，確認 Package 內容正確本地化
• 測試 Package 支援但主 App 不支援的語言
• 檢查 App Store Connect 顯示的支援語言清單是否符合預期
• 確認沒有使用到不存在的語言代碼（會導致回退）

總結

Swift Package 的多語言支援問題源自於 iOS 系統對本地化資源載入的限制機制。理解 CFBundleLocalizations 和 CFBundleAllowMixedLocalizations 的差異，能幫助你根據專案需求做出正確的技術決策：

• CFBundleLocalizations：明確宣告支援的語言，適合計劃完整本地化的情境
• CFBundleAllowMixedLocalizations：允許 Package 獨立提供額外語言，適合大多數整合第三方 Package 的情境

對於多數開發者而言，CFBundleAllowMixedLocalizations 提供了更靈活且使用者友善的解決方案。它讓你能夠誠實地向使用者呈現 App 的實際語言支援情況，同時允許整合的 Swift Package 提供更豐富的多語言體驗。

參考資料

• Apple Developer Documentation - CFBundleLocalizations
• Apple Developer Documentation - CFBundleAllowMixedLocalizations
• Apple Developer Documentation - Localizing Package Resources

當我實作畫面流程時，我會為一組「流程」建立一個 Coordinator。如果這組流程很複雜，它可以拆分成多個「子流程」，那每一個子流程也會有對應的 Sub-Coordinator。主流程的 Coordinator 可以管理子流程的 Sub-Coordinator。

Coordinator 用來管理流程的畫面，它負責建立畫面、傳遞資料給畫面、回應畫面的請求、移除畫面等等。如果用 tree 來理解畫面流程的話，Coordinator 就是 root，各個畫面就是 leaf。換個角度看，Coordinator 像一個容器 — 它自己不產出畫面內容，而是決定裡面放哪些畫面、什麼時候切換。

UIKit

在 UIKit 實作 Coordinator Pattern 的時候，我喜歡使用 UIViewController 作為 Coordinator，並且在裡頭內嵌一個 UINavigationController。

Coordinator 結構

Coordinator 持有 UINavigationController，負責建立畫面、處理事件、決定導航行為：

public final class FeatureCoordinator: UIViewController {
    private let rootNav = UINavigationController()

    public override func viewDidLoad() {
        super.viewDidLoad()

        addChild(rootNav)
        rootNav.view.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(rootNav.view)
        NSLayoutConstraint.activate([
            rootNav.view.topAnchor.constraint(equalTo: view.topAnchor),
            rootNav.view.bottomAnchor.constraint(equalTo: view.bottomAnchor),
            rootNav.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            rootNav.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
        ])
        rootNav.didMove(toParent: self)

        showHome()
    }

    private func showHome() {
        let homeVC = HomeViewController()
        homeVC.delegate = self
        rootNav.pushViewController(homeVC, animated: false)
    }

    private func showDetail(item: String) {
        let detailVC = DetailViewController(item: item)
        detailVC.delegate = self
        rootNav.pushViewController(detailVC, animated: true)
    }

    private func showSettings() {
        let settingsVC = SettingsViewController()
        settingsVC.delegate = self
        rootNav.pushViewController(settingsVC, animated: true)
    }
}

// MARK: - Event Handlers

extension FeatureCoordinator: HomeViewControllerDelegate {
    func homeViewController(
        _ vc: HomeViewController,
        didSelectItem item: String
    ) {
        showDetail(item: item)
    }

    func homeViewControllerDidTapSettings(
        _ vc: HomeViewController
    ) {
        showSettings()
    }
}

extension FeatureCoordinator: DetailViewControllerDelegate {
    func detailViewController(
        _ vc: DetailViewController,
        didSelectRelatedItem item: String
    ) {
        showDetail(item: item)
    }

    func detailViewControllerDidFinish(
        _ vc: DetailViewController
    ) {
        rootNav.popViewController(animated: true)
    }
}

extension FeatureCoordinator: SettingsViewControllerDelegate {
    func settingsViewControllerDidLogOut(
        _ vc: SettingsViewController
    ) {
        rootNav.popToRootViewController(animated: true)
    }
}

畫面與 Coordinator 的溝通：偏好 Delegate

畫面透過 delegate 與 Coordinator 溝通。我偏好 delegate 而非 closure，因為：

• Contract 明確：protocol 就是溝通介面的完整定義，一眼就能看出畫面會發出哪些事件
• 不容易漏：Xcode 會強制你實作每個 protocol method，不會忘記處理某個事件
• 可讀性：當畫面有多種事件需要回傳時，closure 會變成一堆散落的 property，delegate 則集中在一個 protocol 裡

Closure 適合一次性、單一事件的回傳（例如 completion block），但在 Coordinator pattern 中，畫面通常有多種事件需要通知 Coordinator，delegate 更合適。

// MARK: - View Delegate Protocols

protocol HomeViewControllerDelegate: AnyObject {
    func homeViewController(
        _ vc: HomeViewController,
        didSelectItem item: String
    )
    func homeViewControllerDidTapSettings(
        _ vc: HomeViewController
    )
}

protocol DetailViewControllerDelegate: AnyObject {
    func detailViewController(
        _ vc: DetailViewController,
        didSelectRelatedItem item: String
    )
    func detailViewControllerDidFinish(
        _ vc: DetailViewController
    )
}

protocol SettingsViewControllerDelegate: AnyObject {
    func settingsViewControllerDidLogOut(
        _ vc: SettingsViewController
    )
}

子流程管理與反向溝通

既然 Coordinator 是 UIViewController，子流程的管理就是標準的 UIKit parent-child 關係。呈現子流程用 present，子流程結束後透過 delegate 把結果傳回 parent Coordinator — 溝通方式與畫面 → Coordinator 一致，整個架構的溝通模型是統一的。

// MARK: - Sub-Coordinator Management

protocol SubFeatureCoordinatorDelegate: AnyObject {
    func subFeatureCoordinator(
        _ coordinator: SubFeatureCoordinator,
        didFinishWith result: SubFeatureResult
    )
}

// In parent FeatureCoordinator:
extension FeatureCoordinator {
    func showSubFeature() {
        let subCoordinator = SubFeatureCoordinator()
        subCoordinator.delegate = self
        present(subCoordinator, animated: true)
    }
}

extension FeatureCoordinator: SubFeatureCoordinatorDelegate {
    func subFeatureCoordinator(
        _ coordinator: SubFeatureCoordinator,
        didFinishWith result: SubFeatureResult
    ) {
        coordinator.dismiss(animated: true)
        // Handle result from sub-flow
    }
}

這正好是 UIViewController-based Coordinator 相較 protocol-based 做法的優勢：你不需要手動從 childCoordinators 陣列移除子 Coordinator，dismiss 就是一切。Sub-Coordinator 如果有需要清理的資源，應該在自己的 deinit 處理 — Coordinator 是 self-contained 的，不該讓 parent 操心內部清理。

SwiftUI

在 SwiftUI 實作 Coordinator Pattern 的時候，對應 UIKit 版的「Coordinator = UIViewController」，我使用 SwiftUI View 作為 Coordinator，讓它擁有 NavigationStack 和 @State 導航狀態。

Coordinator 結構

Coordinator View 持有 NavigationStack 的 path 和 sheet 狀態，負責建立畫面、處理事件、決定導航行為：

struct FeatureCoordinatorView: View {
    enum Route: Hashable {
        case home
        case detail(String)
        case settings
    }

    @State private var path: [Route] = []
    @State private var sheetRoute: Route?

    var body: some View {
        NavigationStack(path: $path) {
            HomeView(onEvent: handleHomeEvent)
                .navigationDestination(for: Route.self) { route in
                    view(for: route)
                }
        }
        .sheet(item: $sheetRoute) { route in
            NavigationStack {
                view(for: route)
            }
        }
    }

    @ViewBuilder
    private func view(for route: Route) -> some View {
        switch route {
        case .home:
            HomeView(onEvent: handleHomeEvent)
        case .detail(let item):
            DetailView(item: item, onEvent: handleDetailEvent)
        case .settings:
            SettingsView(onEvent: handleSettingsEvent)
        }
    }

    // MARK: - Event Handlers

    private func handleHomeEvent(_ event: HomeView.Event) {
        switch event {
        case .didSelectItem(let item):
            path.append(.detail(item))
        case .didTapSettings:
            path.append(.settings)
        }
    }

    private func handleDetailEvent(_ event: DetailView.Event) {
        switch event {
        case .didSelectRelatedItem(let item):
            path.append(.detail(item))
        case .didFinish:
            if !path.isEmpty { path.removeLast() }
        }
    }

    private func handleSettingsEvent(_ event: SettingsView.Event) {
        switch event {
        case .didLogOut:
            path.removeAll()
        }
    }
}

畫面與 Coordinator 的溝通：Event Enum + Closure

UIKit 版偏好 delegate，SwiftUI 版則改用每個 View 自己定義的 Event enum 搭配 onEvent closure。精神是一樣的 — contract 明確、不容易漏。

具體做法：

• 每個 View 內部宣告自己的 Event enum，列出這個 View 會發出的所有事件
• Coordinator 建立 View 時必須提供 (Event) -> Void，漏了就 compile error
• Handler 裡 switch 這個 concrete enum，Swift 會強制處理每個 case — 不會有 default fallback 的漏洞

命名用 Event 而非 NavigationEvent，因為不是每個事件都跟導航有關。更重要的是，Event 的 case 應該描述發生了什麼事，而非指揮 Coordinator 該做什麼導航 — 讓 View 保持 context-independent。

struct DetailView: View {
    enum Event {
        case didSelectRelatedItem(String)
        case didFinish(DetailResult)
    }

    let item: String
    let onEvent: (Event) -> Void

    var body: some View {
        VStack {
            Text("詳情: \(item)")

            Button("完成") {
                onEvent(.didFinish(.success))
            }
        }
    }
}

子流程管理與反向溝通

與 UIKit 版一樣，子流程用獨立的 Coordinator View 實作，透過 .sheet 或 .fullScreenCover 呈現。子流程完成後透過 onEvent closure 把結果傳回 parent Coordinator — 溝通方式與畫面 → Coordinator 一致。

struct FeatureCoordinatorView: View {
    // ...
    @State private var isShowingSubFeature = false

    var body: some View {
        NavigationStack(path: $path) {
            // ...
        }
        .sheet(isPresented: $isShowingSubFeature) {
            SubFeatureCoordinatorView(
                onEvent: handleSubFeatureEvent
            )
        }
    }

    private func handleSubFeatureEvent(
        _ event: SubFeatureCoordinatorView.Event
    ) {
        switch event {
        case .didFinish(let result):
            isShowingSubFeature = false
            // Handle result from sub-flow
        }
    }
}

// Sub-Coordinator 也是一個 View，擁有自己的 NavigationStack
struct SubFeatureCoordinatorView: View {
    enum Event {
        case didFinish(SubFeatureResult)
    }

    let onEvent: (Event) -> Void

    @State private var path: [SubRoute] = []

    var body: some View {
        NavigationStack(path: $path) {
            // Sub-flow's root view
            // ...
        }
    }
}

Q&A

一定要整個 app 都用 Coordinator 嗎？

不用。Coordinator 可以作為 app 的 root 直接使用，也可以在開發新功能時局部導入 — 為某個功能建立 Coordinator 不需要改動既有架構，侵入性很低。

為什麼選 UIViewController 而不是社群常見的 Protocol-based Coordinator？

社群主流的 Coordinator pattern（如 Soroush Khanlou 原版）是用 Coordinator protocol 搭配 childCoordinators 陣列來管理子流程。我選擇直接用 UIViewController 作為 Coordinator，理由如下：

• 少一層抽象：Coordinator 的 lifecycle 直接跟 UIKit 綁定，不需要自己維護 start() / stop() 等生命週期方法
• 不需要手動管理 childCoordinators 陣列：UIKit 的 children（child view controller）已經替你做了這件事，少一個容易遺漏的 bookkeeping
• present / dismiss 不需要額外 wiring：因為 Coordinator 本身就是 UIViewController，所以呈現子流程就是標準的 present(_:animated:)，結束就是 dismiss，不需要額外的 routing 邏輯

為什麼不定義一個所有 Coordinator 都 conform 的 protocol？

我刻意不定義一個所有 Coordinator 都要 conform 的 CoordinatorProtocol。Coordinator 是一個概念，不是一個介面。

每個流程的需求不同 — 有的要處理 deep link，有的不用；有的有子流程，有的只有兩個畫面。硬定義一個共用 protocol（start()、childCoordinators、router 等）反而綁手綁腳，逼你為了滿足 protocol 而寫不需要的東西。

依需求開發每一個 Coordinator，比套一個 protocol 更實際。

這樣做對畫面復用有什麼幫助？

Coordinator 全權管理導航，帶來一個實務上很重要的好處：畫面不需要知道自己被放在什麼容器裡。

畫面不用管自己是被 push 進 NavigationStack、用 sheet 呈現、還是當 tab 的 root — 它只負責顯示內容、發出事件。導航相關的 UI（back button、close button、toolbar action、tab item）全部由 Coordinator 或容器決定，畫面本身不碰。

主要的例外是 title：畫面可以自己聲明標題。在 UIKit 中是 self.title，在 SwiftUI 中是 .navigationTitle — 兩者的性質一樣，都是「我叫什麼名字」，不是「我要怎麼被導航」。至於標題最終怎麼呈現，是容器的事。

這讓同一個畫面可以在不同情境直接復用，不用為了換容器而改畫面的程式碼。

UIKit 用 delegate、SwiftUI 用 closure，為什麼不統一？

兩個框架選擇不同溝通方式，是因為架構特性不同：

• UIKit 用 delegate：ViewController 是 reference type（class），closure capture self 容易造成 retain cycle，每個地方都要寫 [weak self]。Delegate 用 weak 一次解決，而且整個 UIKit 框架本身就大量使用 delegate（UITableViewDelegate、UITextFieldDelegate 等），風格一致
• SwiftUI 用 closure：View 是 value type（struct），沒有 retain cycle 的問題。SwiftUI 框架本身就是 closure 慣例 — Button(action:)、.onTapGesture {}、.task {} 全部都是 closure，用 delegate 反而格格不入。而且 View struct 會被頻繁重建，delegate 這種需要 assign reference 的模式不適合這個生命週期

不是 closure 或 delegate 誰絕對更好，而是跟著框架的慣例和型別系統走。

Coordinator 要負責 dependency injection 嗎？

Coordinator 負責管理流程，不負責規定 dependency 怎麼到達畫面。Coordinator 建立畫面時注入 dependency、畫面自己從 DI container 取得、或透過 SwiftUI 的 environment 傳遞，都可以 — 視專案的 DI 策略決定。

Deep link 怎麼跟 Coordinator 整合？

收到 deep link 時，Coordinator 如果知道怎麼處理就直接顯示對應畫面；如果不知道，就詢問它能建立的 Sub-Coordinator — 每個 Sub-Coordinator 提供一個 static method 來回答自己能不能處理這個 deep link。Parent Coordinator 找到能處理的 Sub-Coordinator 後，建立並呈現它。這個 resolve 過程沿著 tree 從 root 往 leaf 遞迴，跟 Coordinator 管理畫面的結構一致。

我的解決方案

將 project.pbxproj 中的各個區塊按固定規則排序，確保相同內容產生相同的檔案結構。配合 git pre-commit hook，每次提交前自動排序，團隊成員的專案檔就能維持一致的順序，大幅降低無意義的衝突。

我開發了一個腳本工具來執行這個任務，也已經在多個專案上跑了好幾年，GitHub repo 放在這裡：https://github.com/chiahsien/sort-Xcode-project-file

雖然目前推崇使用 Swift Package Manager 進行模組化，Xcode 16 也引入了 buildable folders 功能來減少專案檔變更，甚至也有 Tuist 或 Xcode Gen 這類的工具來生成專案檔，但這些新技術主要針對新專案或願意大幅重構的專案。對於已經開發多年、結構複雜的舊專案，貿然改用 SPM 模組化或轉換成 folder references 風險過高。此時，這個排序工具仍是最務實的選擇，能以最小成本解決 merge conflict 問題。

排序範圍

此工具排序以下 array 結構：

• children — group 內的檔案與 subgroup（目錄排在檔案前面）
• files — build phase 的檔案列表
• buildConfigurations — build configuration 列表
• targets — 專案 target 列表
• packageProductDependencies — Swift Package product dependency
• packageReferences — Swift Package reference

安全性

這些 array 是宣告性內容，Xcode 透過 24 字元的十六進位 ID 參照物件，而非依賴位置。排序不影響建置行為或專案結構，僅改變檔案內的呈現順序。

不排序的區塊：PBXFrameworksBuildPhase section 的 framework 連結順序會影響符號解析，工具會偵測到這個區塊並完整保留原始順序。其餘不在上述排序範圍內的 array（例如 buildPhases）則不會被處理，同樣維持原始順序。

寫入方式採用原子操作（透過暫存檔 + os.replace()），即使過程中發生錯誤，也不會留下損壞的 .pbxproj 檔案。

警告：
雖然這個工具已經在多個不同專案執行很長一段時間了，我還是強烈建議在修改之前先做好備份，才不會出現難以挽回的錯誤！

與原版的差異

本版本是 WebKit 專案的 fork，以 Python 3 重寫並新增以下功能：

• Natural sorting：數字部分按數值比較，file2.m 排在 file10.m 前面，符合人類直覺
• Case-insensitive 選項：提供 --case-insensitive 參數支援不分大小寫排序，預設仍為 case-sensitive 以保持原始行為
• 目錄優先排序：children array 中目錄排在檔案前面，符合檔案系統慣例
• 自動去除重複：移除重複的項目 reference
• 擴充排序範圍：包含所有 children array、files array、targets 列表、packageProductDependencies 與 packageReferences
• CI 檢查模式：--check 參數可檢查檔案是否已排序，不修改檔案，適合整合到 CI pipeline
• 遞迴搜尋：-r 參數可遞迴搜尋目錄下所有 project.pbxproj 並排序，適合 monorepo
• Stdin/stdout 支援：使用 - 參數可從 stdin 讀取、寫到 stdout，方便管線操作
• 原子寫入：透過暫存檔 + os.replace() 確保寫入過程不會損壞原始檔案

使用方法

基本呼叫

python3 sort-Xcode-project-file.py path/to/Project.xcodeproj

腳本會自動找到 project.pbxproj 並就地排序。也可以直接指定 project.pbxproj 檔案路徑。

選項

# 使用 case-insensitive sorting
python3 sort-Xcode-project-file.py --case-insensitive Project.xcodeproj

# CI 檢查模式：exit 0 = 已排序，exit 1 = 未排序（不修改檔案）
python3 sort-Xcode-project-file.py --check Project.xcodeproj

# 遞迴搜尋目錄下所有 project.pbxproj 並排序
python3 sort-Xcode-project-file.py -r .

# 從 stdin 讀取，寫到 stdout
cat project.pbxproj | python3 sort-Xcode-project-file.py - > sorted.pbxproj

# 抑制 warning 訊息
python3 sort-Xcode-project-file.py -w Project.xcodeproj

# 顯示版本號
python3 sort-Xcode-project-file.py --version

# 顯示說明
python3 sort-Xcode-project-file.py --help

Git Pre-commit Hook 整合

在專案根目錄建立 Scripts 目錄，將 sort-Xcode-project-file.py 放進去，然後建立 .git/hooks/pre-commit：

#!/bin/sh

echo 'Sorting Xcode project files'

GIT_ROOT=$(git rev-parse --show-toplevel)
sorter="$GIT_ROOT/Scripts/sort-Xcode-project-file.py"

git diff --name-only --cached | grep "project.pbxproj" | while IFS= read -r filePath; do
  fullFilePath="$GIT_ROOT/$filePath"
  python3 "$sorter" "$fullFilePath"
  git add "$fullFilePath"
done

echo 'Done sorting Xcode project files'

記得設定執行權限：

chmod +x .git/hooks/pre-commit

另外可以在 .gitattributes 加上以下設定，進一步減少合併衝突：

*.pbxproj merge=union

注意： merge=union 會讓 Git 自動保留衝突的雙方內容。搭配排序工具使用效果很好，但如果專案檔沒有經過排序，可能會產生無效的結果。請確保團隊成員都有使用這個排序工具。

下載路徑：https://github.com/chiahsien/KOReader.Patches

重點摘要

• 功能：資料夾顯示自訂或來源於書籍的封面；支援單一封面與 2×2 格狀兩種風格；遞迴搜尋子資料夾。
• 來源：修改自 sebdelsol/KOReader.patches 的 2-browser-folder-cover.lua，新增格狀封面、遞迴搜尋、.cover 支援、非同步載入、e-ink 閃爍消除、LRU 快取與 UI 選項。

為什麼會需要這個 patch

KOReader 的 Mosaic 檢視本身會以書籍封面作為格子顯示；但資料夾通常只會顯示資料夾名稱或預設圖示。這個 patch 補強了資料夾的視覺表現，讓資料夾也能像書籍一樣顯示代表性的封面，改進瀏覽體驗，特別適合把資料夾當作書櫃或系列集合來管理的使用者。

主要功能

• 支援自訂封面檔案：將自訂圖片放在資料夾內，檔名前綴為 .cover 並附上副檔名（範例：.cover.jpg、.cover.png、.cover.webp）。
• 兩種封面風格：
  • Single cover（單一封面）：每個資料夾顯示一張書籍封面，底部對齊。
  • Grid (2×2)（格狀封面）：最多顯示四張書籍封面以 2×2 格狀排列，每格使用 aspect fill（裁切溢出以填滿格子）。支援不完整的格狀排列：2 張填滿上排、3 張多填左下角。只找到 1 張時自動退回單一封面顯示。
• 自動從書籍封面取代：若沒有 .cover，會在資料夾內尋找有效的書籍封面並使用。
• 遞迴搜尋子資料夾：若資料夾本身沒有可用封面，會往下搜尋子資料夾（預設深度 3）以找到合適的書籍封面。
• 非同步封面載入：當書籍封面尚未被 KOReader 擷取時，資料夾格子會在封面就緒後自動重新整理，不需手動操作。
• e-ink 閃爍消除：資料夾跳過預設的 original_update() 流程，避免先畫預設圖示再替換封面所產生的 e-ink 閃爍。
• 性能優化：Per-directory LRU widget 快取（最多保留 10 個目錄）與封面來源快取，避免重複掃描目錄；settings version 追蹤機制，只在設定變更時才清除快取。

封面搜尋順序

Patch 依以下優先順序決定資料夾封面：

1. 自訂 .cover 檔案：檢查資料夾內是否有 .cover.{jpg,jpeg,png,webp,gif}。找到即直接使用，不論目前選擇的封面風格為何，自訂封面一律以單一封面方式顯示。
2. 封面來源快取：若該資料夾先前已解析過書籍封面路徑，直接重用，跳過目錄掃描。
3. 掃描資料夾內的書籍：呼叫 BookInfoManager:getBookInfo() 逐一檢查檔案，收集有效封面（grid 模式最多 4 張、single 模式 1 張）。
4. 遞迴搜尋子資料夾：若仍需更多封面，往下遞迴搜尋子資料夾（最多深度 3）以尋找額外的書籍封面。

若封面仍在背景擷取中，資料夾格子會註冊到 CoverBrowser 的 polling 機制，待封面就緒後自動重試。

與上游（原作者）差異

此版本基於 sebdelsol/KOReader.patches 的實作，但做了下列主要改動：

• 新增 2×2 格狀封面模式（Grid mode），支援不完整排列。
• 新增對自訂 .cover 檔案的偵測與使用。
• 新增遞迴搜尋子資料夾以尋找書籍封面（避免空資料夾顯示預設圖示）。
• 新增非同步封面載入，封面未就緒時自動重試。
• 消除 e-ink 閃爍：資料夾直接設定封面，不再先畫預設圖示。
• 改用 Per-directory LRU widget 快取（最多 10 個目錄）與封面來源快取，大幅降低 UI 建構成本。
• 尊重 KOReader 既有的封面快取有效性檢查，避免使用過期封面。

安裝與使用

1. 將 2-browser-folder-cover.lua 複製到 KOReader 的 patches 資料夾（通常位於 <koreader_data_dir>/patches/）。常見路徑：

   • Kobo: /mnt/onboard/.adds/koreader/patches/
   • Kindle: /mnt/us/documents/koreader/patches/
   • Android: /sdcard/koreader/patches/
   • Desktop: ~/.koreader/patches/

2. 重新啟動 KOReader，patch 會在啟動時自動載入。

3. 使用方法：

   • 若要使用自訂封面，於資料夾放入檔名為 .cover 並含有副檔名的圖片檔（例如 .cover.jpg）。
   • 若未放 .cover，patch 會先檢查該資料夾內的書籍封面，找不到時再往子資料夾遞迴搜尋（最多 3 層）。
   • 可於 KOReader 設定中找到新增的選項（File browser settings → Mosaic and detailed list settings）：
     • Folder cover style：子選單，可選擇 "Single cover"（預設）或 "Grid (2×2)"。
     • Crop folder custom image（裁切自訂封面，預設啟用）
     • Show folder name（顯示資料夾名稱，預設啟用）

注意事項與建議

• .cover 的優先度高於書籍封面：一旦發現 .cover，patch 會直接使用該圖片並略過書籍封面搜尋。自訂封面一律以單一封面顯示，不受封面風格設定影響。
• 若資料夾或子資料夾包含大量檔案或深度很深，遞迴搜尋可能帶來額外的檔案系統存取成本，建議將預設深度（目前程式內使用 3）視情況調整或僅在目標目錄使用 .cover。
• 若發現封面顯示不正常，請先檢查 BookInfoManager 是否已正確擷取並快取了該書的封面，或在 KOReader 中重建封面快取。

授權與來源

此 patch 為我自行維護的衍生版本，原始實作與靈感來自：

• sebdelsol/KOReader.patches

若想回到上游版本或查看原始程式碼，可參考上面連結。

以我最近在做的功能為例，它是一個完整的獨立模組 - 有多個頁面、支援多國語言、使用圖片與動畫資源。為了避免日後整合時出現命名衝突、相依過重或編譯過慢的問題，我選擇把它獨立成一個 Swift Package。在將 feature 抽出到 Package 的過程我也踩到了一些坑，趁著這個機會記錄下來，以免日後忘記。

為什麼要把 Feature 打包成 Swift Package？

建立專屬的 Swift Package 有幾個明顯的好處：

• ✅ 可獨立開發與測試：模組化後不必依賴主專案，可單獨編譯與驗證。
• ⚙️ 降低相依與衝突：減少命名重複、依賴鏈過長等問題。
• 🚀 加快編譯速度：主專案不需每次都重新編譯整個功能。
• 🔄 方便整合與重用：未來可以直接被其他 app 或團隊使用。

問題一：如何支援多國語言？

若要在 Package 內使用多國語言，有兩件事情一定要搞清楚：

1. 檔案結構要正確放置。
2. 讀取時要明確指定 .module。

正確的資料夾結構

根據 Apple 官方文件，多國語言檔（.lproj）必須直接放在 Resources 資料夾底下，不能再有子目錄。正確的結構如下：

MyPackage/
├─ Sources/
│  └─ MyLibrary/
│     └─ Resources/
│        ├─ en.lproj/
│        │  └─ Localizable.strings
│        ├─ zh-Hant.lproj/
│        │  └─ Localizable.strings
│        └─ Strings.dict

這樣做可以確保 .lproj 檔會被正確地讀取與載入。若放錯層級，Xcode 雖然不會報錯，但翻譯字串就是不會出現。

正確的呼叫方式

在 Package 內呼叫多國語言字串時，別忘了指定 bundle: .module。否則 Swift 會自動去主專案尋找對應字串，導致載不到 Package 內的翻譯。

extension String {
    var localized: String {
        NSLocalizedString(
            self,
            tableName: "Localizable",
            bundle: .module,    // 關鍵：指定為 package 的 bundle
            value: self,
            comment: ""
        )
    }
}

使用時只要 "Some.Localized.String.Key".localized 就能正確取回包內的翻譯字串。這樣做讓 package 在任何專案中都能獨立運作，無需依賴主專案的語言設定。

問題二：如何使用圖片與動畫資源？

圖片與多國語言的處理方式類似，同樣要注意資料夾結構與載入方式。

圖片資源結構

官方建議將圖片檔（.xcassets）放在 Resources 目錄底下。若你使用像 Lottie 這類第三方函式庫，也可以把相關 JSON 資源放在同個目錄。

MyPackage/
├─ Sources/
│  └─ MyLibrary/
│     └─ Resources/
│        ├─ Images.xcassets/
│        │  ├─ Avatar.imageset/
│        │  ├─ Error.imageset/
│        │  └─ ...
│        └─ Lottie/
│           ├─ greeting.json
│           └─ ...

呼叫圖片的方式

有兩種常見方式可以載入圖片：

1. UIImage(resource: .xxx)
2. UIImage(named: "xxx", in: .module, with: nil)

而如果你使用 Lottie 動畫，則要記得加上 bundle：

LottieAnimationView(name: "greeting", bundle: .module)

這樣才能確保動畫資源來自 package，而不是主專案。

問題三：Package.swift 要怎麼設定？

最後一步，就是在 Package.swift 中設定好本地化與資源處理。這一步如果漏掉，前面做的一切可能都不會生效。

let package = Package(
    name: "MyLibrary",
    defaultLocalization: "en",  // 一定要設定預設語言
    platforms: [
        .iOS(.v16)
    ],
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]
        ),
    ],
    dependencies: [
        .package(url: "https://github.com/airbnb/lottie-spm.git", from: "4.5.2"),
    ],
    targets: [
        .target(
            name: "MyLibrary",
            dependencies: [
                .product(name: "Lottie", package: "lottie-spm"),
            ],
            resources: [
                .process("Resources")  // 使用 .process 讓 Xcode 處理資源檔
            ]
        ),
    ]
)

這裡的兩個重點是：

• defaultLocalization：沒有這行，多國語言會無法自動套用。
• .process("Resources")：讓 Xcode 知道要把資源包含進 target。

結語：讓 Feature 真正成為可重用的模組

當一個功能變得越來越複雜時，把它獨立成 Swift Package 不只是整潔問題，更是 架構與維護性的升級。

模組化能讓你：

• 更容易進行單元測試；
• 快速重用或移植到新專案；
• 明確定義每個功能的邊界與責任。

只要依照上面的步驟設定語言與資源，就能建立一個乾淨、可移植、可重用的 Feature Package。當你下一次打開 Xcode 時，或許就會開始想：「這個功能，其實也該是一個獨立的 package 吧？」

01. 系統地基 (System Foundation)

拿到新電腦的第一步，先把終端機與套件管理搞定，這是所有開發工作的基礎。

套件管理：Homebrew

Homebrew 是 macOS 必備的套件管理工具。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Silicon (M1/M2/M3...) 設定注意：

安裝完成後，為了讓系統能正確找到 brew 指令，建議將環境變數設定寫入 ~/.zprofile（而非 .zshrc），這樣能避免每次開新分頁都重複執行，提升效能：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

終端機與 Shell

• Terminal App
  • 我改用 Ghostty（推薦，已推出正式版）或 iTerm2 取代內建終端機。
  • 如果需要更強大的功能，可以試試 Tabby，它跨平台且支援 SSH / Serial / Telnet 連線。
  • Tip: Ghostty 雖然強調開箱即用，還是可以透過修改設定檔自訂。有人建立了 這個網站 方便使用者調整設定。
• Shell
  • Oh My Zsh：讓 Zsh 更好用、更漂亮的必裝框架。

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

如果安裝了 Oh My Zsh 又想要自動補完 brew 的指令，記得在 ~/.zprofile 加入：

FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}"

版本控制核心：Git

Git 是版本控制的靈魂。

brew install git
brew install git-lfs

02. 開發與語言環境 (Coding Environment)

編輯器與 IDE

• Visual Studio Code：我的首選編輯器，理由是「速度快」、「界面友好」、「套件生態系豐富」。必備套件可參考 這篇文章。
• Xcode：iOS/macOS 開發必備。
  • 推薦使用 Xcodes 來管理多版本 Xcode，詳情參考 這篇文章。
  • 定期使用 DevCleaner 清理肥大的暫存檔。
  • 搭配 Github Copilot for Xcode 輔助開發。
• Zed：使用 Rust 開發的高效能編輯器，速度極快且內建 AI 支援，適合追求極致效能或需要開啟大檔案的人。
• Sublime Text：以前用過，真的很快，但因介面不夠友善懶得折騰而放棄。
• Typora：Markdown 編輯器首選，所見即所得的體驗與佈景主題讓我離不開它。
  • 輕量替代品：妙言，簡單輕巧是它的特色。

語言執行環境 (Runtimes)

以 Ruby 為例，我使用 rbenv 來管理版本：

brew install rbenv ruby-build

接著安裝常用的 Ruby 版本並設為全域預設：

rbenv install 3.2.2 # 請依當下最新穩定版調整
rbenv rehash
rbenv global 3.2.2

最後記得在 ~/.zshrc 加入初始化設定：

eval "$(rbenv init - zsh)"

(如果安裝過程遇到 permission denied，可嘗試 sudo chown -R "$(whoami)":admin /usr/local/var 修復)

03. 開發輔助工具 (Development Tools)

Git GUI 客戶端

Git 指令雖然強大，但在檢視複雜的線圖或做部分 commit 時，GUI 工具還是比較直覺。

• Fork：目前的主力，介面非常友善且操作流暢。
• 其他選擇：
  • SourceTree
  • Tower
  • SmartGit
  • GitKraken

API 與網路除錯

• Bruno：管理與呼叫 API 的工具。
• Dash：強大的離線 API 文件瀏覽器與程式碼片段管理工具。
• Proxyman：介面漂亮的抓包工具，用來檢查與修改 HTTP/HTTPS 請求。

UI 檢測

• Lookin (免費)：若 Xcode 內建工具不夠用時的進階選擇。
• 其他付費選擇：Reveal 或 Sherlock。

04. 生產力與系統增強 (Productivity & Utilities)

這區塊收錄了讓 Mac 更順手的小工具，依照功能分類：

滑鼠增強

• Better Mouse：我不喜歡安裝肥大的驅動程式，這是更流暢、功能強大的輕量化替代品。
• logi-options-plus-mini：如果你依然必須使用羅技官方驅動 (Logi Options+)，建議使用這個工具進行最小化安裝，去除不必要的臃腫功能。

視窗與檔案管理

• 視窗管理：
  • 用 Magnet 或 Rectangle (免費) 進行視窗分割。
  • 用 AltTab 或 HyperSwitch 將 Windows 的視窗切換邏輯帶回 Mac。
  • Tip: 如果你有安裝 Raycast，它的 Window Management extension 也能完美處理視窗分割的需求。
• Finder 增強：
  • Open In Terminal：在 Finder 快速開啟終端機。
  • QLMarkdown：按空白鍵預覽 Markdown 文件。
  • Syntax Highlight：按空白鍵預覽帶有高亮色彩的原始碼。
  • ForkLift 3：雙視窗檔案管理 + FTP 傳輸工具。
  • QSpace：功能單純的多面板 Finder。
• 解壓縮：
  • The Unarchiver 或 Keka。
  • 如果不介意 command line，也可考慮 WinRAR for Mac。

知識管理 (PKM)

• 筆記軟體：Logseq 與 Obsidian，無論在家或公司都用它們整理思緒。
• 心智圖：XMind，用於紀錄發散性或階層性的想法（雖然稍嫌笨重）。

系統優化與小工具

• 啟動器：
  • Raycast：我的首選，自訂性高。
  • Alfred：也是很棒的替代品。
• 防休眠：
  • Amphetamine：長時間跑程式或下載時防止電腦休眠。
  • Tip: Raycast 也有 Coffee / Anti-sleep 相關的 extension 可以達到一樣的效果，不一定要裝獨立 App。
• 軟體更新檢查：Latest 或 Applite，檢查新版本非常方便。
• 截圖工具：Shottr。

05. 日常應用 (Daily Essentials)

瀏覽器

我目前的需求是「多組帳號切換」、「設定可同步」與「套件多」。

• 主力使用：Vivaldi。
• 其他 Chromium 選擇：Google Chrome (以前常用)、Microsoft Edge、Brave、Arc。
  • 必備 Extension 記錄在 這篇文章。
• WebKit 選擇：Orion (重視隱私且支援 Chrome 套件)。
• AI 瀏覽器 (新趨勢)：
  • Dia
  • ChatGPT Atlas
  • Perplexity Comet
• Firefox：Firefox (因帳號切換功能不符需求而未採用)。

通訊軟體

為了避免開一大堆視窗，我通常使用整合型工具：

• 整合工具：Ferdium (主力)，其他類似選擇還有 Franz 與 Station。
• 常用服務：LINE、Slack、Telegram、Facebook Messenger。

06. 線上工具 (Online Tools)

偶爾才用一次的需求，可以使用一些免費的線上工具解決。

• JSON Editor Online：檢視與編輯 JSON 的工具。
• 圖表繪製：
  • draw.io、Excalidraw、tldraw、Zen Flowchart、yEd live。
  • ASCIIFlow Infinity：輕鬆畫出 ASCII 圖，適合放在程式碼註解裡說明架構。
• 圖片工具：
  • Collage Maker：圖片拼貼工具，通常送 PR 給同事 review UI 修改時，用來製作前後對照圖。

每次換工作都是一次整理工作環境的機會，我的瀏覽器也藉此重裝，雖然每次的工作都不完全一樣，但我發現有些 extension 是不管在之前還是現在的工作、不管是公司還是家裏都會安裝的。以下就是我必備的幾個 extension：

• AdGuard 廣告封鎖器
  這一定是我第一個安裝的套件，實在是因為現在的網頁充斥著大量的廣告，不裝擋廣告套件根本無法好好瀏覽網頁了。

• Bitwarden
  我使用 Bitwarden 來儲存帳號密碼，透過這個套件就可以在瀏覽器快速存取密碼登入網站了。

• Tab Group
  很容易為了查資料不知不覺就開啟幾十個分頁，由於只是臨時查詢的頁面，存為書籤感覺不太必要，一直開著又很浪費資源。這時我就會用這個套件把分頁存成不同的 group 方便日後參考，不需要的時候就把整個 group 砍掉。Arc Browser 跟 Vivaldi 瀏覽器在分頁管理方面做得非常好，完全不需要這個套件。

• Tab Copy
  這個套件可以讓你自訂格式，複製目前開啟的分頁資訊，對於時常需要寫信寫文件傳訊息的工程師來說很方便。

• AutoPagerize
  顧名思義就是自動載入下一頁的套件，幫忙我們節省寶貴的時間。

• 沉浸式翻譯
  方便翻譯單字、片段或是全文的好工具。

• Cleary Reader、簡悅 - SimpRead 或是 Circle 閱讀模式
  讓你瞬間進入沉浸式閱讀的 Chrome 擴展，提供與 Safari 類似的 read mode，以及其他更有彈性的設定。