macOS Tahoe 26 Homebrew 科研環境配置教學

macOS Tahoe 26 科研環境的第一個風險不是套件本身，而是主機條件不明。先在終端機執行：

sw_vers
uname -m
arch
whoami
xcode-select -p
df -h /

你要記錄以下結果：

• sw_vers：macOS 主版本與補丁版本。Apple 支援頁面目前列出的 macOS Tahoe 版本為 26.6。
• uname -m 與 arch：Apple Silicon 通常應顯示 arm64。
• xcode-select -p：確認開發工具路徑是否存在。
• df -h /：確認系統硬碟仍有足夠空間，不要等到編譯或解壓資料集時才發現不足。
• whoami：確認你使用的是一般帳戶、管理員帳戶，還是受限制的遠端帳戶。

Homebrew 官方目前將 macOS Sonoma 14 或更新版本列為支援條件，Apple Silicon 的預設安裝前綴是 /opt/homebrew。Homebrew 安裝要求與預設前綴

先查官方文件，再決定能否直接安裝。
目標科研軟體要逐項確認是否提供 arm64 版本、Homebrew formula、通用二進位檔，或明確支援從原始碼建置。不要因為某個工具在 Linux 上能安裝，就推定它在 Tahoe 26 或 Apple Silicon 上一定可用。

同時把工具分成四類：

1. 純命令列工具。
2. 需要圖形介面的 .app 軟體。
3. 需要付費授權、校園授權或授權伺服器的軟體。
4. 需要 USB、序列埠、特殊感測器或其他實體硬體的工具。

遠端 Mac 通常適合前三類中的命令列與圖形介面驗證，但不能取代需要直接接觸實驗室硬體的本機工作站。

你可以使用 SSH、VNC 或網頁控制台登入。第一次不要急著貼上完整安裝腳本，先確認登入與檔案操作正常：

pwd
touch ~/connection-test.txt
rm ~/connection-test.txt
git --version

如果 git 或其他開發工具觸發安裝提示，按 Apple 的方式處理 Command Line Tools：

xcode-select --install

Apple 說明指出，Command Line Tools 包含 macOS SDK、Clang 等命令列開發工具，安裝位置通常是 /Library/Developer/CommandLineTools；它不等同於完整 Xcode，xcodebuild 和 xctrace 等工具仍可能需要完整 Xcode。Apple Command Line Tools 安裝說明

安裝完成後檢查版本與路徑：

xcode-select -p
pkgutil --pkg-info=com.apple.pkg.CLTools_Executables
clang --version

不要在來源不明的腳本中輸入管理員密碼。需要 sudo 時，先讀懂命令會修改哪個目錄。尤其要留意三個邊界：

• 系統工具與 Homebrew 套件不應混用相同檔案路徑。
• 授權檔、SSH 金鑰和研究資料不要放進公開儲存庫。
• 遠端主機的管理員權限不代表你可以任意更改課題組的系統設定。

如果你在 VNC 中操作圖形介面，還要確認螢幕鎖定、睡眠設定和遠端工作階段不會中斷長時間任務。需要長時間執行工作時，可先閱讀 遠端 Mac 長時間科研任務的斷線恢復方法，再決定採用 SSH、終端機工作階段或圖形介面。

Homebrew 的安裝腳本會先顯示即將執行的內容，確認後才開始。官方文件提供的安裝方式如下：

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

在 Apple Silicon 上，安裝完成後應優先使用：

/opt/homebrew/bin/brew shellenv

安裝程式通常會提示你把 shell 設定加入 ~/.zprofile。若目前使用 zsh，可執行：

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

接著驗證：

command -v brew
brew --prefix
brew config
brew doctor

正常的核心結果應包括：

• command -v brew 指向 /opt/homebrew/bin/brew。
• brew --prefix 顯示 /opt/homebrew。
• brew config 的 CPU、作業系統和 Ruby 狀態沒有明顯矛盾。
• brew doctor 的警告已被逐項理解，而不是直接忽略。

Homebrew 官方文件也提醒，Apple Silicon 上同時存在 /usr/local 和 /opt/homebrew，常見原因是曾經使用 Intel 終端機或從舊 Mac 遷移。可用以下命令檢查：

arch
command -v brew
brew --prefix

Homebrew 常見問題與多重安裝說明

第一輪只安裝有明確用途的工具。例如課題需要版本控制、編譯和資料處理時，可以按實際需求安裝：

brew install git

不要先建立一份「科研工具大全」。套件越多，日後更新、授權和重建時的變數越多。Homebrew 適合管理系統層級工具，但不能取代 Python、R 或其他語言的專案環境管理。

Apple 官方將 Mac 軟體分為 Apple Silicon、Intel 和 Universal 等類型。Intel 應用程式可透過 Rosetta 執行，但這不表示所有外掛、編譯依賴或命令列子程式都會自動相容。Apple Silicon 執行 Intel 應用程式的說明

原有 Intel 科研工具能否直接在 Apple Silicon 上執行？
答案取決於工具本身。圖形應用程式可能透過 Rosetta 執行；命令列工具則要另外檢查可執行檔和相依函式庫。你可以先查檔案架構：

file /path/to/tool

再查 Homebrew 套件：

