curl 錯誤代碼：完整參考

Q: 如何檢查 curl 退出碼？

執行 curl 指令後，退出碼儲存在 shell 的特殊變數中。在 Bash/Zsh 中，在 curl 指令後立即執行 echo $?。在 PowerShell 中，使用 $LASTEXITCODE。在腳本中，您可以使用條件判斷檢查：if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi。退出碼 0 表示成功；其他任何數字表示錯誤。要同時查看 HTTP 狀態碼和 curl 退出碼，可以組合使用 curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?"。請注意，curl 的退出碼與 HTTP 狀態碼不同——除非使用 --fail 旗標，否則 curl 即使遇到 HTTP 404 也會傳回 0。

Q: 如何修復 curl 錯誤 28（操作逾時）？

錯誤 28 表示請求超過了最大允許時間。首先，增加逾時時間：curl --connect-timeout 30 --max-time 120 URL。--connect-timeout 限制 TCP 連線階段，而 --max-time 限制整個操作。接下來，使用 curl -v URL 診斷瓶頸——詳細輸出會顯示 curl 卡在哪裡（DNS、連線、TLS 或傳輸）。常見修復方法：檢查您的網路連線和 DNS 設定，確認伺服器正在回應（ping 和 telnet），使用 --noproxy '*' 繞過代理，對於大檔案下載可加入 --retry 3 --retry-delay 5 進行自動重試。

Q: 如何修復 curl SSL 憑證錯誤（錯誤 60）？

錯誤 60 表示 curl 無法驗證伺服器的 SSL 憑證。修復方法取決於原因。對於 CA 套件已過時：從 https://curl.se/ca/cacert.pem 下載最新套件並使用 curl --cacert /path/to/cacert.pem URL。對於 Docker 容器：安裝 ca-certificates 套件（apt-get install ca-certificates）。對於開發環境中的自簽憑證：使用 curl -k URL 跳過驗證——但永遠不要在生產環境中使用 -k，因為它會停用所有憑證檢查。診斷方法：執行 openssl s_client -connect host:443 -showcerts 以檢查憑證鏈。如果憑證已過期或主機名稱不匹配，問題出在伺服器端。

Q: curl 錯誤 7（連線失敗）是什麼意思？

錯誤 7 表示 curl 已將主機名稱解析為 IP 位址，但無法建立 TCP 連線。伺服器主動拒絕了連線，或連線嘗試在網路層級逾時。常見原因：服務未在目標主機上執行（使用 systemctl status 或 docker ps 檢查）、防火牆阻擋了連接埠（使用 telnet host port 測試）、您使用了錯誤的連接埠（例如 80 而不是 443，或開發伺服器使用 8080），或伺服器在高負載下監聽佇列已滿。除錯方法：使用 curl -v URL 並在輸出中查找「Connected to」或「Connection refused」。

當 curl 指令失敗時，它會傳回一個數字退出碼（也稱為 curl 錯誤代碼），用於識別錯誤類型。您可以在 curl 指令後立即執行 echo $?（或在 PowerShell 中使用 $LASTEXITCODE）來檢查 curl 退出碼。退出碼 0 表示成功；其他任何數字表示特定問題——從 DNS 解析失敗和連線逾時到 SSL 憑證問題。本頁是最常見 curl 錯誤代碼的完整參考，包含解釋、原因和修復方法。如果您在程式碼中使用 curl 指令，可以將它們貼到 curl2code 中轉換為您選擇的程式語言。

快速參考表

