ClashX 安裝失敗怎麼辦：6 種常見原因與解決方案

安裝失敗的 6 種常見原因概覽

在 macOS 上安裝 ClashX 時，你可能會遇到彈窗警告、應用程式無法開啟或安裝中途失敗等問題。以下是最常見的 6 種原因及其對應解決方案的快速索引：

原因 1 — macOS Gatekeeper 阻擋安裝

macOS Gatekeeper 是蘋果內建的安全機制，預設只允許來自 App Store 或已認證開發者的應用程式執行。由於 ClashX 是開源社群發布的應用，未通過 Apple 公證，因此會被 Gatekeeper 攔截。

方法一：透過系統偏好設定允許

1. 嘗試開啟 ClashX，系統彈出阻擋提示後點擊 好
2. 開啟 系統偏好設定 → 安全性與隱私 → 一般
3. 在底部找到「已阻擋使用 ClashX」的提示，點擊 強制開啟
4. 在確認彈窗中再次點擊 開啟

方法二：使用終端機移除隔離屬性

如果方法一無效，可以使用 xattr 指令移除 macOS 為下載檔案新增的隔離標記：

sudo xattr -cr /Applications/ClashX.app

執行後輸入管理員密碼，然後重新開啟 ClashX 即可。

方法三：暫時允許任何來源（不建議長期使用）

sudo spctl --master-disable

此指令會在「安全性與隱私」中顯示「任何來源」選項。修復完成後建議恢復：

sudo spctl --master-enable

原因 2 — 程式碼簽章問題

如果你看到「ClashX 已損壞，無法開啟」或「無法驗證開發者」等提示，可能是應用程式的程式碼簽章遺失或無效。

檢查應用程式簽章狀態

# 檢查 Gatekeeper 評估結果
spctl --assess --verbose /Applications/ClashX.app

# 檢視詳細的程式碼簽章資訊
codesign -dv --verbose=4 /Applications/ClashX.app

# 驗證簽章完整性
codesign --verify --deep --strict /Applications/ClashX.app

解決方法

1. 重新簽章（推薦）：使用 ad-hoc 簽章修復

   sudo codesign --force --deep --sign - /Applications/ClashX.app

2. 移除隔離標記 + 重新簽章：

   sudo xattr -cr /Applications/ClashX.app
   sudo codesign --force --deep --sign - /Applications/ClashX.app

3. 如果以上均無效，請從官方下載頁重新取得最新版本

原因 3 — 系統版本不相容

ClashX 要求 macOS 10.15 (Catalina) 或更高版本。較舊的 macOS 版本可能導致安裝失敗或啟動後閃退。

檢查目前系統版本

# 檢視 macOS 版本
sw_vers

# 輸出範例：
# ProductName:        macOS
# ProductVersion:     14.3.1
# BuildVersion:       23D60

版本相容性對照

解決方法

• 如果系統版本過低，請升級 macOS 或使用相容的舊版 ClashX
• Apple Silicon (M1/M2/M3) 使用者請確保下載通用版或 ARM64 版本

原因 4 — 磁碟空間不足

ClashX 安裝檔約 20 MB，但執行時需要額外空間儲存設定檔和記錄檔。磁碟空間不足可能導致安裝中斷或執行異常。

檢查磁碟可用空間

# 檢視磁碟使用情況
df -h /

# 輸出範例：
# Filesystem     Size   Used  Avail Capacity  Mounted on
# /dev/disk1s1  460Gi  380Gi   75Gi    84%    /

快速清理方法

