FreeSurfer 8.2 已提供 Apple Silicon 原生安裝路線；研究者應使用官方 arm64 安裝包，獨立設定授權與 XQuartz，並在命令列、Freeview、SynthSeg 三個場景分別驗收。基礎安裝成功，不代表整套腦部 MRI 流程已經可以交付。
本指南適合三類讀者：需要在 Apple Silicon Mac 建立 FreeSurfer 8.2 環境的研究生與博士生；實驗室只有 Windows、Linux 或高校集群，卻需要補充 macOS 驗證環境的科研人員；以及負責版本、授權與結果重現的高校技術支援人員。
最後更新於 2026 年 8 月 30 日；版本與相容性資料核實自 FreeSurfer 官方下載頁、官方發布說明及 FreeSurfer 8.2.0 更新說明。官方頁面日後若更換安裝包名稱、校驗值或 macOS 支援範圍，應以重新核對後的內容為準。
[ SECTION_01 ] 先確認原生路線與研究邊界
官方頁面目前將 FreeSurfer 8.2.0 標示為穩定版本，並提供 Apple Silicon 的 arm64 安裝路線與 macOS Tahoe 支援說明。可是下載表格中的版本標籤、檔案名稱與支援系統欄位可能需要逐頁確認，不能直接沿用舊版 Intel Mac 或虛擬機教學。
安裝前先做三項確認：
- 在終端機執行
uname -m，確認處理器架構為arm64。 - 只從官方下載頁取得對應的 arm64 PKG，並對照頁面當日的校驗資訊。
- 記錄 macOS 版本、FreeSurfer 版本、安裝檔名稱與校驗值，放進課題環境紀錄。
FreeSurfer 8.2 是否原生支援 M 系列 Mac？
目前官方提供 arm64 安裝路線，因此可按原生 Apple Silicon 路線部署；但「能夠安裝」與「所有工具都能完成研究任務」是兩個不同判斷。尤其 SynthSeg 必須依照 8.2.0 更新說明檢查已知問題與最新修補狀態。
如果課題只需要查看既有輸出，驗收重點是 Freeview 與資料讀取。若要執行 recon-all，則必須增加長時間批次、磁碟空間、權限與日誌檢查。若要使用 Python 分割工具，則要另外驗證模型依賴與輸出檔案。
[ SECTION_02 ] 安裝目錄、授權與環境變數分開管理
已有舊版 FreeSurfer 的主機，不應直接覆蓋原目錄。先記錄舊版路徑、環境變數、SUBJECTS_DIR、課題使用的命令參數，以及正在處理的被試清單。舊環境最好保留只讀備份，避免新版本改寫論文專案正在使用的輸出。
官方 Mac 安裝文件提供 PKG 安裝與環境初始化方向。安裝完成後，先以新目錄作為測試環境，不要立即替換研究群組共用的設定。以下只保留必要命令：
export FREESURFER_HOME=/usr/local/freesurfer/8.2.0
source "$FREESURFER_HOME/SetUpFreeSurfer.sh"
export FS_LICENSE="$FREESURFER_HOME/license.txt"
實際路徑必須以安裝程式和官方文件當日內容為準。許可證檔案也可以透過 FS_LICENSE 指向明確的絕對路徑，重點是不要依賴某個使用者帳戶中未記錄的隱藏設定。
FreeSurfer 的 license.txt 應該放在哪裡？
建議把它放在版本化且權限可控的位置，例如測試版本的 FreeSurfer 目錄，或課題專用的授權目錄，再由 FS_LICENSE 明確指定。完成註冊後，按照 FreeSurfer 官方註冊頁取得授權資訊。不要把授權檔提交到 Git 儲存庫，也不要把它放進會被公開同步的資料夾。
最小安裝通過證據應包括：
recon-all --version能輸出預期版本。which recon-all指向目前測試目錄。- 啟動工具時能識別授權檔。
- 能讀取官方測試資料或脫敏樣例。
這四項中任何一項失敗，都只能判定為「安裝尚未完成」，不能進入真實論文資料處理。
[ SECTION_03 ] 四個科研方案的取捨
下表用來決定環境方向，而不是替代實際驗收。評分採用高、中、低，表示對指定科研場景的適配程度，不代表官方效能測試結果。
| 方案 | 原生 Apple Silicon | recon-all 批次 |
Freeview 圖形檢查 | 版本隔離 | 適合情境 |
|---|---|---|---|---|---|
| Apple Silicon 本機 | 高 | 高 | 高 | 中 | 已有可管理的 Mac，需長期處理 |
| Intel Mac 或舊教學路線 | 低 | 中 | 中 | 低 | 只作歷史環境參考，不宜作新部署起點 |
| 虛擬機內的舊 macOS | 不確定 | 低至中 | 低至中 | 中 | 只為重現特定舊環境，先做完整驗收 |
| 遠端 Apple Silicon Mac | 高 | 中至高 | 取決於遠端顯示鏈路 | 高 | 實驗室沒有 Mac、短期驗證或跨系統測試 |
| Linux 主機 | 不適用 | 視既有 Linux 流程而定 | 視桌面環境而定 | 高 | 既有批次穩定，暫不需要 macOS 結果 |
如果讀者只是想補一個 macOS 驗證節點，遠端 Apple Silicon Mac 通常比為單一課題立即購置設備更容易回退。若課題有長期、大量、連續的批次工作，則應把本機 Mac、Linux 伺服器或雙軌環境納入正式資源規劃，而不是把遠端連線當成永久替代。
[ SECTION_04 ] recon-all 場景要先驗證輸出基線
FreeSurfer 的 recon-all 不應一開始就拿唯一一份真實被試資料試錯。先使用官方教學資料或已脫敏樣例建立最小測試，再逐步換成能代表論文流程的被試。可參考 官方 recon-all 教學與 重建流程說明。
建議按以下步驟執行：
- 建立專用的
SUBJECTS_DIR，確認目前使用者具有讀寫權限。 - 將原始影像、測試輸出與日誌放在不同目錄，避免誤刪或覆蓋。
- 先執行官方最小案例，記錄命令列、版本與開始時間。
- 檢查終端機退出狀態，以及日誌最後是否出現錯誤。
- 核對主要輸出目錄是否完整，再進行人工質控。
- 將同一樣例放到既有 Linux 流程比較，但不要預設兩個作業系統會產生完全相同結果。
- 只有在樣例通過後，才處理代表性被試。
此處不應自行填寫記憶體、硬碟或耗時數字。FreeSurfer 8.x 的流程與資源需求曾有變更，資源要求應以官方文件和實際課題資料量評估。能夠啟動命令，不等於長時間重建能穩定完成。
Apple Silicon Mac 執行 recon-all 前要驗收什麼？
至少要確認架構、授權、SUBJECTS_DIR 權限、可用硬碟空間、連續執行穩定性、日誌退出狀態與輸出完整性。若測試在長時間批次中失敗，應先停止擴大資料量，回到 Linux 路線或建立雙軌環境，而不是直接重跑更多被試。
[ SECTION_05 ] Freeview 要把主機問題與顯示鏈路拆開
Freeview 的故障不一定代表 FreeSurfer 命令列不可用。Mac 上應先按照官方文件安裝並驗證目前的 XQuartz，版本資訊以 XQuartz 官方發布頁為準。不要只從 Finder 點擊程式；先在終端機啟動，才能取得較清楚的錯誤訊息。
驗收可拆成四層：
- 空視窗能否啟動。
- 能否載入官方樣例的體積影像。
- 能否顯示表面與基本切片。
- 旋轉、縮放、切換檢視時是否出現崩潰或顯示異常。
Freeview 在 Mac 上打不開時怎麼檢查 XQuartz？
先確認 XQuartz 已安裝、能正常啟動，再完全關閉並重新開啟終端機與 Freeview。若空視窗已能開啟但載入資料失敗，問題可能在檔案權限、路徑或資料本身，不應繼續反覆重裝 XQuartz。若主機本身通過，而遠端螢幕出現延遲，則要另外記錄 VNC 畫面更新、三維操作和大檔案載入狀況；這些屬於網路連線體驗，不能用官方軟體說明代替本站實測。
[ SECTION_06 ] SynthSeg 必須獨立驗收
recon-all 通過後，不能推論 SynthSeg 也一定可用。FreeSurfer 8.2.0 發布說明已列出 arm64 Mac 上 SynthSeg 可能無法安裝或完成執行的已知問題。應先閱讀 FreeSurfer 8.2.0 更新說明，套用官方最新更新，再開始測試。
建議流程如下：
- 記錄目前 FreeSurfer 版本與更新狀態。
- 依官方說明套用最新修補，不自行替換未知來源的 Python 依賴。
- 使用單一脫敏影像測試模型載入。
- 核對輸出檔案、命令結束狀態與日誌。
- 用 Freeview 或其他已核准工具檢查結果。
- 將 SynthSeg 的結果與課題既有質控方法對照。
若官方修補後仍無法完成關鍵模組，應選擇暫緩遷移、保留 Linux 流程，或建立 Linux/macOS 雙軌環境。未經證實的手工依賴替換，可能令日後結果無法重現。
[ SECTION_07 ] 代表性被試決定是否交付
正式交付前，選一個能代表論文工作流的脫敏被試。環境記錄至少包括 FreeSurfer 版本、macOS 版本、處理器架構、命令參數、授權狀態、日誌、主要輸出與人工質控結果。這份紀錄比「程式成功開啟」更能支持課題審查與日後重跑。
跨 Linux 與 macOS 比較時，應把作業系統差異可能造成的結果變化交給官方版本說明與課題統計方案判斷。不同平台的輸出不能預設為天然完全一致。若要混用結果，必須先完成同一代表性資料的平行驗證。
實驗室沒有 Mac 時，可先按週期使用遠端 Apple Silicon Mac，完成安裝、批次處理、Freeview 檢查與檔案帶走測試。NOVAKVM 的 繁體中文遠端 Mac 方案可作為環境選擇的入口；若研究團隊位於香港，也可查看香港遠端 Mac 方案。遠端方案的連線方式、交付流程與實際穩定性，仍應以當次租用條件和本站實測為準。
對短期復現、論文補圖或 Apple Silicon 相容性驗證而言，現有 Windows/Linux 方案的限制通常很明確：缺少原生 macOS 工具鏈、圖形檢查需要額外轉接、跨平台權限與路徑容易產生差異。直接購置 Mac 則會帶來一次性硬體成本、設備管理與閒置問題。若先租用 NOVAKVM 的遠端 Mac 完成樣例和代表性被試驗收，研究者可以根據課題週期再決定長期設備、Linux/macOS 雙軌，或繼續採用短期環境，而不是在結果未確認前承擔長期維護成本。
需要臨時算力或測試環境時，最穩妥的做法不是立即搬遷全部資料，而是先以脫敏樣例完成三層驗收：命令列、Freeview、SynthSeg。三層都通過，再把遠端 Mac 納入課題交付流程；任何一層未通過，便保留 Linux 路線並等待官方更新。