退出碼	錯誤名稱	描述
0	CURLE_OK	成功。操作已完成，沒有任何錯誤。
1	CURLE_UNSUPPORTED_PROTOCOL	不支援的協定。URL 使用了 curl 未內建支援的協定。
3	CURLE_URL_MALFORMAT	URL 格式錯誤。URL 語法無效或無法解析。
5	CURLE_COULDNT_RESOLVE_PROXY	無法解析代理伺服器。指定的代理伺服器主機名稱無法解析。
6	CURLE_COULDNT_RESOLVE_HOST	DNS 查詢失敗——主機名稱無法解析為 IP 位址。
7	CURLE_COULDNT_CONNECT	TCP 連線失敗——伺服器已停止、連接埠被阻擋或防火牆拒絕連線。
18	CURLE_PARTIAL_FILE	檔案不完整。傳輸被中斷，僅收到部分檔案。
22	CURLE_HTTP_RETURNED_ERROR	伺服器回傳 HTTP 錯誤（4xx/5xx）且使用了 --fail 旗標。
23	CURLE_WRITE_ERROR	寫入錯誤。curl 無法將收到的資料寫入磁碟（權限被拒或磁碟已滿）。
28	CURLE_OPERATION_TIMEDOUT	操作超過了最大允許時間（DNS、連線或傳輸）。
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS 交握失敗——協定版本或加密套件不匹配。
37	CURLE_FILE_COULDNT_READ_FILE	無法讀取檔案。請求中引用的本地檔案無法開啟或讀取。
52	CURLE_GOT_NOTHING	伺服器回覆為空。伺服器在未傳送任何資料的情況下關閉了連線。
56	CURLE_RECV_ERROR	連線被重設——伺服器在資料傳輸過程中中斷了連線。
60	CURLE_SSL_CACERT	SSL 憑證驗證失敗——已過期、自簽或 CA 套件已過時。
77	CURLE_SSL_CACERT_BADFILE	SSL CA 憑證問題。無法讀取或解析指定的 CA 憑證檔案。
92	CURLE_HTTP2_STREAM	HTTP/2 串流錯誤。傳輸過程中發生了 HTTP/2 協定層級的串流錯誤。

0CURLE_OK

成功。操作已完成，沒有任何錯誤。

1CURLE_UNSUPPORTED_PROTOCOL

不支援的協定。URL 使用了 curl 未內建支援的協定。

3CURLE_URL_MALFORMAT

URL 格式錯誤。URL 語法無效或無法解析。

5CURLE_COULDNT_RESOLVE_PROXY

無法解析代理伺服器。指定的代理伺服器主機名稱無法解析。

6CURLE_COULDNT_RESOLVE_HOST

DNS 查詢失敗——主機名稱無法解析為 IP 位址。

7CURLE_COULDNT_CONNECT

TCP 連線失敗——伺服器已停止、連接埠被阻擋或防火牆拒絕連線。

18CURLE_PARTIAL_FILE

檔案不完整。傳輸被中斷，僅收到部分檔案。

22CURLE_HTTP_RETURNED_ERROR

伺服器回傳 HTTP 錯誤（4xx/5xx）且使用了 --fail 旗標。

23CURLE_WRITE_ERROR

寫入錯誤。curl 無法將收到的資料寫入磁碟（權限被拒或磁碟已滿）。

28CURLE_OPERATION_TIMEDOUT

操作超過了最大允許時間（DNS、連線或傳輸）。

35CURLE_SSL_CONNECT_ERROR

SSL/TLS 交握失敗——協定版本或加密套件不匹配。

37CURLE_FILE_COULDNT_READ_FILE

無法讀取檔案。請求中引用的本地檔案無法開啟或讀取。

52CURLE_GOT_NOTHING

伺服器回覆為空。伺服器在未傳送任何資料的情況下關閉了連線。

56CURLE_RECV_ERROR

連線被重設——伺服器在資料傳輸過程中中斷了連線。

60CURLE_SSL_CACERT

SSL 憑證驗證失敗——已過期、自簽或 CA 套件已過時。

77CURLE_SSL_CACERT_BADFILE

SSL CA 憑證問題。無法讀取或解析指定的 CA 憑證檔案。

92CURLE_HTTP2_STREAM

HTTP/2 串流錯誤。傳輸過程中發生了 HTTP/2 協定層級的串流錯誤。

錯誤 6：無法解析主機

含義: 您的終端機顯示 curl: (6) Could not resolve host。curl 無法將主機名稱解析為 IP 位址——DNS 查詢在任何連線嘗試之前就已失敗。
原因: 最常見的原因是：主機名稱拼寫錯誤（例如 curl https://apiexample.com 而不是 api.example.com）、DNS 伺服器問題（您設定的 DNS 停止運作或無法連線）、無網路連線（Wi-Fi 已斷開、VPN 未連線），或網域確實不存在。
修復方法: 首先，確認 URL 是否正確。然後直接測試 DNS 解析：nslookup api.example.com 或 dig api.example.com。如果 DNS 失敗，嘗試使用不同的 DNS 伺服器：curl --dns-servers 8.8.8.8 https://api.example.com。檢查您的 /etc/resolv.conf 或網路設定。如果在企業 VPN 後面，確保內部 DNS 能解析該主機。