# 清理系統快取
sudo rm -rf ~/Library/Caches/*

# 清理 Xcode 衍生資料（如有）
rm -rf ~/Library/Developer/Xcode/DerivedData

# 清理系統記錄檔
sudo rm -rf /var/log/*.gz

# 檢視大型檔案
du -sh ~/Downloads/* | sort -rh | head -20

建議保持至少 5 GB 以上可用空間以確保 ClashX 正常運作。

原因 5 — 舊版本衝突

在已有舊版 ClashX 或 ClashX Pro 的情況下直接安裝新版，可能因為殘留設定、快取或 Helper 工具衝突導致安裝失敗。

完整移除舊版 ClashX

# 1. 結束 ClashX
osascript -e 'quit app "ClashX"'

# 2. 刪除應用程式本體
sudo rm -rf /Applications/ClashX.app

# 3. 清理設定與資料
rm -rf ~/Library/Application\ Support/com.west2online.ClashX
rm -rf ~/Library/Application\ Support/ClashX

# 4. 清理偏好設定
rm -f ~/Library/Preferences/com.west2online.ClashX.plist
rm -f ~/Library/Preferences/com.west2online.ClashXPro.plist

# 5. 清理快取
rm -rf ~/Library/Caches/com.west2online.ClashX

# 6. 移除 Helper 工具
sudo rm -f /Library/PrivilegedHelperTools/com.west2online.ClashX.ProxyConfigHelper
sudo rm -f /Library/LaunchDaemons/com.west2online.ClashX.ProxyConfigHelper.plist

驗證清理完成

# 確認沒有殘留程序
ps aux | grep -i clash

# 確認 Helper 已移除
ls -la /Library/PrivilegedHelperTools/ | grep -i clash

清理完成後重新從下載頁取得最新版並安裝。

原因 6 — 網路下載問題導致檔案損壞

下載過程中如果網路不穩定（特別是使用代理或 CDN 時），可能導致安裝檔不完整或損壞。

校驗下載檔案完整性

# 使用 SHA-256 校驗檔案
shasum -a 256 ~/Downloads/ClashX.dmg

# 將輸出的雜湊值與官方發布頁提供的值對比
# 如果不一致，說明檔案已損壞，需要重新下載

解決方法

1. 更換網路環境：嘗試關閉現有代理，使用直連下載
2. 使用瀏覽器下載：避免使用下載管理程式（可能修改檔案）
3. 透過 curl 下載：

   # 使用 curl 從 GitHub Release 下載
   curl -L -o ~/Downloads/ClashX.dmg \
     https://github.com/ClashX-Pro/ClashX/releases/latest/download/ClashX.dmg
   
   # 下載完成後校驗
   shasum -a 256 ~/Downloads/ClashX.dmg

4. 使用 GitHub 鏡像：如果直接存取 GitHub 速度較慢，可以嘗試 CDN 加速連結

常見問題 (FAQ)

Q: ClashX 和 ClashX Pro 安裝失敗的解決方法一樣嗎？

A: 基本一致。兩者使用相同的 Helper 工具和系統權限機制，本文所有方法均適用於 ClashX 和 ClashX Pro。

Q: M1/M2/M3 Mac 安裝 ClashX 需要 Rosetta 嗎？

A: 最新版 ClashX 已原生支援 Apple Silicon，無需 Rosetta。如果你使用較舊版本，可以安裝 Rosetta 以相容：

softwareupdate --install-rosetta --agree-to-license

Q: 執行 sudo 指令時提示「Operation not permitted」怎麼辦？

A: 這通常與 macOS SIP（系統完整性保護）有關。對於 xattr 和 codesign 指令，正常情況下不需要關閉 SIP。如果仍有問題，請檢查終端機是否有「完整磁碟存取權限」（系統偏好設定 → 安全性與隱私 → 隱私 → 完整磁碟存取權限）。

Q: 安裝成功後 ClashX 無法啟動怎麼辦？

A: 請參考我們的 ClashX 連線逾時排查指南，其中包含啟動失敗和連線問題的詳細排查步驟。

Q: 多次嘗試仍然無法安裝，還有什麼辦法？

A: 建議按以下順序排查：

1. 重新啟動 Mac 後再試
2. 建立新的管理員帳號測試安裝
3. 在 macOS 安全模式下嘗試安裝
4. 到 GitHub Issues 搜尋或提交問題