你看到的症狀是：mojo 可以執行，但 GPU 範例回報找不到 Apple GPU 或 Metal 工具。
最快解法是：先確認 macOS 15+、Apple Silicon M1–M5、Xcode 或命令列工具 16+，再檢查 Xcode 路徑與 Metal Toolchain；只有最小 GPU 程式成功後，才應轉查 MAX 26.5 的模型與記憶體問題。
這篇排障筆記適合誰
如果你已能執行 mojo，但 GPU 範例出現裝置、Metal 或編譯錯誤，這篇會幫你縮小範圍。
如果你正用 Apple Silicon M1/M2 評估 MAX serve，卻分不清是晶片不支援還是模型不支援，也可以直接從故障樹開始。平台負責人則可用同一組輸出，判斷本機修復或遠端 Apple Silicon 環境是否更合理。
先保留證據： 不要一開始就刪除虛擬環境。請記下
mojo、max的實際路徑、xcode-select -p輸出，以及首次失敗時的完整錯誤訊息。排障時，這些資料比「我已經重裝過」更有用。
三層結果與故障邊界
Mojo 語言可執行、Metal 可呼叫、目標模型可服務，是三個不同結論。你可以按以下順序分流：
-
mojo命令不可用
先查安裝環境、Shell PATH 和虛擬環境。此時還不能判斷 GPU 或 MAX。 -
Mojo 程式能執行，但 GPU 不可見
優先查系統版本、Apple Silicon、Xcode 開發者目錄和 Metal Toolchain。不要先把 M1/M2 判定為淘汰硬體。 -
最小 GPU 程式成功，但
MAX serve失敗
Metal 基礎層已經通過。接著查max[serve]是否存在、模型架構、Apple GPU 核心覆蓋，以及可用統一記憶體。反覆重裝 Mojo 通常不會修好模型圖編譯錯誤。
Mojo GPU 入門範例可作為基準測試；請以官方 GPU 入門程式的結果作比較，不要用一個完整模型的失敗結果代替硬體探測。
系統與晶片支援
官方系統要求是 macOS 15 或以上、Apple Silicon M1–M5，並要求 Xcode 或命令列工具 16 或以上。Mojo 1.0 系統要求是這一層的判斷依據。
因此，M1 和 M2 位於官方兼容範圍內。看到「GPU not found」時，合理的第一個假設是環境未對齊，不是晶片必然不支援。若你的 Mac 是 Intel 機，或 macOS 低於要求，應停止軟體層排查，改為升級、換用符合要求的 Mac，或先用遠端 Apple Silicon 環境重現。
在終端機先收集以下資料：
uname -m
sw_vers
system_profiler SPHardwareDataType
xcode-select -p
xcodebuild -version
你要確認的是實際處理器架構、macOS 版本、Xcode 版本與目前開發者目錄。不要只看 Finder 中安裝了哪個 Xcode；系統可能仍指向舊版本，甚至指向已刪除的路徑。
Metal Toolchain 與內建 Framework
macOS 內建的 Metal Framework，和額外下載的 Metal Toolchain 不是同一件事。前者讓系統與應用程式使用 Metal API；後者涉及某些 GPU 程式編譯所需的開發工具。只確認「Mac 有 Metal」不足以證明 Mojo 能完成編譯。
當錯誤明確指向 Metal 工具找不到、GPU 編譯階段失敗，或 macOS／Xcode 更新後突然失效，可依官方方式執行：
xcodebuild -downloadComponent MetalToolchain
接著重新執行最小 GPU 範例，並檢查上一個指令的退出狀態：
echo $?
如果下載指令成功，但最小程式仍失敗，下一步不是再次下載，而是回到 Xcode 路徑與命令列工具。若最小程式成功，則 Metal 層已通過，請停止追查 Toolchain，改查 MAX。
更新後的判斷： macOS 或 Xcode 更新不代表一定要重裝 Metal Toolchain；但只要 Metal 編譯錯誤在更新後出現，就要重新驗證。下載完成畫面不是驗收結果，能否成功編譯最小 GPU 程式才是。
Xcode 路徑與命令列工具
多個 Xcode 版本並存時，最容易出現「你安裝的是新版、系統使用的是舊版」的錯位。先查看目前路徑：
xcode-select -p
xcrun --find metal
xcodebuild -version
若 xcode-select -p 指向不再存在的目錄，或 xcodebuild -version 顯示的版本低於官方要求，重新選擇有效的 Xcode：
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
如果你使用的是獨立的 Command Line Tools，則應在 Apple 的命令列工具設定文件中確認選取狀態。完成後重新開啟終端機，再執行 xcrun --find metal 與最小 GPU 程式。
不要同時修改多個環境變數再測試。一次只修正開發者目錄，否則你無法知道真正有效的變更。
套件來源與執行時錯位
Mojo、MAX、Python 及虛擬環境可能不是來自同一個環境。尤其是 uv、pixi、全域安裝與舊版 modular 並存時，終端機呼叫的命令不一定是你剛更新的那一份。
先查實際位置：
command -v mojo
command -v max
python -c "import sys; print(sys.executable)"
python -c "import importlib.util; print(importlib.util.find_spec('max'))"
再確認目前專案到底需要哪一組 MAX 套件。MAX 26.5 已把功能拆分為不同套件，服務工作應檢查 max[serve]，基準測試才需要 max[benchmark]；只有確定專案需要完整功能時，才考慮 max[all]。詳細拆包方式以MAX Packages 說明為準。
| 症狀 | 優先檢查 | 不要先做的事 | 下一個驗證 |
|---|---|---|---|
mojo 找不到 |
PATH、虛擬環境、命令實際路徑 | 刪除所有環境 | command -v mojo |
| GPU 探測失敗 | Xcode 路徑、Metal Toolchain、系統要求 | 直接換 M1/M2 | 最小 GPU 程式 |
MAX serve 缺少命令 |
max[serve] 是否安裝 |
重裝 Metal | 查套件來源與版本 |
| 模型編譯失敗 | 模型架構、核心覆蓋、記憶體 | 反覆重裝 Mojo | 換支援度較高的模型 |
清理時只處理出錯的專案環境。不要刪除其他仍可用的 uv 或 pixi 專案，也不要把穩定版與 nightly 套件混裝後再比較錯誤訊息。
MAX 26.5 與模型編譯
MAX 26.5 已將 Apple Silicon GPU 支援擴展回 M1；這是硬體支援修正，不等於所有模型都能在每一代晶片上服務。MAX 26.5 官方發布說明與更新記錄可用來核對版本行為。
MAX 在 Apple Silicon 上仍是模型子集。官方模型頁列出的支援範圍，不能延伸解讀成「任何 Hugging Face 模型都能直接 serve」。例如模型可能通過 GPU 探測，卻在圖編譯階段使用未覆蓋的核心、特殊算子或不相容的權重格式。MAX 模型支援頁是你選模型時應先看的資料。
此時請按三個方向處理：
- 環境修復： 最小 GPU 程式也失敗，繼續查 Xcode、Toolchain 和套件路徑。
- 模型調整： 最小程式成功，但特定模型失敗，先換官方支援度較高的架構或縮小測試範圍。
- 環境遷移： 模型需要較多統一記憶體、多人共用，或本機無法穩定重現時，改用較充裕的遠端 Apple Silicon Mac。
| 驗證結果 | 故障位置 | 建議決策 | 你要保存的證據 |
|---|---|---|---|
mojo 不可用 |
安裝或 PATH 層 | 重建單一專案環境 | command -v mojo、Python 路徑 |
mojo 可用、GPU 範例失敗 |
Metal／Xcode 層 | 修 Toolchain 或開發者目錄 | xcode-select、xcodebuild 輸出 |
| GPU 範例成功、單一模型失敗 | MAX／模型層 | 換模型或核對算子支援 | 模型名稱、完整編譯錯誤 |
| GPU 範例與模型都成功但團隊不穩定 | 資源與交付層 | 建立遠端可重現環境 | 初始化記錄與探測輸出 |
這也解釋了為什麼「M1/M2 能不能用 Mojo」不能只回答能或不能：Mojo GPU 程式的可執行性、MAX 的模型覆蓋、以及可用記憶體，是三個不同的門檻。
可重現的五步驗收流程
- 固定版本與環境紀錄。 保存 macOS、晶片、Xcode、
mojo、max版本，以及使用uv或pixi的專案來源。 - 確認開發者目錄。 執行
xcode-select -p、xcrun --find metal和xcodebuild -version，先排除舊 Xcode 或失效路徑。 - 只在需要時下載 Toolchain。 執行官方
xcodebuild -downloadComponent MetalToolchain，記下退出狀態，不把下載畫面當成成功證明。 - 執行最小 GPU 程式。 使用官方 Mojo GPU 範例，保存完整標準輸出與錯誤輸出；不要先用大型模型測試。
- 再測 MAX 服務。 確認安裝的是
max[serve]，選擇官方模型頁列出的支援模型，將模型編譯錯誤與 Metal 探測錯誤分開保存。
若你要把這套流程交給團隊，建議將命令輸出與模型名稱放在同一份驗收記錄內。這比只記錄「已安裝成功」更容易在另一部 Mac 或雲端環境重現。
常見誤判與處置
- 把 M1/M2 當成不支援： 官方要求涵蓋 M1–M5；先查環境，不要先換晶片。
- 把 Metal Framework 當成 Toolchain： 系統有 Metal，不代表編譯工具完整。
- 把套件缺失當成 GPU 故障：
MAX serve命令不存在時，先查max[serve]。 - 把模型失敗當成 Mojo 失敗： 最小 GPU 程式成功後，故障邊界已經移到 MAX 或模型。
- 把遠端環境當成萬能解法： 若你需要實體 USB、特定外接裝置或長期固定重負載，應先評估自購 Mac；雲端環境主要適合臨時算力、團隊測試與可重現部署。
截至 2026 年 8 月 21 日，本文依據 Mojo 1.0 系統要求、MAX Packages、MAX 26.5 發布與更新資料核實。官方已確認 Mojo 1.0 於 2026 年 8 月 11 日發布，ModCon 2026 亦已宣布 Mojo 編譯器與工具鏈完整開源；這些發布資訊不會改變上述故障分層。官方 MAX 26.5 說明可作版本背景核對。若日後出現 MAX 26.6、最低系統要求或套件名稱變更，請重新核對官方文件，不要照搬舊命令。
FAQ：安裝後的分流答案
Mojo 1.0 為什麼在 Mac 上偵測不到 Apple GPU？
先不要把問題歸因於 M1 或 M2。Mojo 1.0 的官方支援範圍涵蓋 Apple Silicon M1–M5；較常見原因是 macOS 版本、Xcode 或命令列工具指向錯誤，或額外的 Metal Toolchain 尚未安裝。請先保留最小 GPU 程式的完整錯誤輸出。
Metal Toolchain 下載完成後，Mojo 仍然報錯要怎麼辦？
下載完成只代表安裝指令執行過，不代表目前的開發者目錄能使用該工具鏈。重新確認 xcode-select 指向的 Xcode、命令列工具版本與 Metal 編譯錯誤，再執行最小 GPU 範例。若最小範例仍失敗，問題在工具鏈或路徑；若成功，應轉查 MAX 或模型。
Apple Silicon M1 和 M2 是否支援 Mojo GPU 程式設計？
支援。Mojo 1.0 的系統要求列出 Apple Silicon M1–M5，MAX 26.5 也把 Apple Silicon GPU 支援擴展回 M1。這只代表硬體位於支援範圍，不代表每個 MAX 模型或每種核心都能在 M1、M2 上完成編譯與服務。
最小 GPU 程式正常，但 MAX serve 仍然啟動失敗，問題在哪裡？
這通常不是 Metal Toolchain 故障。最小程式成功後，應檢查 MAX 套件是否包含 serve 元件、目標模型是否在 Apple Silicon 支援子集中、模型圖是否使用未覆蓋的核心，以及統一記憶體是否足夠。必要時先換支援度較高的模型，再評估更大記憶體的遠端 Mac。
更新 macOS 或 Xcode 後，需要重新安裝 Metal Toolchain 嗎？
不必每次更新都盲目重裝，但系統升級後若出現 Metal 編譯錯誤、工具找不到或開發者目錄失效，就應重新檢查並視結果執行官方下載指令。完成後必須用最小 GPU 程式驗證，而不是只看下載指令是否顯示成功。
如果你的本機只是 Xcode 路徑損壞，留在本機修復成本最低；你可以先參考 MacHTML 的技術支援與環境排查說明。但若真正限制是統一記憶體不足、GPU 被其他工作長時間佔用，或團隊需要每次都得到相同的初始化結果，繼續在同一部 Mac 重裝只會重複消耗時間。相較之下，自購 Mac 適合長期固定負載，現有本機方案則可能受硬體記憶體、單人佔用和環境不可重置限制；租用 MacHTML 的雲端 Mac，可按芯片代際、記憶體需求與使用週期提交環境，並用同一份 Metal 探測和最小 GPU 日誌驗證遷移結果。需要臨時算力或測試環境時，再查看MacHTML 的方案資訊會比盲目換機更容易做出可核對的決定。
需要更穩定的 Apple Silicon GPU 開發環境？
使用 MacHTML 遠端 Mac，在雲端取得適合 Mojo、Metal 與 MAX 開發的 Apple Silicon 運算環境。 免受本機 macOS、Xcode 或 Metal Toolchain 設定限制影響，快速切換至合適的 Mac 執行個體。 透過遠端桌面操作完整 macOS，方便測試 GPU 工作流程、模型支援度及實際執行結果。 按您的開發需求選擇 Mac 租賃或算力方案，讓除錯與驗證不再受限於手上的硬件。