$ curl https://api.exmple.com/users

錯誤 7：連線失敗

含義: 您的終端機顯示 curl: (7) Failed to connect to host port: Connection refused。curl 已解析主機名稱但無法建立到伺服器的 TCP 連線——連線被主動拒絕或在 TCP 層級逾時。
原因: 常見原因包括：伺服器已停止或未執行、防火牆阻擋了連接埠（檢查本地和伺服器端防火牆）、連接埠錯誤（例如服務在 8080 執行但您連線到 443），或伺服器在高負載下監聽佇列已滿。
修復方法: 確認伺服器正在執行：ping api.example.com 和 telnet api.example.com 443。檢查正確的連接埠是否開啟：nmap -p 443 api.example.com。暫時停用本地防火牆進行測試。如果使用 Docker，確保容器連接埠已發布。嘗試使用詳細模式：curl -v https://api.example.com 以查看連線在哪裡失敗。

$ curl https://localhost:8080/api

錯誤 22：HTTP 回傳錯誤

含義: 您的終端機顯示 curl: (22) The requested URL returned error。伺服器回傳了 HTTP 錯誤狀態碼（4xx 或 5xx），且 curl 使用了 -f 或 --fail，這告訴 curl 將 HTTP 錯誤視為失敗。
原因: 此錯誤由 HTTP 狀態碼觸發，如 400（錯誤請求）、401（未授權）、403（禁止存取）、404（找不到）或 500（內部伺服器錯誤）——但僅在使用 --fail 時。沒有 --fail，curl 即使遇到 HTTP 錯誤也會以代碼 0 退出。常見原因：URL 錯誤、缺少驗證、權限不足或伺服器端錯誤。
修復方法: 不加 --fail 執行 curl 以查看完整回應主體——它通常包含實際的錯誤訊息。檢查 HTTP 狀態碼：curl -w "%{http_code}" -o /dev/null -s URL。對於 401/403：驗證您的授權令牌或 API 金鑰。對於 404：仔細檢查 URL 路徑。對於 500：問題出在伺服器端。

$ curl --fail https://api.example.com/nonexistent

錯誤 28：操作逾時

含義: 您的終端機顯示 curl: (28) Operation timed out 或 curl: (28) Connection timed out。操作時間超過了允許的時間。這是最常見的 curl 錯誤——可能發生在 DNS 解析、TCP 連線、SSL 交握或資料傳輸期間。
原因: 典型原因包括：伺服器緩慢或過載未能及時回應、網路擁塞或封包遺失、防火牆靜默丟棄封包（無拒絕，只有沈默）、使用 --connect-timeout 或 --max-time 設定了過於嚴格的逾時值，或代理伺服器配置錯誤導致延遲。
修復方法: 增加逾時時間：curl --connect-timeout 30 --max-time 120 URL。使用詳細模式查看卡在哪裡：curl -v URL。測試網路延遲：ping api.example.com 和 traceroute api.example.com。如果在代理伺服器後面，嘗試繞過它：curl --noproxy '*' URL。對於大檔案傳輸，考慮使用 --retry 3 搭配 --retry-delay 5。

$ curl --connect-timeout 5 https://slow-api.example.com/data

錯誤 35：SSL 連線錯誤

含義: 您的終端機顯示 curl: (35) SSL connect error。SSL/TLS 交握失敗——curl 無法與伺服器建立安全連線。
原因: 常見原因：TLS 版本不匹配（伺服器需要 TLS 1.3 但您的 curl 僅支援到 TLS 1.2）、加密套件不相容、伺服器 SSL 配置錯誤（交握期間提供了過期憑證、憑證鏈不完整）、伺服器在指定連接埠上實際不支援 HTTPS，或代理或防火牆正在攔截 SSL 連線（中間人攻擊）。
修復方法: 強制使用特定 TLS 版本：curl --tlsv1.2 URL 或 curl --tlsv1.3 URL。檢查伺服器支援什麼：openssl s_client -connect api.example.com:443。將 curl 和 OpenSSL 更新到最新版本。如果伺服器使用自簽憑證，這通常是錯誤 60——錯誤 35 通常表示協定層級的交握失敗。

