macOS 上安裝失敗：Gatekeeper、隔離標記與缺少建置工具（Chinese original）

Mac 上的安裝失敗看起來比 Windows 少，但每一次都更像「這個工具壞了」。原因是 macOS 擋東西的時候，措辭非常重：「無法打開，因為無法驗證開發者」「這個 App 會損壞你的電腦」。

這些話聽起來像在告訴你檔案有問題。多數時候它在告訴你另一件事：這個檔案不是從 App Store 來的，而 macOS 對所有不是從 App Store 來的軟體都會先問一次。

這篇按順序處理四件事：下載錯版本、Gatekeeper 擋下、下載檔被標記、缺少建置工具。每一件都給你一個確認動作。

不需要你會寫程式。

步驟

步驟一：先確認你的 Mac 是哪一種晶片

Apple 從 2020 年末的某些機型開始，把 Mac 從 Intel 處理器轉到自家晶片。這件事對你的直接影響是：很多工具的下載頁會給兩個檔案，選錯的那個可能裝不起來，或裝起來但跑得很怪。

Apple 官方給的分辨方法，是看「關於這台 Mac」視窗裡那一欄的標題：

Apple 晶片的 Mac：顯示一個標籤為**「晶片」**的項目，後面是晶片名稱
Intel 的 Mac：顯示一個標籤為**「處理器」**的項目，後面是 Intel 處理器名稱

開啟方式：從螢幕角落的 Apple 選單裡選「關於這台 Mac」。

用終端機也可以。Apple 官方在「找出你的 Mac 型號名稱與序號」這篇文章裡就給了終端機的做法，並說明終端機 App 位在「應用程式」資料夾的「工具程式」資料夾裡。確認晶片：

uname -m

uname 的 -m 在 Apple 隨 macOS 附上的說明頁（man page）裡的定義是「把目前硬體平台的類型寫到標準輸出」。本站在一台 Apple 晶片的 Mac（macOS 26.6.2）上實際執行這條指令，得到的是 arm64。Intel 機型回報的是另一個值，你可以自己跑一次確認，不需要相信任何文章的說法。

Apple 官方也列了哪些機型有 Apple 晶片：MacBook Pro 2021 年或之後（加上 13 吋 M1 2020）、MacBook Air 2022 年或之後（加上 M1 2020）、iMac 2021 年或之後、Mac mini 2020 年或之後、Mac Studio 2022 年或之後、Mac Pro 2023。

下載頁上看到 arm64 / aarch64 / Apple Silicon 就是給 Apple 晶片的；看到 x86_64 / x64 / Intel 就是給 Intel 的。

一個真實的坑：有些工具的 macOS 安裝檔只提供 Apple 晶片版本。這種情況下 Intel Mac 不是「裝不起來」，是「根本沒有對應的檔案可下載」—— 在下載頁找不到 Intel 選項時，先去工具的官方文件確認支援範圍，不要去找第三方打包的版本。

步驟二：確認 App 到底裝進去沒有

Mac 上「安裝」分成兩種完全不同的東西，卡住的人常常在找錯的那一種。

第一種：圖形介面 App。 它就是一個檔案，躺在「應用程式」資料夾裡。確認方式不需要任何指令：打開 Finder，左側點「應用程式」，看有沒有那個圖示。

.dmg 檔是磁碟映像檔，打開它不等於安裝。macOS 上標準動作是把視窗裡的 App 圖示拖曳到「應用程式」資料夾圖示上。很多人在 .dmg 打開的視窗裡直接雙擊 App 跑了一次，以為裝好了，重開機之後什麼都沒有 —— 因為它從來沒被複製進去。

第二種：命令列工具。 沒有圖示，只有一個可以打名字呼叫的執行檔。確認方式：

which 程式名
command -v 程式名

預期輸出：一行路徑，例如 /usr/local/bin/程式名 或 /opt/homebrew/bin/程式名。

什麼都沒印：分兩種。真的沒裝，或裝了但那個資料夾不在 PATH 與路徑上。用遞迴搜尋確認：

ls -l /usr/local/bin/ | grep 程式名
ls -l /opt/homebrew/bin/ | grep 程式名

找到了路徑卻呼叫不到，就是 PATH 的問題，去步驟六。

步驟三：Gatekeeper 說「無法驗證開發者」

症狀：雙擊 App，跳出一個對話框，說它無法被打開，因為開發者無法被驗證；或說 Apple 無法檢查它有沒有惡意軟體；或說它不是從 App Store 下載的。

這是什麼：macOS 內建一項叫 Gatekeeper 的技術，設計目的是確保只有受信任的軟體在你的 Mac 上執行。Apple 的說明是：當你安裝來自 App Store 之外的 Mac App、外掛程式與安裝套件時，macOS 會檢查 Developer ID 簽章，以驗證軟體來自一位已識別的開發者、而且沒有被竄改。從 macOS Catalina 開始，還預設要求軟體經過公證（notarization）—— Apple 檢查過它、沒有偵測到已知惡意軟體。

