curl exit code / 返回碼大全（1-99）：按編號查詢含義與修復方法

按編號或名稱快速查詢任意 curl exit code（退出碼 / 返回碼，1-99），包括 22、3、28、52 等。清楚說明含義、常見原因和具體修復方法，可作為官方文件的速查替代，適用於 CI/CD、cron 任務和 Shell 指令碼除錯。

curl exit code 對照表

程式碼	常量名	含義	常見原因
連線・初始化錯誤
1	CURLE_UNSUPPORTED_PROTOCOL	表示 curl 不支援 URL 中指定的協議。	使用了編譯時停用該協議（如 gopher、ldap）的 curl 二進位制檔案，或 URL 協議部分拼寫錯誤。
2	CURLE_FAILED_INIT	表示 curl 的內部初始化失敗。	記憶體不足或環境異常等極少發生的底層初始化失敗。
3	CURLE_URL_MALFORMAT	表示指定的 URL 格式不正確，curl 無法解析。	URL 缺少協議字首（如遺漏 http://）或包含非法字元時發生。
5	CURLE_COULDNT_RESOLVE_PROXY	表示 curl 未能解析指定代理伺服器的主機名。	--proxy 指定的主機名拼寫錯誤，或代理專用 DNS 無法完成名稱解析。
6	CURLE_COULDNT_RESOLVE_HOST	表示 curl 未能解析（DNS）目標主機的主機名。	典型原因是域名拼寫錯誤、DNS 伺服器故障，或在離線環境中執行命令。
7	CURLE_COULDNT_CONNECT	表示已完成名稱解析，但 curl 未能與伺服器建立 TCP 連線。	埠號錯誤、被防火牆攔截，或伺服器處於宕機狀態時發生。
8	CURLE_WEIRD_SERVER_REPLY	表示 curl 收到了伺服器返回的無法解釋的異常格式響應。	FTP 伺服器返回非標準響應，或誤連到使用不同協議的伺服器時容易發生。
9	CURLE_REMOTE_ACCESS_DENIED	表示已連線到伺服器，但訪問被拒絕。	FTP 目錄許可權不足，或觸發了伺服器端的 IP 限制時發生。
資料傳輸錯誤
18	CURLE_PARTIAL_FILE	表示傳輸在完成前被中斷，檔案只接收了一部分。	網路瞬斷，或伺服器在到達預告的 Content-Length 之前提前斷開連線時發生。
23	CURLE_WRITE_ERROR	表示向本地磁碟或回撥目標寫入資料失敗。	磁碟空間不足，或對輸出檔案沒有寫入許可權時發生。
26	CURLE_READ_ERROR	表示讀取待上傳的本地檔案失敗。	-T/--upload-file 指定的檔案不存在，或沒有讀取許可權時發生。
52	CURLE_GOT_NOTHING	表示已連線到伺服器，但完全沒有收到任何響應。	典型原因是伺服器程序在請求過程中崩潰，或配置不當導致返回空響應。
55	CURLE_SEND_ERROR	表示向網路傳送資料失敗。	連線建立後對方立即斷開，或本地網路接口出現異常時發生。
56	CURLE_RECV_ERROR	表示從網路接收資料失敗。	通訊過程中對方意外重置連線（Connection reset by peer）時較為常見。
63	CURLE_FILESIZE_EXCEEDED	表示檔案大小超過了 --max-filesize 指定的上限。	獲取的響應比預期更大，觸發了為安全起見設定的上限時發生。
78	CURLE_REMOTE_FILE_NOT_FOUND	表示遠端伺服器上不存在指定的檔案（如 FTP）。	FTP 路徑拼寫錯誤，或目標檔案已被刪除或移動時發生。
SSL/TLS 證書錯誤
35	CURLE_SSL_CONNECT_ERROR	表示在 SSL/TLS 握手過程中出現問題，未能建立連線。	伺服器與客戶端支援的 TLS 版本・加密套件不一致時容易發生。
51	CURLE_PEER_FAILED_VERIFICATION	表示伺服器證書驗證失敗（例如證書內容與主機名不匹配等）。	訪問自簽名證書，或證書的 Common Name / SAN 與目標主機名不一致時發生。
58	CURLE_SSL_CERTPROBLEM	表示本地指定的客戶端證書存在問題。	--cert 指定的證書檔案格式不正確，或密碼短語輸入錯誤是典型原因。
60	CURLE_SSL_CACERT	表示無法確認用於驗證伺服器證書的 CA 證書鏈。	CA 證書包過舊，或企業代理等使用的自簽名 CA 未註冊到信任庫時發生。雖然可用 -k/--insecure 規避，但不建議在生產環境中使用。
HTTP・認證錯誤
22	CURLE_HTTP_RETURNED_ERROR	表示在指定 -f/--fail 選項時，HTTP 響應返回了 400 以上的錯誤狀態碼。	在 CI/CD 指令碼中使用 curl -f，以便在 API 返回錯誤狀態時將其檢測為失敗。
67	CURLE_LOGIN_DENIED	表示伺服器拒絕了登入（認證）請求。	使用者名稱或密碼錯誤，或 FTP/SMTP 等賬戶被鎖定是典型原因。
其他
27	CURLE_OUT_OF_MEMORY	表示 curl 在執行過程中記憶體分配失敗。	在記憶體不足的環境中處理超大檔案等罕見情況下發生。
28	CURLE_OPERATION_TIMEDOUT	表示操作未能在 --connect-timeout/--max-time 等指定的時間限制內完成。	伺服器響應緩慢、網路延遲，或超時值設定過短時發生，是 CI 中最常見的錯誤之一。
47	CURLE_TOO_MANY_REDIRECTS	表示重定向次數超過了 --max-redirs 指定的上限。	重定向迴圈（301/302 迴圈跳轉），或超過預設上限（50 次）的正規重定向鏈時發生。

