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 状态码不同——即使是 HTTP 404，curl 也返回 0，除非您使用了 --fail 标志。

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 $? 来检查 curl 退出码（在 PowerShell 中使用 $LASTEXITCODE）。退出码 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 时，即使出现 HTTP 错误，curl 也会以退出码 0 退出。常见原因：URL 错误、缺少身份验证、权限不足或服务器端 Bug。
修复方法: 不使用 --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。连接已成功建立，但数据接收失败——服务器在传输过程中意外关闭或重置了连接。
原因: 这通常发生在以下情况：服务器在传输过程中崩溃或重启、负载均衡器或代理断开连接（空闲超时、请求过大）、防火墙终止长连接、服务器的保活超时时间比预期短，或者客户端与服务器之间存在网络中断。
修复方法: 重试请求——临时网络问题是最常见的原因。使用详细模式：curl -v URL 查看确切的失败点。如果在大文件上传时出现错误，尝试分块传输：curl -H "Transfer-Encoding: chunked" URL。对于 Git 操作中出现的 RPC failed; curl 56，增加缓冲区：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 状态码不同——即使是 HTTP 404，curl 也返回 0，除非您使用了 --fail 标志。

如何修复 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"。