网络

curl 退出代码（exit code）对照表

汇总 curl 命令返回的 exit code（退出代码）含义、常见原因和解决方法，是调试 CI/CD 流水线和 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 次）的正规重定向链时发生。

使用提示

  • 可以在命令执行后立即用 $?（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。

常见问题

执行 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」。如今 curl 几乎已成为所有 Linux 发行版、macOS 以及 Windows 10 及以上版本的标配工具，是 Web 开发者最基础的工具之一。

exit code 体系与 libcurl 内部的错误枚举类型 CURLcode 一一对应，从 `CURLE_OK`（成功，exit code 0）开始按顺序编号定义。之所以存在编号缺口，是因为在开发过程中有部分错误代码被废弃或合并。

有趣的是，curl 的 exit code 拥有独立于 POSIX 一般惯例（0=成功，1=一般错误）的自有体系。因此在 Shell 脚本中需要横向处理多个命令的 exit code 时，必须分别查阅各工具的手册来确认其含义。

同类工具