什麼是 curl exit code？

curl exit code（退出碼）是 curl 指令執行結束後回傳給 shell 的數字（可透過 $? 查看），表示請求是否成功，若失敗則說明原因。與伺服器回傳的 HTTP 狀態碼不同，exit code 描述的是 curl 指令本身的執行結果，例如 DNS 解析失敗、連線逾時、SSL 交握錯誤等。

本工具只需輸入代碼編號（1-99）即可查詢含義與常見原因，也可以依編號、常數名稱或關鍵字篩選完整對照表。適用於排查 CI/CD 流水線、cron 工作或 Shell 指令碼中呼叫 API、下載檔案時 curl 失敗的原因。

使用方法

輸入 exit code 編號將 curl 指令失敗後透過 echo $? 取得的編號輸入查詢框。
查看含義與常見原因工具會顯示該代碼所代表的含義，以及通常會觸發它的情況。
在對照表中篩選查找若不確定具體編號，可用關鍵字篩選完整對照表來找出對應代碼。
參考修復建議結合常見原因，對指令碼或環境進行相應的修復。

用好本工具的小技巧

可以在命令執行後立即用 $?（Bash）或 %errorlevel%（Windows）檢視 exit code。在 Shell 指令碼中使用 curl ... || echo "failed with $?" 這樣的寫法便於分支處理。
28（超時）與 7（連線失敗）容易混淆，區別在於：28 是連線建立後響應緩慢，7 是根本無法建立 TCP 連線本身。
出現 60（CA 證書錯誤）時不要輕易用 -k/--insecure 規避，應先確認 CA 證書包（ca-certificates）是否為最新版本。在生產環境中長期使用 -k 會增加中間人攻擊的風險。
22（HTTP 錯誤）只會在添加了 -f/--fail 選項時出現。若不新增，即使收到 404 或 500，curl 也會返回 exit code 0（成功），因此在 CI 中若想檢測失敗，務必新增 -f。

應用情境

排查 CI/CD 流水線失敗

只需查詢建置紀錄中記錄的 exit code，即可快速定位以 curl 執行的部署或健康檢查失敗的原因。

診斷 cron 工作的靜默失敗

cron 工作通常沒有輸出，查看紀錄中的 exit code 往往是定位原因最快的方式。

