curl exit code / 返回代码大全（1-99）：按编号查询含义与修复方法

按编号或名称快速查询任意 curl exit code（退出代码 / 返回代码，1-99），包括 22、3、28、52 等。清晰说明含义、常见原因和具体修复方法，可作为官方文档的速查替代，适用于 CI/CD、cron 任务和 Shell 脚本调试。

最后更新: 2026-09-03

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 时，不能想当然地套用同一套规则，而必须分别查阅各工具自己的手册来确认具体含义——这正是本页面这类速查表存在的意义所在。

查看全部趣味知识