$ curl https://legacy-server.example.com/api

錯誤 56：接收失敗——連線被重設

含義: 您的終端機顯示 curl: (56) Recv failure: Connection reset by peer。連線已成功建立，但資料接收失敗——伺服器在傳輸過程中意外關閉或重設了連線。
原因: 這通常發生在：伺服器在傳輸中途當機或重啟、負載平衡器或代理丟棄連線（閒置逾時、請求過大）、防火牆終止長時間連線、伺服器的 keep-alive 逾時時間比預期短，或客戶端與伺服器之間存在網路中斷。
修復方法: 再次嘗試請求——暫時性網路問題是最常見的原因。使用詳細模式：curl -v URL 以查看確切的失敗點。如果在大檔案上傳時出現錯誤，嘗試分塊傳輸：curl -H "Transfer-Encoding: chunked" URL。對於顯示 RPC failed; curl 56 的 Git 操作，增加緩衝區：git config http.postBuffer 524288000。

$ curl https://api.example.com/large-download

錯誤 60：SSL 憑證問題

含義: 您的終端機顯示 curl: (60) SSL certificate problem: unable to get local issuer certificate。curl 無法根據其 CA（憑證授權單位）套件驗證伺服器的 SSL 憑證。TLS 交握在協定層級完成，但憑證驗證失敗。
原因: 最常見的原因：伺服器使用自簽憑證、憑證已過期、憑證鏈不完整（缺少中繼憑證）、curl 的 CA 套件已過時（常見於舊系統或 Docker 容器中），或憑證的通用名稱 / SAN 與請求的主機名稱不匹配。
修復方法: 更新 CA 套件：curl --cacert /path/to/cacert.pem URL。從 https://curl.se/ca/cacert.pem 下載更新的套件。診斷方法：openssl s_client -connect api.example.com:443 -showcerts。對於開發環境中的自簽憑證，使用 curl -k URL（永遠不要在生產環境中使用——它會停用所有憑證驗證）。在 Docker 中，安裝 ca-certificates 套件。

$ curl https://self-signed.example.com/api

其他錯誤代碼

退出碼	錯誤名稱	描述
0	CURLE_OK	成功。操作已完成，沒有任何錯誤。
1	CURLE_UNSUPPORTED_PROTOCOL	不支援的協定。URL 使用了 curl 未內建支援的協定。
3	CURLE_URL_MALFORMAT	URL 格式錯誤。URL 語法無效或無法解析。
5	CURLE_COULDNT_RESOLVE_PROXY	無法解析代理伺服器。指定的代理伺服器主機名稱無法解析。
18	CURLE_PARTIAL_FILE	檔案不完整。傳輸被中斷，僅收到部分檔案。
23	CURLE_WRITE_ERROR	寫入錯誤。curl 無法將收到的資料寫入磁碟（權限被拒或磁碟已滿）。
37	CURLE_FILE_COULDNT_READ_FILE	無法讀取檔案。請求中引用的本地檔案無法開啟或讀取。
52	CURLE_GOT_NOTHING	伺服器回覆為空。伺服器在未傳送任何資料的情況下關閉了連線。
77	CURLE_SSL_CACERT_BADFILE	SSL CA 憑證問題。無法讀取或解析指定的 CA 憑證檔案。
92	CURLE_HTTP2_STREAM	HTTP/2 串流錯誤。傳輸過程中發生了 HTTP/2 協定層級的串流錯誤。

0CURLE_OK

成功。操作已完成，沒有任何錯誤。

1CURLE_UNSUPPORTED_PROTOCOL

不支援的協定。URL 使用了 curl 未內建支援的協定。

3CURLE_URL_MALFORMAT

URL 格式錯誤。URL 語法無效或無法解析。

5CURLE_COULDNT_RESOLVE_PROXY

無法解析代理伺服器。指定的代理伺服器主機名稱無法解析。

18CURLE_PARTIAL_FILE

檔案不完整。傳輸被中斷，僅收到部分檔案。

23CURLE_WRITE_ERROR