設計穩健的 Shell 指令碼錯誤處理

區分可重試的暫時性網路錯誤與重試也無法解決的永久性錯誤，據此設計指令碼的分支邏輯。

事故復盤分析

在事故處理後回顧紀錄時，能準確確認屬於 DNS、TLS 還是逾時哪一類失敗。

學習 curl 與網路基礎知識

借助對照表系統性了解一次傳輸的哪個階段（解析、連線、TLS、傳輸）可能出錯。

術語解釋

exit code（退出碼）: 程式結束時回傳給 shell 的數字。0 表示成功，curl 使用 1-99 表示具體的失敗類型。
CURLcode: libcurl 內部定義各類錯誤的列舉型別，curl 指令列的 exit code 直接對應此列舉。
libcurl: 實作 curl 核心傳輸邏輯的 C 語言函式庫，curl 指令列工具只是對它的一層薄封裝。
--fail / -f 選項: 當 HTTP 回傳錯誤狀態（400 以上）時，讓 curl 回傳 exit code 22 而非預設 exit code 0 的選項。
逾時與連線被拒的差異: 逾時（28）指在限定時間內未收到回應；連線被拒/失敗（7）指 TCP 連線本身未能建立。
DNS 解析: 將主機名稱轉換為 IP 位址的過程，一旦失敗 curl 會回傳 exit code 6。
SSL/TLS 交握: 客戶端與伺服器建立加密連線的協商過程，此階段的問題通常對應 exit code 35、51、58 或 60。

常見問題

執行 curl 命令後，可在 Bash/Zsh 中用 echo $?、在 Windows 命令提示符中用 echo %errorlevel%、在 PowerShell 中用 $LASTEXITCODE 檢視。

首先重新檢查 --connect-timeout 和 --max-time 的設定值，必要時適當延長。如果伺服器響應長期緩慢，也應確認伺服器負載狀況和網路路徑（代理、VPN 等）。

兩者不同。HTTP 狀態碼（如 404、500）是伺服器返回的協議層響應，而 curl exit code 表示 curl 命令本身的執行結果（連線失敗、超時等）。curl 預設將 HTTP 錯誤也視為 exit code 0（成功），因此需注意不要混淆兩者。

新增 curl -f（--fail）選項後，當 HTTP 響應為 400 以上時會返回 exit code 22。如果不新增該選項，即便只是成功獲取了一個錯誤頁面，exit code 也會是 0。

6（COULDNT_RESOLVE_HOST）是在 DNS 階段無法將主機名解析為 IP 地址的錯誤，7（COULDNT_CONNECT）則是名稱解析成功後，未能與該 IP 地址建立 TCP 連線的錯誤。

閒話 ― curl exit code 體系

curl 是由 Daniel Stenberg 於 1996 年開始開發的命令列工具，最初名字樸素得很，就叫「httpget」。誰也沒想到，這個當初為了抓取網頁而寫的小工具，如今幾乎已經成了所有 Linux 發行版、macOS 以及 Windows 10 及以上版本的標配，也順理成章地成為了 Web 開發者最基礎、最離不開的工具之一。

正因為 curl 承擔著如此繁重的網路通訊任務，它的 exit code 體系也設計得相當細緻——每一個編號都與 libcurl 內部的錯誤列舉型別 CURLcode 一一對應，從 CURLE_OK（成功，exit code 0）開始按順序編號定義。仔細查閱就會發現這套編號裡存在一些缺口，這是因為在漫長的開發歷程中，有部分錯誤程式碼被廢棄或者合併進了其他程式碼，留下的空位就這樣一直保留至今。

有趣的是，curl 的 exit code 並沒有沿用 POSIX 的一般慣例（0 表示成功，1 表示籠統的一般錯誤），而是發展出了一套完全屬於自己的獨立體系。這也意味著，在 Shell 指令碼中需要橫向處理多個命令的 exit code 時，不能想當然地套用同一套規則，而必須分別查閱各工具自己的手冊來確認具體含義——這正是本頁面這類速查表存在的意義所在。

檢視全部趣味知識