brew info <formula-name>

若工具顯示為 Intel，先採用以下順序：

1. 查詢上游是否已提供 arm64 或 Universal 版本。
2. 查詢 Homebrew 是否已有原生 formula 或 bottle。
3. 查詢專案是否正式支援 Tahoe 26。
4. 仍只能使用 Intel 版本時，再評估 Rosetta。
5. 不要讓 /usr/local/bin 和 /opt/homebrew/bin 在 PATH 中無順序地混用。

Rosetta 是相容路徑，不是長期的相容性保證。若科研工具包含 Intel-only 外掛、舊版編譯器或特定驅動，最終仍要以該專案的官方文件和實際樣例任務為準。

Homebrew 解決的是系統套件層。Python 套件、R 套件、模型權重和研究程式碼，應該分開保存。至少建立以下檔案：

project/
├── Brewfile
├── pyproject.toml 或 requirements.txt
├── renv.lock 或其他 R 依賴檔
├── README.md
└── docs/
    └── environment-notes.md

先建立專案目錄，再輸出 Homebrew 狀態：

mkdir -p ~/research-project/docs
cd ~/research-project
brew bundle dump --file=./Brewfile --force

Homebrew 文件說明，brew bundle dump 會將已安裝的 formula、cask、tap 等項目寫入 Brewfile，可放進版本控制並進行差異比較。Homebrew Bundle 與 Brewfile 文件

在另一台 Mac 上重建時：

brew bundle install --file=./Brewfile

但不要把 Brewfile 當成完整環境快照。它通常不會替你固定：

• Python 或 R 的專案套件版本。
• 系統補丁和 Command Line Tools 版本。
• 外部授權檔與環境變數。
• 私有 tap、未公開下載網址或研究資料。
• 需要手動設定的圖形介面權限。

遠端 Mac 上的科研環境怎樣長期保存？
至少保存四層記錄：系統資訊、Homebrew 狀態、語言層依賴、最小樣例輸出。把 sw_vers、uname -m、brew config 和 brew doctor 的結果寫入 docs/environment-notes.md，並在每次升級前後提交一次版本差異。

怎樣用 Brewfile 重建課題組環境？
由一名成員維護 Brewfile，其他成員先在乾淨帳戶或隔離主機執行 brew bundle install，再依專案依賴檔建立 Python/R 環境。不要直接使用 brew bundle cleanup，除非你已確認它不會刪除課題組其他工作所需的套件。

不要以「命令成功安裝」作為完成標準。科研環境至少要通過四項測試：

• 讀取一份小型樣例資料。
• 執行課題核心命令。
• 產生可檢查的結果檔。
• 重新登入後再次執行，確認 PATH、權限和工作目錄仍然有效。

可用以下清單逐項勾選：

• [ ] 重新連線後 brew --prefix 仍指向正確路徑。
• [ ] 研究程式找到正確的 Python、R 或編譯器。
• [ ] 樣例資料沒有依賴本機絕對路徑。
• [ ] 結果檔能匯出到課題組指定位置。
• [ ] 中斷任務後能從記錄位置繼續。
• [ ] 第二名成員能依 README 和 Brewfile 重建。
• [ ] 授權檔位置已記錄，但秘密內容沒有提交到版本控制。
• [ ] macOS 更新後，CLT、Homebrew 和核心工具仍能通過驗證。

若課題只需要短期相容性驗證，則先選遠端 Mac；若需要長期穩定重負載，則評估自有設備或校內專用伺服器。
遠端環境的優點是可以按課題週期取得完整 macOS，快速驗證 Apple Silicon、圖形介面和命令列工具；限制則包括網路延遲、資料匯出流程、長任務管理，以及無法直接連接實驗室硬體。

如果實驗室目前沒有可用 Mac，你可以先從 CALMVPS 繁體中文遠端 Mac 入口 了解連線方式，再依課題所在地和連線需求查看遠端 Mac 方案。先完成最小樣例，再決定是否保留環境，比一開始就購買設備更容易控制課題風險。

macOS Tahoe 26、Command Line Tools 和 Homebrew 都會持續更新。科研環境不應在主要實驗週期中隨意升級。建議每次變更前保存：

sw_vers
uname -m
brew config
brew list --versions
brew bundle dump --file=./Brewfile --force

維護時遵守三個條件：

• 若只是安全更新，先在樣例資料上驗證，再安排正式任務。
• 若是 macOS 大版本升級，先確認目標科研軟體的官方支援範圍。
• 若 brew doctor 出現架構或路徑警告，先修正 PATH，不要用符號連結掩蓋缺少的函式庫。

實驗室原本的 Linux 或 Windows 方案，通常面臨三個實際缺點：沒有原生 macOS 測試環境、遇到 Apple Silicon 相容問題時只能靠猜，還可能要為一次短期課題長期維護額外硬體。對需要先驗證 macOS 科研工具鏈的研究生而言，CALMVPS 的按週期遠端 Mac 可以把「購買設備」改成「先驗證、再決定是否長期保留」。不過，如果你的研究長期佔用高負載資源，或必須連接實驗室專用硬體，租用就未必是最佳長期方案；先用最小驗證任務確認適用性，才是成本和交付風險都較低的做法。