Apple 也說明：在第一次打開下載來的軟體之前，macOS 會請求你的同意，以確保你不會被誤導去執行你沒預期的軟體。

所以這個對話框不是錯誤，是一道詢問。

Apple 的 Mac 使用者指南對這種情況講得很直白：如果你試著打開一個沒有由已知開發者向 Apple 註冊的 App，你會得到一個警告對話框；這個 App 沒有被審閱過，macOS 無法檢查它自發布以來有沒有被修改或損壞。

指南也同時給了一句你應該照聽的警告：覆寫安全設定以打開 App，是 Mac 被惡意軟體感染最常見的方式。 如果一個 App 沒有被 Apple 檢查過，即使它看起來來自一家大廠，你也不應該覆寫安全設定；最安全的做法是找 App Store 裡的版本，或找一個替代 App。

如果你確認來源可信（例如你就是從該工具的官方網站下載的），Apple 官方列的覆寫路徑是：

從 Apple 選單打開系統設定
在側邊欄點**「隱私權與安全性」**（指南特別註明：你可能需要往下捲）
捲到**「安全性」**那一區
按**「仍要打開」**
輸入你的登入密碼，按「好」

這裡有一件幾乎所有教學都漏掉的事，Apple 的指南原文寫著：這個按鈕在你試著打開該 App 之後，只保留大約一小時。

意思是：你按了「完成」把警告關掉，然後去泡杯咖啡、去讀別的文章，半小時後回來找不到「仍要打開」按鈕 —— 它不是消失，是過期了。再雙擊一次那個 App，讓警告重新跳出來，按鈕就會再出現一次。

成功之後，Apple 的說明是：該 App 會被存成你安全設定的一項例外，之後你可以像任何其他已授權的 App 一樣，直接雙擊打開它。

如果你要開的是一個命令列工具而不是 App，它可能根本不會觸發這個對話框 —— 沒有圖形介面就沒有地方顯示它。這種情況看步驟四。

順帶說清楚另一個選項：在「隱私權與安全性」的「安全性」底下，有一項「允許從以下位置下載的 App」，Apple 列的選項是「App Store」與「App Store 與已識別的開發者」。Apple 也註明：如果這台 Mac 由公司或學校的系統管理員／IT 部門管理，這些設定可能無法使用。 改成後者是一個全域決定，比針對單一 App 按「仍要打開」影響大得多 —— 能用單一例外解決的，就不要改全域。

步驟四：下載來的檔案被標記成「來自網路」

macOS 會記住一個檔案是從哪裡來的。從瀏覽器或通訊軟體存下來的檔案，會被加上一個延伸屬性（extended attribute），Gatekeeper 就是靠它知道「這是剛下載的、第一次打開要問你」。

你可以自己看這個標記。本站在一台 macOS 26.6.2 的機器上，對幾個下載來的檔案實際執行：

xattr -p com.apple.quarantine 某個下載檔.pdf

得到的輸出形如：

0083;6a3bf230;Safari;
0082;6a3befc1;Feishu;

四段用分號隔開，最後一段是放下這個檔案的那個程式 —— 上面兩筆分別是 Safari 下載的與某個通訊軟體存下來的。這是本站自己跑出來的第一手觀察，不是抄自文件；Apple 隨 macOS 附上的 xattr 說明頁並沒有逐一列出各個系統屬性的名字，所以這個屬性名以實際執行結果為準。

這個標記是正常的，不是中毒。 它就是你會看到步驟三那個對話框的原因。

網路上常見的「解法」是把標記移除：

xattr -d com.apple.quarantine 某個檔案

本站不建議你把這個當成預設做法。 理由跟步驟三那條 Apple 警告是同一個：這個標記存在的目的是讓 macOS 在第一次執行前問你一次。移除它，你就跳過了那一次詢問 —— 對一個你確認過來源的 App，用「仍要打開」達成同樣的效果，而且留下一條看得見的例外紀錄，比在終端機裡把標記刪掉好。

真的要用的時候，注意兩件事：只對單一檔案用，不要對整個資料夾遞迴用；以及用完之後那個檔案就不再受 Gatekeeper 的首次詢問保護。

步驟五：安裝到一半說找不到建置工具

症狀：你在終端機跑一段安裝指令，它跑到某一步停下來，說需要命令列開發者工具、或說找不到 cc／clang／git／make，然後跳出一個系統對話框問你要不要安裝。