寫入錯誤。curl 無法將收到的資料寫入磁碟（權限被拒或磁碟已滿）。

37CURLE_FILE_COULDNT_READ_FILE

無法讀取檔案。請求中引用的本地檔案無法開啟或讀取。

52CURLE_GOT_NOTHING

伺服器回覆為空。伺服器在未傳送任何資料的情況下關閉了連線。

77CURLE_SSL_CACERT_BADFILE

SSL CA 憑證問題。無法讀取或解析指定的 CA 憑證檔案。

92CURLE_HTTP2_STREAM

HTTP/2 串流錯誤。傳輸過程中發生了 HTTP/2 協定層級的串流錯誤。

如何除錯 curl 錯誤

當 curl 失敗時，這三個旗標可以幫助您快速找出根本原因——從 DNS 解析到 SSL 交握再到回應內容。

1
啟用詳細輸出
執行 curl -v URL 以查看完整的請求/回應過程：DNS 解析、TCP 連線、TLS 交握、已傳送的請求標頭和已接收的回應標頭。這是最有用的除錯旗標。
2
檢查 HTTP 狀態碼
執行 curl -o /dev/null -s -w "%{http_code}" URL 以僅獲取 HTTP 狀態碼（200、404、500 等），不含回應主體。適用於快速健康檢查和腳本編寫。
3
靜默顯示錯誤
執行 curl -sS URL 以抑制進度條（-s）但仍顯示錯誤（-S）。非常適合需要乾淨輸出但需要捕捉失敗的腳本。

常見問題

如何檢查 curl 退出碼？

執行 curl 指令後，退出碼儲存在 shell 的特殊變數中。在 Bash/Zsh 中，在 curl 指令後立即執行 echo $?。在 PowerShell 中，使用 $LASTEXITCODE。在腳本中，您可以使用條件判斷檢查：if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi。退出碼 0 表示成功；其他任何數字表示錯誤。要同時查看 HTTP 狀態碼和 curl 退出碼，可以組合使用 curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?"。請注意，curl 的退出碼與 HTTP 狀態碼不同——除非使用 --fail 旗標，否則 curl 即使遇到 HTTP 404 也會傳回 0。

如何修復 curl 錯誤 28（操作逾時）？

錯誤 28 表示請求超過了最大允許時間。首先，增加逾時時間：curl --connect-timeout 30 --max-time 120 URL。--connect-timeout 限制 TCP 連線階段，而 --max-time 限制整個操作。接下來，使用 curl -v URL 診斷瓶頸——詳細輸出會顯示 curl 卡在哪裡（DNS、連線、TLS 或傳輸）。常見修復方法：檢查您的網路連線和 DNS 設定，確認伺服器正在回應（ping 和 telnet），使用 --noproxy '*' 繞過代理，對於大檔案下載可加入 --retry 3 --retry-delay 5 進行自動重試。

如何修復 curl SSL 憑證錯誤（錯誤 60）？

錯誤 60 表示 curl 無法驗證伺服器的 SSL 憑證。修復方法取決於原因。對於 CA 套件已過時：從 https://curl.se/ca/cacert.pem 下載最新套件並使用 curl --cacert /path/to/cacert.pem URL。對於 Docker 容器：安裝 ca-certificates 套件（apt-get install ca-certificates）。對於開發環境中的自簽憑證：使用 curl -k URL 跳過驗證——但永遠不要在生產環境中使用 -k，因為它會停用所有憑證檢查。診斷方法：執行 openssl s_client -connect host:443 -showcerts 以檢查憑證鏈。如果憑證已過期或主機名稱不匹配，問題出在伺服器端。

curl 錯誤 7（連線失敗）是什麼意思？

錯誤 7 表示 curl 已將主機名稱解析為 IP 位址，但無法建立 TCP 連線。伺服器主動拒絕了連線，或連線嘗試在網路層級逾時。常見原因：服務未在目標主機上執行（使用 systemctl status 或 docker ps 檢查）、防火牆阻擋了連接埠（使用 telnet host port 測試）、您使用了錯誤的連接埠（例如 80 而不是 443，或開發伺服器使用 8080），或伺服器在高負載下監聽佇列已滿。除錯方法：使用 curl -v URL 並在輸出中查找「Connected to」或「Connection refused」。