這是什麼：macOS 預設不附編譯器與相關工具。Apple 的技術文件說明，「命令列工具套件」是一個可獨立下載的小型自成套件，讓你能在 macOS 上做命令列開發；它包含 macOS SDK 與 Clang 這類命令列工具，安裝在 /Library/Developer/CommandLineTools 目錄。

官方給的安裝方式（Apple 技術文件 TN2339 原文）：在終端機執行

xcode-select --install

Apple 也說明，macOS 本身就附帶 xcode-select 這個命令列工具，安裝在 /usr/bin，用來管理 Xcode 與其他 BSD 開發工具的使用中開發者目錄。

預期輸出：一個系統對話框，問你要不要安裝命令列開發者工具，按「安裝」並同意授權條款，然後它自己下載。下載需要幾分鐘，視網路而定。

確認裝好了：

xcode-select --print-path

Apple 的文件用這條指令來查「目前命令列工具用的是哪個版本／哪個 Xcode」。印出一個路徑就代表有；沒裝過的話它會告訴你找不到。

不需要為了這個裝整個 Xcode。 Apple 的文件明說，如果 Xcode 已經裝在你機器上，就不需要另外裝命令列工具（Xcode 已經全包了）；但反過來不成立 —— 你只是要跑一個安裝腳本，裝那個小型套件就夠，Xcode 是十幾 GB 的東西。

還有一種狀況：同一份 Apple 文件提到，如果 /Library/Developer/CommandLineTools 這個目錄存在，移除它就會解除安裝命令列工具。所以「我明明裝過，怎麼又說找不到」有可能是那個目錄被動過 —— 重跑一次 xcode-select --install 通常就解決。

步驟六：Homebrew 裝完，指令還是找不到

很多 Mac 上的 AI 工具教學第一行就是 brew install 某個東西。Homebrew 是 macOS（與 Linux）上事實標準的套件管理器，詞條見 Homebrew（brew）。

官方文件說明它的預設安裝位置：Apple 晶片是 /opt/homebrew，macOS Intel 是 /usr/local，Linux 是 /home/linuxbrew/.linuxbrew。文件也說明這個位置選在這裡，是為了讓你在初次安裝 Homebrew 之後不需要 sudo 就能安裝 formula（某些 cask 與系統服務仍需要提權）。

這直接給了你一個診斷線索：Apple 晶片與 Intel 的 Mac，Homebrew 的 bin 目錄是兩個不同的路徑（/opt/homebrew/bin 對 /usr/local/bin）。網路上抄來的 PATH 設定如果是寫給另一種晶片的，你照做之後一樣是 command not found。

官方要求你把下面這行加進 shell 的設定檔（檔案依你的 shell 而定，例如 ~/.bashrc 或 ~/.zshrc）：

eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac 把路徑換成 /usr/local/bin/brew。官方文件的原話是：如果你沒有照那些指示更新 shell 的設定，Homebrew 將無法運作。

改完設定檔之後，開一個新的終端機視窗再試。設定檔只在 shell 啟動時讀一次，這件事在 Config File（設定檔）詞條裡有說明。

不要對 brew 加 sudo。 官方文件說明的預設位置設計，目的就是讓你不需要提權；用 root 跑 Homebrew 會讓它產出的檔案變成 root 擁有，之後你用平常身分跑又卡住。詞條 sudo（管理員權限）把這個陷阱的完整鏈條寫出來了。

三個 macOS 特有、看起來像壞掉的狀況

一、.dmg 打開之後，桌面多出一個白色磁碟圖示。 那是掛載中的磁碟映像檔，正常。安裝完要把它退出（右鍵 → 退出，或拖到垃圾桶圖示上）。它不會自己消失，也不是「多裝了一份」。

二、終端機第一次跑某個指令時，跳出一個視窗要求「允許存取可移除的卷宗／桌面／文件資料夾」。 這是 macOS 的隱私保護在問你，不是錯誤。按允許。按了拒絕的話，之後那個工具會以「找不到檔案」的姿態失敗，而錯誤訊息完全不會提到權限 —— 到系統設定 → 隱私權與安全性裡找對應的項目重新給。

三、指令在終端機裡跑得通，從 Finder 雙擊或從某個 App 裡呼叫就失敗。 從圖形介面啟動的程式，讀到的環境跟你的 shell 不一定相同，尤其是 PATH。這也是為什麼很多工具要求你「從終端機啟動它」。

下一步

用的其實是 Windows：Windows 上安裝失敗：PATH、執行原則、SmartScreen 三件事
想有一套不分作業系統的判斷流程：裝完沒反應：五個檢查，照順序做完再重裝
錯誤訊息到底該怎麼讀：怎麼讀一則錯誤訊息
那個視窗到底是什麼：Terminal 是什麼
路徑、~、空格與引號：檔案路徑是什麼
先把詞認完：開始之前：你只需要先認識這 20 個詞

步驟