第一次在服务器上敲 curl我猜大部分人的经历都差不多照着某篇教程复制了一行curl -fsSL https://xxx/install.sh | sh回车装完了然后就把这个命令丢进收藏夹吃灰。直到某天接口联调发现返回是空的、下载脚本卡在证书报错、自动化构建里那行 curl 悄悄失败了却没人发现才反应过来这个看起来简单的命令其实有一整套行为逻辑没搞明白。curl 属于 Linux 常用命令里那种用得最多、懂得最少的典型代表它既是下载工具又是 HTTP 客户端还是排错探针三种身份混在一个二进制文件里。这篇内容就是把我这几年在运维、接口调试、CI 流程里踩过的 curl 相关的坑整理一遍从最基础的方法和头部构造一路讲到证书报错、错误码定位、脚本化落地适合刚接触 Linux 的朋友也适合已经用了一两年但没系统梳理过的同学看完至少能做到一件事报错信息摆在面前知道下一步该查哪里。1. 从一条安装脚本拆起curl 在真实环境里解决什么问题很多人对 curl 的第一印象来自各种官方安装脚本那条长长的命令看起来像咒语其实每个字母都有明确含义。把这条命令拆开看是理解 curl 设计哲学最快的入口也是后面所有参数组合的基础。1.1 安装脚本为什么普遍写成 curl -fsSL URL | shcurl -fsSL https://example.com/install.sh | sh这行命令里塞了四个短选项它们分别解决四个不同的问题。-f表示遇到 HTTP 错误状态码4xx、5xx时不要输出响应体直接以非零退出码结束这一条极其关键——如果没有-f服务器返回一个 404 的 HTML 错误页管道后面的 sh 会认认真真地尝试执行这段 HTML结果就是一堆莫名其妙的语法错误让人完全找不到方向。-s是静默模式关掉进度条和统计信息避免这些内容混进管道污染脚本内容。-S是配合-s使用的意思是静默但不隐藏错误当出错时仍然把错误信息打到标准错误。-L是跟随重定向很多下载地址会先返回 301 或 302 跳到 CDN没有-L就只能拿到一个空响应。把这四个拼起来读就是下载时安静点但真出错了要告诉我遇到跳转要跟过去HTTP 状态不对就直接失败。这套组合几乎可以当作所有下载后立即使用场景的默认模板。我自己写脚本时只要是拉配置、拉密钥、拉脚本一律用-fsSL很少例外。注意管道执行远程脚本这件事本身有风险脚本内容在传输前你并没有看过。稳妥的做法是先curl -fsSL url -o /tmp/install.sh用less或head看一眼关键部分确认无误再sh /tmp/install.sh。多花十秒钟能避免很多尴尬。1.2 curl 和 wget 的分工与取舍新手常见的困惑是这两个工具到底该用哪个。简单说wget 的设计目标是递归下载整个网站擅长镜像、断点续传、批量抓取curl 的设计目标是构造并发送一个 HTTP 请求擅长自定义方法、请求头、请求体、认证方式。所以你会发现两个现象写接口调试脚本的人几乎只用 curl做爬取或备份静态资源的人偏爱 wget。在容器镜像里这个区别更明显。很多精简基础镜像比如 alpine默认只带 curl 不带 wget也有些镜像反过来。所以写 Dockerfile 的时候别想当然地认为两个都在要么显式安装要么统一用同一个工具。我自己在 CI 脚本里统一用 curl好处是参数语义一致跨发行版行为差异小。另外一个容易忽略的点是退出码语义。curl 的退出码是自己定义的一整套比如 7 是连接失败、60 是证书校验失败和 HTTP 状态码是两回事wget 的退出码语义相对简单。脚本里做错误分支判断时这个差异会直接影响你的逻辑写得对不对。1.3 先确认手上的 curl 支持什么版本与特性自检同一个curl命令在 CentOS 7 自带的 7.x 版本和现在常见的 8.x 版本上行为可能不一样尤其是 HTTP/2、TLS 版本、--fail-with-body这类较新的选项。所以排错前先确认版本这一步经常能直接锁定原因。curl --version # 输出示例 # curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 # Release-Date: 2023-12-06 # Protocols: dict file ftp ftps gopher http https ... # Features: alt-svc AsynchDNS brotli HSTS HTTP2 HTTPS-proxy IPv6 ...这段输出信息量很大第一行是版本号和底层库libcurl后面跟着的 OpenSSL 版本决定了 TLS 能力Protocols那一行列出了编译时启用的协议Features那行列出了编译选项。如果Features里没有HTTP2那么--http2参数是没意义的如果没有SSL或者没有任何 TLS 后端名OpenSSL、GnuTLS、Schannel 之类那么所有 https 请求都会失败。我遇到过一次很典型的情况某台老服务器的 curl 报(35)握手失败查了半天代码最后发现是 curl 太旧只支持到 TLS 1.0而对方服务器早就关掉了 TLS 1.0。这种情况下除了升级 curl 没有别的办法。2. 请求骨架三件套地址、方法、头部把 curl 当成一个可以写在命令行的 Postman这个类比基本成立。它做的事情就是给定一个地址选一个方法附上一组头部和一个请求体把数据发出去再把响应带回来。理解这三样东西的构造方式覆盖了日常八成以上的使用场景。2.1 URL 里的那些写法查询串、变量展开、多 URL 一次发最基础的用法是直接把 URL 写在命令后面。如果 URL 里带查询参数注意 shell 的转义问题在 shell 里是后台执行符号所以必须加引号写成curl https://example.com/api?page1size20。这一点新手极其容易错忘了加引号的表现是命令只跑到第一个就结束了后面那一截被 shell 当成另一条命令报出size20: command not found这种莫名其妙的错误。curl 支持一次传多个 URL会按顺序依次请求curl -s -o /dev/null -w %{http_code} %{url_effective}\n \ https://example.com/a \ https://example.com/b \ https://example.com/c这个小技巧在批量探活时特别好用一次就能拿到三个地址的状态码不用写循环。URL 里还可以用[1-10]这种范围展开语法批量生成地址比如curl https://example.com/img/[1-5].jpg -O会依次下载五张图片。范围可以是数字也可以是字母还能带步长。还有一个容易被忽略的细节是 URL 中的、:、%等字符。如果路径里含有这些字符最好用--url-query或者--data-urlencode来构造而不是自己手工拼接字符串手工拼接百分号编码出错率非常高尤其是中文参数。2.2 方法切换与重定向-G、-L、--max-redirs默认方法永远是 GET需要切换时用-X POST、-X PUT、-X DELETE等。这里有个常识性坑-X只是把请求行里的方法名换掉并不会自动帮你加请求体或 Content-Type。所以curl -X POST https://api.example.com发出去的是一个没有 body 的 POST很多框架会因为 body 缺失直接返回 400。-G是一个反向操作它的作用是把-d提供的数据拼成查询串放到 URL 后面而不是放进请求体。也就是说curl -G -d a1 -d b2 https://example.com实际发出的是GET https://example.com?a1b2。这个用法在需要传递一堆参数但接口只接受 GET 时非常省事。重定向默认是不跟随的需要-L。跟随重定向时有两个细节值得注意一是跟随过程中如果跨域名curl 默认不会把 Authorization 头带过去这是安全设计如果你的接口依赖这个头并且需要跨域跟随得用--location-trusted但要清楚它的风险二是跟随次数默认上限是 30 次防循环可以用--max-redirs调整。# 跟随重定向并显示最终地址和状态码 curl -sL -o /dev/null -w final: %{url_effective}\ncode: %{http_code}\n https://example.com/redirect-me2.3 请求头与 Cookie-H、-b、-c 的组合套路-H添加请求头可以重复使用多次。值得记住的一点是curl 也有一套内置的默认头比如User-Agent: curl/8.x、Accept: */*、Host自动从 URL 推导。用-H指定同名头会覆盖默认值但如果想彻底删掉某个默认头要用-H User-Agent:这种冒号后面留空的写法。Cookie 有两个参数-b发送 Cookie-c把响应里的 Set-Cookie 写入文件。这两个经常配合使用模拟一次完整的登录加访问流程# 第一步登录把会话 Cookie 存到文件 curl -s -c /tmp/cookies.txt -d userdemopasssecret https://example.com/login # 第二步带着 Cookie 访问需要登录的页面 curl -s -b /tmp/cookies.txt https://example.com/dashboard这个模式在做接口自动化测试时特别常用比在脚本里手工管理 Cookie 字符串省事得多。需要提醒的是 Cookie 文件里含有会话凭证别随手提交到代码仓库也别放在共享目录。另外-H里的内容会原样发送所以千万别在头部里塞中文或换行符那会直接破坏请求格式导致服务端解析错误。3. 数据提交的四种形态表单、JSON、文件、原始流POST 请求的构造是 curl 使用中最容易出问题的一块因为数据编码方式太多选错了服务端就解析不到。这一节把常见的四种提交形态拆开讲清楚。3.1 -d 与 --data-urlencode中文和特殊字符的编码陷阱-d是最常用的提交参数它会做三件事把方法改成 POST、把 Content-Type 默认设为application/x-www-form-urlencoded、把数据放进请求体。关键点在于-d不会自动做 URL 编码。如果你的参数里有空格、、、中文服务端拿到的就是脏数据。正确做法是用--data-urlencode它会自动对值做百分号编码# 错误中文和空格会出问题 curl -d name张三 李四 https://example.com/api # 正确自动编码 curl --data-urlencode name张三 李四 https://example.com/api # 也可以只对值编码键自己写 curl --data-urlencode keyword/tmp/query.txt https://example.com/api语法表示从文件读取内容再编码这在提交一大段文本时很实用避免了在命令行里拼接超长字符串。注意文件内容末尾的换行符也会被编码进去如果服务端对格式敏感需要先处理掉。还有一个细节是多个-d之间会用自动连接所以不用自己加分隔符curl -d a1 -d b2 https://example.com/api # 实际请求体a1b23.2 JSON 提交与 Content-Type 的配对现在大部分接口都是 JSON 格式写法上必须显式指定 Content-Type否则服务端可能按表单解析然后报参数缺失这种让人一头雾水的错误curl -X POST https://api.example.com/users \ -H Content-Type: application/json \ -H Accept: application/json \ -d {name:demo,age:30}这里有个非常好用但常被忽略的替代写法把-d换成--json。这个选项会自动设置Content-Type: application/json和Accept: application/json还能自动识别传进来的内容是 JSON 对象还是文件路径少写两个头部出错概率也降低。curl --json {name:demo} https://api.example.com/users curl --json payload.json https://api.example.com/users如果 JSON 内容比较长写成单行字符串容易出错引号嵌套、转义我自己的习惯是先在本地写一个payload.json文件用--json payload.json提交调试通过后再考虑内联。这样还有个附带好处请求体能直接被 jq 或者编辑器校验。3.3 -F 上传文件与 multipart 边界上传文件要用-Fform它会把 Content-Type 设成multipart/form-data并自动生成 boundary。这和-d是两条完全不同的路径混用会失败# 上传单个文件字段名为 file curl -F file/path/to/report.pdf https://example.com/upload # 同时带额外字段并指定文件的 MIME 类型 curl -F filephoto.jpg;typeimage/jpeg \ -F albumvacation \ -F notesummer trip \ https://example.com/upload # 上传多个同名字段文件数组 curl -F filesa.pdf -F filesb.pdf https://example.com/upload表示上传文件内容表示把文件内容当作字段值相当于文本读取这两个符号很容易记混。另外;type;filename这些修饰可以精确控制服务端看到的元信息遇到上传后文件名乱码的问题时往往就是 filename 编码没处理好。提示用-F时不要再手动加-H Content-Type: multipart/form-data因为 boundary 是 curl 自动生成的手工指定的头缺了 boundary服务端会直接解析失败。这是新手特别容易踩的一个坑。3.4 从 Postman 导出 curl 之后要改哪几处很多人是靠 Postman 里的Code → cURL导出命令的导出来的东西能用但直接贴到生产脚本里通常要做几处清理。第一处是--compressed它本身没问题但要求服务端正确返回压缩格式某些老服务端配合某些 curl 版本会出现解析异常调试时可以先去电。第二处是 Windows 与 Linux 的引号差异。Postman 在 Windows 上导出的命令用双引号包裹里面又有单引号直接贴到 Linux 终端上会因为 shell 解析规则不同而报错需要统一改成单引号包裹、内部双引号。第三处是 Cookie 和 Authorization 头的处理。导出的命令经常把令牌硬编码在里面直接放进脚本会有泄漏风险建议改成从环境变量读取curl -X POST https://api.example.com/v1/orders \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ --json order.json第四处是导出的 URL 经常带一堆无意义的查询参数Postman 自己加的上线前清掉避免缓存键被污染导致 CDN 命中率下降。4. 下载与落盘-o、-O、-L、-f、断点续传与静默模式curl 的另一大身份是下载器。下载相关的参数组合非常多而且互相影响理解它们的优先级能省下大量调试时间。4.1 -o 与 -O 的差别以及目录写权限的坑-o是指定输出文件名-O是使用 URL 里的文件名。看起来简单但几个细节经常翻车。第一-O保留的是 URL 最后一段如果 URL 末尾带查询串比如file.zip?tokenabc在某些版本里-O会把查询串也算进去导致生成一个带问号的奇葩文件名。稳妥做法是显式用-o。第二如果目标目录不存在curl 只会报错不会自动建目录。脚本里下载到/data/backup/这种路径时得先mkdir -p。第三权限问题。以普通用户身份向/etc、/usr/local这类目录写文件会被拒绝报错信息是Failed to open the file ... Permission denied这个错误和网络无关但经常被误判成下载失败。遇到这种报错先看路径和权限不要急着查网络。# 下载到指定文件失败时快速退出 curl -fL --retry 3 -o /data/backup/app.tar.gz https://example.com/app.tar.gz # 静默下载只输出最终状态码 curl -fsSL -o /tmp/config.yaml https://example.com/config.yaml \ echo 下载成功 || echo 下载失败4.2 -f 与 -s 与 -S 三兄弟静默不等于隐藏错误这三个选项组合是 curl 里最容易理解错的地方。-s 关掉进度显示很干净但同时也把错误信息吞掉了脚本失败时你只能看到一个非零退出码完全不知道发生了什么。-S 就是把错误信息找回来且仅在出错时输出。实际写脚本时我基本固定用-fsS静默、失败即退出、出错时打印原因。这三个字母的组合比单独用-s或者不用参数都要好。至于-f需要特别注意它的一个副作用它会让 4xx、5xx 响应体不再输出到 stdout也就是你看不到服务端返回的错误详情了。如果调试阶段需要看错误详情用--fail-with-body它保留了-f的退出码语义同时把响应体打出来。# 既想要非零退出码又想看错误响应体 curl -sS --fail-with-body https://api.example.com/maybe-404 echo 退出码$?curl 的退出码是独立于 HTTP 状态码的一套编码。--fail系列会让 4xx/5xx 映射成退出码 22连接层错误则是 7、28、35、60 这些。脚本里可以根据退出码做不同处理比如 22 说明服务端逻辑拒绝7 说明网络或端口不通两者的排查方向完全不同。4.3 大文件下载-C -、--limit-rate、超时参数下载几百 MB 或几个 GB 的文件时断点和限速就很重要了。-C -表示自动从已下载的字节位置续传配合-o使用curl -fL -C - -o /data/big.iso https://mirrors.example.com/big.iso这个参数要求服务端支持 Range 请求如果不支持curl 会从头开始覆盖下载不会有任何提示所以用之前最好确认一下。限速用--limit-rate单位可以是 k、m、g比如--limit-rate 2m表示限制在每秒 2MB适合在带宽紧张的线上机器上做后台下载时避免打满带宽。超时方面有三个参数需要区分清楚--connect-timeout限制建连阶段--max-time限制整个请求从开始到结束的总时长--speed-time配--speed-limit是在速度低于阈值持续多少秒时断开。生产环境里这三个建议都设上尤其--max-time否则一个卡死的连接可能让你的脚本挂到天荒地老在 CI 里表现为任务超时被强制终止日志里什么都看不到。curl -fL --connect-timeout 10 --max-time 600 \ --retry 3 --retry-delay 5 \ -C - -o /data/big.iso https://mirrors.example.com/big.iso配合--retry时要注意默认只对瞬时错误重试比如连接超时、DNS 解析失败对 HTTP 4xx 是不会重试的。如果希望 5xx 也重试加--retry-all-errors但要注意别对幂等性有问题的接口乱用可能导致重复下单这类副作用。5. 证书与错误码curl: (60)、(35)、(7) 的排查链路这一节应该是全文最实用的部分。curl 的报错信息其实写得很清楚只是格式看起来吓人。下面把几个高频错误逐个拆开给出完整的排查顺序而不是直接丢一个加上 -k 就好了的答案——-k关掉证书校验在测试环境偶尔用用还行放到生产脚本里等于把 HTTPS 的安全价值全部扔掉。5.1 curl: (60) SSL certificate problem 的三种成因完整报错通常是这样的curl: (60) SSL certificate problem: unable to get local issuer certificate More details here: https://curl.se/docs/sslcerts.html这个错误的核心含义是客户端拿到的服务端证书无法用本地的 CA 信任库验证出一条完整链路。成因基本落在三种情况上。第一种是系统 CA 证书包缺失或过期。精简的容器镜像为了减小体积经常不装ca-certificates或者装的是很早以前的版本而现在的证书链普遍用 Lets Encrypt 之类的新根证书老库当然验不过。解决办法是安装或更新 CA 包Debian 系用apt-get install -y ca-certificatesRHEL 系用yum install -y ca-certificates装完记得update-ca-certificates。第二种是服务端证书链不完整。很多中间证书没配好浏览器会自动补全所以浏览器访问正常但 curl 严格校验就失败。验证方法是# 查看服务端返回的完整证书链 openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null # 只看证书主题和签发者 echo | openssl s_client -connect example.com:443 -servername example.com 2/dev/null \ | openssl x509 -noout -subject -issuer -dates如果输出的链条只有一张叶子证书、没有中间证书那问题在服务端需要运维把完整链配上去。这种情况你在客户端怎么折腾都没用。第三种是目标用的是自建 CA 或内网证书。这时候正确的做法不是-k而是把自建 CA 的根证书导入本地信任库或者用--cacert指定curl --cacert /etc/pki/ca-trust/source/anchors/internal-ca.crt https://internal.example.com把自建 CA 加到系统信任库的好处是所有工具curl、wget、Python requests 只要用的是系统库都能受益而不用每次都带参数。5.2 curl: (35) 握手阶段的失败信息怎么读(35)是 TLS 握手失败这个错误码覆盖的范围比 60 宽得多具体原因要看冒号后面的描述。常见的几种描述和对应原因报错尾部信息常见原因排查方向tcp connection reset by peer握手阶段被对端或中间设备重置检查是否被防火墙/负载均衡拒绝、TLS 版本协商是否失败next InitializeSecurityContext failed系统 TLS 后端握手失败常见于证书吊销检查失败、系统时间不对error:14094410:SSL routines协议或加密套件不匹配检查服务端是否已禁用老版本 TLSwrong version number明文 HTTP 端口被当成 HTTPS 访问检查端口和协议是否写错这里有两个经验点值得单独说。一个是系统时间。证书有效期校验依赖本机时钟如果服务器时间漂移了几年所有证书都会未生效或已过期报的却是各式各样的握手错误特别难猜。遇到莫名其妙的 TLS 报错先date看一眼时间。另一个是吊销检查。Windows 上有时候会看到CRYPT_E_REVOCATION_OFFLINE这类信息说明吊销列表拉不下来可以临时用--ssl-no-revoke绕过只建议在明确知道自己在做什么的情况下使用。排查握手问题时-v是最直接的工具它会把 TLS 版本、加密套件、证书信息全打出来curl -v https://example.com 21 | grep -Ei SSL|TLS|certificate|ALPN5.3 curl: (7) Failed to connect 的逐层定位curl: (7) Failed to connect to example.com port 443: Connection refused(7)是连接层错误说明 TCP 三次握手没完成问题在 curl 发出请求之前就发生了。排查要分层走顺序不要乱。第一层是 DNS。先确认域名解析出来的 IP 是不是你预期的那个getent hosts example.com dig short example.com如果解析出来是内网地址或者解析失败那后面都不用查了。有些环境里/etc/resolv.conf被改乱表现就是所有域名都解析不了但 IP 直连正常。第二层是网络可达性。用ping或者nc -zv example.com 443确认端口是否可连。注意有些服务器禁 ICMPping 不通不代表端口不通别被误导。第三层是监听状态。如果目标是你自己的服务用ss -lntp | grep 443看端口有没有真的在监听。我遇到过好几次服务启动了但绑到了 127.0.0.1从外部访问自然连不上日志里却看不出任何异常。第四层是防火墙和安全组。本地 iptables、云平台安全组、中间的网络策略任何一层拒绝都会表现为同样的Connection refused或超时。区分方法很简单refused通常意味着包到了但对端没监听或被明确拒绝长时间卡住然后超时更可能是被静默丢弃。5.4 错误码速查表与 --fail-with-body把常用退出码整理成一张表脚本里做分支判断时可以直接对照退出码含义典型场景0成功正常完成1不支持的协议URL 里的协议名写错3URL 格式错误少了协议头或拼写错误6无法解析主机DNS 问题或域名写错7无法连接端口不通、服务未启动、防火墙拦截22HTTP 返回错误码配合 -f / --fail 使用4xx、5xx 会映射到这里28操作超时网络慢、服务端处理慢、超时参数设太短35TLS 握手失败协议版本、证书链、加密套件问题47重定向次数过多重定向循环52服务端无响应连接建立了但没返回数据56接收数据失败传输中断、连接被重置60证书校验失败CA 库缺失、证书链不全、自签名证书脚本里做判断的推荐写法if ! curl -fsSL --max-time 30 -o /tmp/out.json https://api.example.com/data; then code$? case $code in 7) echo 网络不可达检查服务与防火墙 2 ;; 22) echo 服务端返回错误状态码 2 ;; 28) echo 请求超时 2 ;; 60) echo 证书校验失败检查 CA 库或证书链 2 ;; *) echo curl 失败退出码$code 2 ;; esac exit 1 fi这套分支看起来啰嗦但它能在凌晨三点被报警叫醒的时候让你一眼看出是网络问题还是业务问题省下的时间远比写这几行的成本高。6. 把 curl 当调试工具用-v、--trace、-w 与耗时拆解curl 不只是发请求的工具它本身就是一个相当强的网络调试器。会用这几个输出选项之后很多到底卡在哪一步的问题不用抓包就能定位。6.1 -v 与 -i 输出该看哪几行-v把整个过程分成三部分输出每行前面带符号标识*开头的是连接和协议层信息开头的是 curl 发出的内容开头的是收到的内容。用-v时先看*那部分里面包含 DNS 解析结果、尝试连接的 IP 和端口、TLS 版本和加密套件、最终使用的 HTTP 版本这几条信息能快速排除掉一大批猜测。curl -v https://example.com/api 21 | head -40-i只输出响应头加响应体适合快速看状态码、响应头里的缓存策略、重定向位置、Set-Cookie 内容。相比-v-i的输出更干净没有连接层噪音日常调试接口我更常用-i。curl -si https://example.com/api | head -20需要注意的是-v会把 Authorization、Cookie 这类敏感头原样打印出来所以在 CI 日志里使用要谨慎可能造成凭证泄漏。这也是为什么我建议在脚本里用-sS而不是-v。6.2 -w 自定义输出格式一次拿到状态码与各阶段耗时-w是 curl 里被低估最多的选项。它能按模板输出一堆内置变量把一次请求的各阶段耗时、状态码、实际地址、传输字节数全部打印出来配合-o /dev/null就得到一个轻量的接口性能探针。curl -s -o /dev/null -w dns解析: %{time_namelookup}s 建连: %{time_connect}s TLS握手: %{time_appconnect}s 首字节: %{time_starttransfer}s 总耗时: %{time_total}s HTTP状态: %{http_code} 下载字节: %{size_download} 实际地址: %{url_effective} 重定向次数: %{num_redirects} https://example.com/api这几个时间点的关系能说明很多问题。time_namelookup大说明 DNS 慢通常是 DNS 服务器配置有问题或者解析链路太长。time_connect与time_namelookup的差值大说明网络往返延迟高。time_appconnect与time_connect的差值就是 TLS 握手耗时如果这个值异常大通常是证书链太长或者吊销检查在超时。time_starttransfer与time_appconnect的差值接近服务端处理时间能直接反映出后端的响应速度。这几个数字一摆出来问题归属到哪一层就非常清楚了。提示-w的模板字符串里换行可以直接写但如果放在 shell 的双引号里%不需要转义。想输出字面的百分号写%%。6.3 抓 SSE 流式接口与长时间连接的注意事项现在越来越多接口是流式返回的服务端持续推送数据块用 curl 调试这类接口时默认的缓冲行为会让你感觉卡住了没有任何输出。实际上数据在陆续到达只是被行缓冲挡住了。# 关闭缓冲实时看到流式输出 curl -N -s https://example.com/stream/events # 加上超时限制避免流式连接一直挂着 curl -N -s --max-time 60 https://example.com/stream/events-N是关闭输出缓冲的关键参数。另外流式接口通常不会正常结束连接会一直保持所以--max-time几乎是必须的。如果只是想观察几十秒的数据格式用timeout 30 curl -N -s ...从外部加时限也可以两种方式效果类似。调试流式接口时还有个实用技巧把输出重定向到文件再逐行看避免终端被刷屏。timeout 20 curl -N -s https://example.com/stream/events /tmp/stream.log wc -l /tmp/stream.log tail -5 /tmp/stream.log这样能清楚看到这段时间内到达了多少条事件、格式对不对、有没有心跳包比盯着滚动的终端有用得多。7. 脚本化落地把 curl 放进运维与 CI 流程命令行敲和写进脚本是两回事。脚本里要考虑退出码传播、重试策略、凭证管理、并发控制这些才是 curl 在生产环境里真正的难点。7.1 退出码与 set -e 的配合shell 脚本里如果写了set -e任何一条命令返回非零都会让脚本立即退出。curl 只要没加--failHTTP 500 也会返回退出码 0脚本会当成功继续往下跑这是很多构建成功了但产物是错的问题的根源。所以脚本里使用 curl 有两条铁律下载和调用接口一律加-f或--fail-with-body如果有哪次失败是可以容忍的显式用|| true或者在if条件里调用不要依赖隐式行为。#!/usr/bin/env bash set -euo pipefail APIhttps://api.example.com # 失败的调用会让脚本退出且能看到错误详情 curl -fsS --fail-with-body --max-time 20 ${API}/health -o /tmp/health.json # 允许失败的调用明确写在 if 里 if ! curl -fsS --max-time 10 ${API}/optional -o /tmp/optional.json; then echo 可选接口不可用继续执行 2 fiset -o pipefail这一条在管道场景里也很重要。curl ... | sh这种写法如果没有 pipefailsh 的退出码会覆盖 curl 的退出码下载失败但脚本解析失败被掩盖的情况就会发生。加上 pipefail管道里任何一段失败都会传播出来。7.2 重试、超时与并发控制的参数组合生产脚本里的 curl 调用基本都应该带上超时和重试。推荐的组合是curl -fsSL \ --connect-timeout 10 \ --max-time 60 \ --retry 3 \ --retry-delay 2 \ --retry-max-time 180 \ --retry-connrefused \ -o /tmp/artifact.tar.gz \ https://example.com/artifact.tar.gz这套参数的含义是建连最多等 10 秒整个请求最多 60 秒失败后重试 3 次、每次间隔 2 秒、重试总时长不超过 180 秒遇到连接被拒绝也重试。--retry-connrefused这个选项在服务刚启动还没就绪的场景下很有用比如容器编排里等待依赖服务起监听。需要批量请求时不要写一个 for 循环串行跑几十个请求会慢到不可接受。用xargs -P做并发控制cat urls.txt | xargs -P 8 -I {} sh -c code$(curl -s -o /dev/null -w %{http_code} --max-time 10 {}) echo {} $code -P 8表示最多 8 个并发。这个数字别开太大容易把对端打挂也会让本机的文件描述符和连接数紧张。8 到 16 之间对大多数场景是合适的。7.3 认证信息不进历史记录--netrc、-K 配置文件直接在命令行里写-H Authorization: Bearer xxx有两个问题一是会进 shell 历史记录二是会出现在ps输出里同机器上的其他用户能看到。生产脚本里应该从环境变量读取或者用 curl 的配置文件。-K可以指定一个配置文件把常用参数写进去# /etc/curlrc-app (权限设为 600) header Authorization: Bearer abc123 connect-timeout 10 max-time 60 retry 3 silent true show-error truecurl -K /etc/curlrc-app https://api.example.com/data配置文件的语法是每行一个选项名 值和命令行参数一一对应参数名前面不用加--短横线保持一致。这样做的好处是凭证不出现在命令行和历史里同时把一批公共参数集中管理脚本里只保留和业务相关的部分可读性提升明显。另一个方案是--netrc-file专注于用户名密码认证格式是三段式machine api.example.com login myuser password mypassword配合curl -n --netrc-file /path/to/netrc使用。这个文件同样要设置成chmod 600并且不要提交到任何代码仓库。如果是 CI 环境把内容放进受保护的密钥变量在流水线里临时生成这个文件、用完立即删除是比较稳妥的做法。注意配置文件里的选项是默认值命令行里显式写的参数会覆盖它。所以不用怕全局配置会影响所有调用需要临时覆盖的时候直接加参数就行。用 curl 这些年我最大的体会是这个工具的报错其实非常诚实它在尽力告诉你哪一层出了问题只是信息被压缩成了几个数字和短语不熟悉的人容易慌。真正值钱的经验不是记住所有参数而是养成一个习惯看到报错先确认版本和系统时间再按 DNS、网络、TLS、HTTP 这个顺序分层排查一层确认没问题再往下一层走别跳步。另外强烈建议在自己的机器上准备一份~/.curlrc把connect-timeout、max-time、retry、silent、show-error这几项设成默认值你会发现日常调试的体验顺滑很多至少在终端里不会再被卡死的连接和一堆进度条打扰。
第一次在服务器上敲 curl我猜大部分人的经历都差不多照着某篇教程复制了一行curl -fsSL https://xxx/install.sh | sh回车装完了然后就把这个命令丢进收藏夹吃灰。直到某天接口联调发现返回是空的、下载脚本卡在证书报错、自动化构建里那行 curl 悄悄失败了却没人发现才反应过来这个看起来简单的命令其实有一整套行为逻辑没搞明白。curl 属于 Linux 常用命令里那种用得最多、懂得最少的典型代表它既是下载工具又是 HTTP 客户端还是排错探针三种身份混在一个二进制文件里。这篇内容就是把我这几年在运维、接口调试、CI 流程里踩过的 curl 相关的坑整理一遍从最基础的方法和头部构造一路讲到证书报错、错误码定位、脚本化落地适合刚接触 Linux 的朋友也适合已经用了一两年但没系统梳理过的同学看完至少能做到一件事报错信息摆在面前知道下一步该查哪里。1. 从一条安装脚本拆起curl 在真实环境里解决什么问题很多人对 curl 的第一印象来自各种官方安装脚本那条长长的命令看起来像咒语其实每个字母都有明确含义。把这条命令拆开看是理解 curl 设计哲学最快的入口也是后面所有参数组合的基础。1.1 安装脚本为什么普遍写成 curl -fsSL URL | shcurl -fsSL https://example.com/install.sh | sh这行命令里塞了四个短选项它们分别解决四个不同的问题。-f表示遇到 HTTP 错误状态码4xx、5xx时不要输出响应体直接以非零退出码结束这一条极其关键——如果没有-f服务器返回一个 404 的 HTML 错误页管道后面的 sh 会认认真真地尝试执行这段 HTML结果就是一堆莫名其妙的语法错误让人完全找不到方向。-s是静默模式关掉进度条和统计信息避免这些内容混进管道污染脚本内容。-S是配合-s使用的意思是静默但不隐藏错误当出错时仍然把错误信息打到标准错误。-L是跟随重定向很多下载地址会先返回 301 或 302 跳到 CDN没有-L就只能拿到一个空响应。把这四个拼起来读就是下载时安静点但真出错了要告诉我遇到跳转要跟过去HTTP 状态不对就直接失败。这套组合几乎可以当作所有下载后立即使用场景的默认模板。我自己写脚本时只要是拉配置、拉密钥、拉脚本一律用-fsSL很少例外。注意管道执行远程脚本这件事本身有风险脚本内容在传输前你并没有看过。稳妥的做法是先curl -fsSL url -o /tmp/install.sh用less或head看一眼关键部分确认无误再sh /tmp/install.sh。多花十秒钟能避免很多尴尬。1.2 curl 和 wget 的分工与取舍新手常见的困惑是这两个工具到底该用哪个。简单说wget 的设计目标是递归下载整个网站擅长镜像、断点续传、批量抓取curl 的设计目标是构造并发送一个 HTTP 请求擅长自定义方法、请求头、请求体、认证方式。所以你会发现两个现象写接口调试脚本的人几乎只用 curl做爬取或备份静态资源的人偏爱 wget。在容器镜像里这个区别更明显。很多精简基础镜像比如 alpine默认只带 curl 不带 wget也有些镜像反过来。所以写 Dockerfile 的时候别想当然地认为两个都在要么显式安装要么统一用同一个工具。我自己在 CI 脚本里统一用 curl好处是参数语义一致跨发行版行为差异小。另外一个容易忽略的点是退出码语义。curl 的退出码是自己定义的一整套比如 7 是连接失败、60 是证书校验失败和 HTTP 状态码是两回事wget 的退出码语义相对简单。脚本里做错误分支判断时这个差异会直接影响你的逻辑写得对不对。1.3 先确认手上的 curl 支持什么版本与特性自检同一个curl命令在 CentOS 7 自带的 7.x 版本和现在常见的 8.x 版本上行为可能不一样尤其是 HTTP/2、TLS 版本、--fail-with-body这类较新的选项。所以排错前先确认版本这一步经常能直接锁定原因。curl --version # 输出示例 # curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 # Release-Date: 2023-12-06 # Protocols: dict file ftp ftps gopher http https ... # Features: alt-svc AsynchDNS brotli HSTS HTTP2 HTTPS-proxy IPv6 ...这段输出信息量很大第一行是版本号和底层库libcurl后面跟着的 OpenSSL 版本决定了 TLS 能力Protocols那一行列出了编译时启用的协议Features那行列出了编译选项。如果Features里没有HTTP2那么--http2参数是没意义的如果没有SSL或者没有任何 TLS 后端名OpenSSL、GnuTLS、Schannel 之类那么所有 https 请求都会失败。我遇到过一次很典型的情况某台老服务器的 curl 报(35)握手失败查了半天代码最后发现是 curl 太旧只支持到 TLS 1.0而对方服务器早就关掉了 TLS 1.0。这种情况下除了升级 curl 没有别的办法。2. 请求骨架三件套地址、方法、头部把 curl 当成一个可以写在命令行的 Postman这个类比基本成立。它做的事情就是给定一个地址选一个方法附上一组头部和一个请求体把数据发出去再把响应带回来。理解这三样东西的构造方式覆盖了日常八成以上的使用场景。2.1 URL 里的那些写法查询串、变量展开、多 URL 一次发最基础的用法是直接把 URL 写在命令后面。如果 URL 里带查询参数注意 shell 的转义问题在 shell 里是后台执行符号所以必须加引号写成curl https://example.com/api?page1size20。这一点新手极其容易错忘了加引号的表现是命令只跑到第一个就结束了后面那一截被 shell 当成另一条命令报出size20: command not found这种莫名其妙的错误。curl 支持一次传多个 URL会按顺序依次请求curl -s -o /dev/null -w %{http_code} %{url_effective}\n \ https://example.com/a \ https://example.com/b \ https://example.com/c这个小技巧在批量探活时特别好用一次就能拿到三个地址的状态码不用写循环。URL 里还可以用[1-10]这种范围展开语法批量生成地址比如curl https://example.com/img/[1-5].jpg -O会依次下载五张图片。范围可以是数字也可以是字母还能带步长。还有一个容易被忽略的细节是 URL 中的、:、%等字符。如果路径里含有这些字符最好用--url-query或者--data-urlencode来构造而不是自己手工拼接字符串手工拼接百分号编码出错率非常高尤其是中文参数。2.2 方法切换与重定向-G、-L、--max-redirs默认方法永远是 GET需要切换时用-X POST、-X PUT、-X DELETE等。这里有个常识性坑-X只是把请求行里的方法名换掉并不会自动帮你加请求体或 Content-Type。所以curl -X POST https://api.example.com发出去的是一个没有 body 的 POST很多框架会因为 body 缺失直接返回 400。-G是一个反向操作它的作用是把-d提供的数据拼成查询串放到 URL 后面而不是放进请求体。也就是说curl -G -d a1 -d b2 https://example.com实际发出的是GET https://example.com?a1b2。这个用法在需要传递一堆参数但接口只接受 GET 时非常省事。重定向默认是不跟随的需要-L。跟随重定向时有两个细节值得注意一是跟随过程中如果跨域名curl 默认不会把 Authorization 头带过去这是安全设计如果你的接口依赖这个头并且需要跨域跟随得用--location-trusted但要清楚它的风险二是跟随次数默认上限是 30 次防循环可以用--max-redirs调整。# 跟随重定向并显示最终地址和状态码 curl -sL -o /dev/null -w final: %{url_effective}\ncode: %{http_code}\n https://example.com/redirect-me2.3 请求头与 Cookie-H、-b、-c 的组合套路-H添加请求头可以重复使用多次。值得记住的一点是curl 也有一套内置的默认头比如User-Agent: curl/8.x、Accept: */*、Host自动从 URL 推导。用-H指定同名头会覆盖默认值但如果想彻底删掉某个默认头要用-H User-Agent:这种冒号后面留空的写法。Cookie 有两个参数-b发送 Cookie-c把响应里的 Set-Cookie 写入文件。这两个经常配合使用模拟一次完整的登录加访问流程# 第一步登录把会话 Cookie 存到文件 curl -s -c /tmp/cookies.txt -d userdemopasssecret https://example.com/login # 第二步带着 Cookie 访问需要登录的页面 curl -s -b /tmp/cookies.txt https://example.com/dashboard这个模式在做接口自动化测试时特别常用比在脚本里手工管理 Cookie 字符串省事得多。需要提醒的是 Cookie 文件里含有会话凭证别随手提交到代码仓库也别放在共享目录。另外-H里的内容会原样发送所以千万别在头部里塞中文或换行符那会直接破坏请求格式导致服务端解析错误。3. 数据提交的四种形态表单、JSON、文件、原始流POST 请求的构造是 curl 使用中最容易出问题的一块因为数据编码方式太多选错了服务端就解析不到。这一节把常见的四种提交形态拆开讲清楚。3.1 -d 与 --data-urlencode中文和特殊字符的编码陷阱-d是最常用的提交参数它会做三件事把方法改成 POST、把 Content-Type 默认设为application/x-www-form-urlencoded、把数据放进请求体。关键点在于-d不会自动做 URL 编码。如果你的参数里有空格、、、中文服务端拿到的就是脏数据。正确做法是用--data-urlencode它会自动对值做百分号编码# 错误中文和空格会出问题 curl -d name张三 李四 https://example.com/api # 正确自动编码 curl --data-urlencode name张三 李四 https://example.com/api # 也可以只对值编码键自己写 curl --data-urlencode keyword/tmp/query.txt https://example.com/api语法表示从文件读取内容再编码这在提交一大段文本时很实用避免了在命令行里拼接超长字符串。注意文件内容末尾的换行符也会被编码进去如果服务端对格式敏感需要先处理掉。还有一个细节是多个-d之间会用自动连接所以不用自己加分隔符curl -d a1 -d b2 https://example.com/api # 实际请求体a1b23.2 JSON 提交与 Content-Type 的配对现在大部分接口都是 JSON 格式写法上必须显式指定 Content-Type否则服务端可能按表单解析然后报参数缺失这种让人一头雾水的错误curl -X POST https://api.example.com/users \ -H Content-Type: application/json \ -H Accept: application/json \ -d {name:demo,age:30}这里有个非常好用但常被忽略的替代写法把-d换成--json。这个选项会自动设置Content-Type: application/json和Accept: application/json还能自动识别传进来的内容是 JSON 对象还是文件路径少写两个头部出错概率也降低。curl --json {name:demo} https://api.example.com/users curl --json payload.json https://api.example.com/users如果 JSON 内容比较长写成单行字符串容易出错引号嵌套、转义我自己的习惯是先在本地写一个payload.json文件用--json payload.json提交调试通过后再考虑内联。这样还有个附带好处请求体能直接被 jq 或者编辑器校验。3.3 -F 上传文件与 multipart 边界上传文件要用-Fform它会把 Content-Type 设成multipart/form-data并自动生成 boundary。这和-d是两条完全不同的路径混用会失败# 上传单个文件字段名为 file curl -F file/path/to/report.pdf https://example.com/upload # 同时带额外字段并指定文件的 MIME 类型 curl -F filephoto.jpg;typeimage/jpeg \ -F albumvacation \ -F notesummer trip \ https://example.com/upload # 上传多个同名字段文件数组 curl -F filesa.pdf -F filesb.pdf https://example.com/upload表示上传文件内容表示把文件内容当作字段值相当于文本读取这两个符号很容易记混。另外;type;filename这些修饰可以精确控制服务端看到的元信息遇到上传后文件名乱码的问题时往往就是 filename 编码没处理好。提示用-F时不要再手动加-H Content-Type: multipart/form-data因为 boundary 是 curl 自动生成的手工指定的头缺了 boundary服务端会直接解析失败。这是新手特别容易踩的一个坑。3.4 从 Postman 导出 curl 之后要改哪几处很多人是靠 Postman 里的Code → cURL导出命令的导出来的东西能用但直接贴到生产脚本里通常要做几处清理。第一处是--compressed它本身没问题但要求服务端正确返回压缩格式某些老服务端配合某些 curl 版本会出现解析异常调试时可以先去电。第二处是 Windows 与 Linux 的引号差异。Postman 在 Windows 上导出的命令用双引号包裹里面又有单引号直接贴到 Linux 终端上会因为 shell 解析规则不同而报错需要统一改成单引号包裹、内部双引号。第三处是 Cookie 和 Authorization 头的处理。导出的命令经常把令牌硬编码在里面直接放进脚本会有泄漏风险建议改成从环境变量读取curl -X POST https://api.example.com/v1/orders \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ --json order.json第四处是导出的 URL 经常带一堆无意义的查询参数Postman 自己加的上线前清掉避免缓存键被污染导致 CDN 命中率下降。4. 下载与落盘-o、-O、-L、-f、断点续传与静默模式curl 的另一大身份是下载器。下载相关的参数组合非常多而且互相影响理解它们的优先级能省下大量调试时间。4.1 -o 与 -O 的差别以及目录写权限的坑-o是指定输出文件名-O是使用 URL 里的文件名。看起来简单但几个细节经常翻车。第一-O保留的是 URL 最后一段如果 URL 末尾带查询串比如file.zip?tokenabc在某些版本里-O会把查询串也算进去导致生成一个带问号的奇葩文件名。稳妥做法是显式用-o。第二如果目标目录不存在curl 只会报错不会自动建目录。脚本里下载到/data/backup/这种路径时得先mkdir -p。第三权限问题。以普通用户身份向/etc、/usr/local这类目录写文件会被拒绝报错信息是Failed to open the file ... Permission denied这个错误和网络无关但经常被误判成下载失败。遇到这种报错先看路径和权限不要急着查网络。# 下载到指定文件失败时快速退出 curl -fL --retry 3 -o /data/backup/app.tar.gz https://example.com/app.tar.gz # 静默下载只输出最终状态码 curl -fsSL -o /tmp/config.yaml https://example.com/config.yaml \ echo 下载成功 || echo 下载失败4.2 -f 与 -s 与 -S 三兄弟静默不等于隐藏错误这三个选项组合是 curl 里最容易理解错的地方。-s 关掉进度显示很干净但同时也把错误信息吞掉了脚本失败时你只能看到一个非零退出码完全不知道发生了什么。-S 就是把错误信息找回来且仅在出错时输出。实际写脚本时我基本固定用-fsS静默、失败即退出、出错时打印原因。这三个字母的组合比单独用-s或者不用参数都要好。至于-f需要特别注意它的一个副作用它会让 4xx、5xx 响应体不再输出到 stdout也就是你看不到服务端返回的错误详情了。如果调试阶段需要看错误详情用--fail-with-body它保留了-f的退出码语义同时把响应体打出来。# 既想要非零退出码又想看错误响应体 curl -sS --fail-with-body https://api.example.com/maybe-404 echo 退出码$?curl 的退出码是独立于 HTTP 状态码的一套编码。--fail系列会让 4xx/5xx 映射成退出码 22连接层错误则是 7、28、35、60 这些。脚本里可以根据退出码做不同处理比如 22 说明服务端逻辑拒绝7 说明网络或端口不通两者的排查方向完全不同。4.3 大文件下载-C -、--limit-rate、超时参数下载几百 MB 或几个 GB 的文件时断点和限速就很重要了。-C -表示自动从已下载的字节位置续传配合-o使用curl -fL -C - -o /data/big.iso https://mirrors.example.com/big.iso这个参数要求服务端支持 Range 请求如果不支持curl 会从头开始覆盖下载不会有任何提示所以用之前最好确认一下。限速用--limit-rate单位可以是 k、m、g比如--limit-rate 2m表示限制在每秒 2MB适合在带宽紧张的线上机器上做后台下载时避免打满带宽。超时方面有三个参数需要区分清楚--connect-timeout限制建连阶段--max-time限制整个请求从开始到结束的总时长--speed-time配--speed-limit是在速度低于阈值持续多少秒时断开。生产环境里这三个建议都设上尤其--max-time否则一个卡死的连接可能让你的脚本挂到天荒地老在 CI 里表现为任务超时被强制终止日志里什么都看不到。curl -fL --connect-timeout 10 --max-time 600 \ --retry 3 --retry-delay 5 \ -C - -o /data/big.iso https://mirrors.example.com/big.iso配合--retry时要注意默认只对瞬时错误重试比如连接超时、DNS 解析失败对 HTTP 4xx 是不会重试的。如果希望 5xx 也重试加--retry-all-errors但要注意别对幂等性有问题的接口乱用可能导致重复下单这类副作用。5. 证书与错误码curl: (60)、(35)、(7) 的排查链路这一节应该是全文最实用的部分。curl 的报错信息其实写得很清楚只是格式看起来吓人。下面把几个高频错误逐个拆开给出完整的排查顺序而不是直接丢一个加上 -k 就好了的答案——-k关掉证书校验在测试环境偶尔用用还行放到生产脚本里等于把 HTTPS 的安全价值全部扔掉。5.1 curl: (60) SSL certificate problem 的三种成因完整报错通常是这样的curl: (60) SSL certificate problem: unable to get local issuer certificate More details here: https://curl.se/docs/sslcerts.html这个错误的核心含义是客户端拿到的服务端证书无法用本地的 CA 信任库验证出一条完整链路。成因基本落在三种情况上。第一种是系统 CA 证书包缺失或过期。精简的容器镜像为了减小体积经常不装ca-certificates或者装的是很早以前的版本而现在的证书链普遍用 Lets Encrypt 之类的新根证书老库当然验不过。解决办法是安装或更新 CA 包Debian 系用apt-get install -y ca-certificatesRHEL 系用yum install -y ca-certificates装完记得update-ca-certificates。第二种是服务端证书链不完整。很多中间证书没配好浏览器会自动补全所以浏览器访问正常但 curl 严格校验就失败。验证方法是# 查看服务端返回的完整证书链 openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null # 只看证书主题和签发者 echo | openssl s_client -connect example.com:443 -servername example.com 2/dev/null \ | openssl x509 -noout -subject -issuer -dates如果输出的链条只有一张叶子证书、没有中间证书那问题在服务端需要运维把完整链配上去。这种情况你在客户端怎么折腾都没用。第三种是目标用的是自建 CA 或内网证书。这时候正确的做法不是-k而是把自建 CA 的根证书导入本地信任库或者用--cacert指定curl --cacert /etc/pki/ca-trust/source/anchors/internal-ca.crt https://internal.example.com把自建 CA 加到系统信任库的好处是所有工具curl、wget、Python requests 只要用的是系统库都能受益而不用每次都带参数。5.2 curl: (35) 握手阶段的失败信息怎么读(35)是 TLS 握手失败这个错误码覆盖的范围比 60 宽得多具体原因要看冒号后面的描述。常见的几种描述和对应原因报错尾部信息常见原因排查方向tcp connection reset by peer握手阶段被对端或中间设备重置检查是否被防火墙/负载均衡拒绝、TLS 版本协商是否失败next InitializeSecurityContext failed系统 TLS 后端握手失败常见于证书吊销检查失败、系统时间不对error:14094410:SSL routines协议或加密套件不匹配检查服务端是否已禁用老版本 TLSwrong version number明文 HTTP 端口被当成 HTTPS 访问检查端口和协议是否写错这里有两个经验点值得单独说。一个是系统时间。证书有效期校验依赖本机时钟如果服务器时间漂移了几年所有证书都会未生效或已过期报的却是各式各样的握手错误特别难猜。遇到莫名其妙的 TLS 报错先date看一眼时间。另一个是吊销检查。Windows 上有时候会看到CRYPT_E_REVOCATION_OFFLINE这类信息说明吊销列表拉不下来可以临时用--ssl-no-revoke绕过只建议在明确知道自己在做什么的情况下使用。排查握手问题时-v是最直接的工具它会把 TLS 版本、加密套件、证书信息全打出来curl -v https://example.com 21 | grep -Ei SSL|TLS|certificate|ALPN5.3 curl: (7) Failed to connect 的逐层定位curl: (7) Failed to connect to example.com port 443: Connection refused(7)是连接层错误说明 TCP 三次握手没完成问题在 curl 发出请求之前就发生了。排查要分层走顺序不要乱。第一层是 DNS。先确认域名解析出来的 IP 是不是你预期的那个getent hosts example.com dig short example.com如果解析出来是内网地址或者解析失败那后面都不用查了。有些环境里/etc/resolv.conf被改乱表现就是所有域名都解析不了但 IP 直连正常。第二层是网络可达性。用ping或者nc -zv example.com 443确认端口是否可连。注意有些服务器禁 ICMPping 不通不代表端口不通别被误导。第三层是监听状态。如果目标是你自己的服务用ss -lntp | grep 443看端口有没有真的在监听。我遇到过好几次服务启动了但绑到了 127.0.0.1从外部访问自然连不上日志里却看不出任何异常。第四层是防火墙和安全组。本地 iptables、云平台安全组、中间的网络策略任何一层拒绝都会表现为同样的Connection refused或超时。区分方法很简单refused通常意味着包到了但对端没监听或被明确拒绝长时间卡住然后超时更可能是被静默丢弃。5.4 错误码速查表与 --fail-with-body把常用退出码整理成一张表脚本里做分支判断时可以直接对照退出码含义典型场景0成功正常完成1不支持的协议URL 里的协议名写错3URL 格式错误少了协议头或拼写错误6无法解析主机DNS 问题或域名写错7无法连接端口不通、服务未启动、防火墙拦截22HTTP 返回错误码配合 -f / --fail 使用4xx、5xx 会映射到这里28操作超时网络慢、服务端处理慢、超时参数设太短35TLS 握手失败协议版本、证书链、加密套件问题47重定向次数过多重定向循环52服务端无响应连接建立了但没返回数据56接收数据失败传输中断、连接被重置60证书校验失败CA 库缺失、证书链不全、自签名证书脚本里做判断的推荐写法if ! curl -fsSL --max-time 30 -o /tmp/out.json https://api.example.com/data; then code$? case $code in 7) echo 网络不可达检查服务与防火墙 2 ;; 22) echo 服务端返回错误状态码 2 ;; 28) echo 请求超时 2 ;; 60) echo 证书校验失败检查 CA 库或证书链 2 ;; *) echo curl 失败退出码$code 2 ;; esac exit 1 fi这套分支看起来啰嗦但它能在凌晨三点被报警叫醒的时候让你一眼看出是网络问题还是业务问题省下的时间远比写这几行的成本高。6. 把 curl 当调试工具用-v、--trace、-w 与耗时拆解curl 不只是发请求的工具它本身就是一个相当强的网络调试器。会用这几个输出选项之后很多到底卡在哪一步的问题不用抓包就能定位。6.1 -v 与 -i 输出该看哪几行-v把整个过程分成三部分输出每行前面带符号标识*开头的是连接和协议层信息开头的是 curl 发出的内容开头的是收到的内容。用-v时先看*那部分里面包含 DNS 解析结果、尝试连接的 IP 和端口、TLS 版本和加密套件、最终使用的 HTTP 版本这几条信息能快速排除掉一大批猜测。curl -v https://example.com/api 21 | head -40-i只输出响应头加响应体适合快速看状态码、响应头里的缓存策略、重定向位置、Set-Cookie 内容。相比-v-i的输出更干净没有连接层噪音日常调试接口我更常用-i。curl -si https://example.com/api | head -20需要注意的是-v会把 Authorization、Cookie 这类敏感头原样打印出来所以在 CI 日志里使用要谨慎可能造成凭证泄漏。这也是为什么我建议在脚本里用-sS而不是-v。6.2 -w 自定义输出格式一次拿到状态码与各阶段耗时-w是 curl 里被低估最多的选项。它能按模板输出一堆内置变量把一次请求的各阶段耗时、状态码、实际地址、传输字节数全部打印出来配合-o /dev/null就得到一个轻量的接口性能探针。curl -s -o /dev/null -w dns解析: %{time_namelookup}s 建连: %{time_connect}s TLS握手: %{time_appconnect}s 首字节: %{time_starttransfer}s 总耗时: %{time_total}s HTTP状态: %{http_code} 下载字节: %{size_download} 实际地址: %{url_effective} 重定向次数: %{num_redirects} https://example.com/api这几个时间点的关系能说明很多问题。time_namelookup大说明 DNS 慢通常是 DNS 服务器配置有问题或者解析链路太长。time_connect与time_namelookup的差值大说明网络往返延迟高。time_appconnect与time_connect的差值就是 TLS 握手耗时如果这个值异常大通常是证书链太长或者吊销检查在超时。time_starttransfer与time_appconnect的差值接近服务端处理时间能直接反映出后端的响应速度。这几个数字一摆出来问题归属到哪一层就非常清楚了。提示-w的模板字符串里换行可以直接写但如果放在 shell 的双引号里%不需要转义。想输出字面的百分号写%%。6.3 抓 SSE 流式接口与长时间连接的注意事项现在越来越多接口是流式返回的服务端持续推送数据块用 curl 调试这类接口时默认的缓冲行为会让你感觉卡住了没有任何输出。实际上数据在陆续到达只是被行缓冲挡住了。# 关闭缓冲实时看到流式输出 curl -N -s https://example.com/stream/events # 加上超时限制避免流式连接一直挂着 curl -N -s --max-time 60 https://example.com/stream/events-N是关闭输出缓冲的关键参数。另外流式接口通常不会正常结束连接会一直保持所以--max-time几乎是必须的。如果只是想观察几十秒的数据格式用timeout 30 curl -N -s ...从外部加时限也可以两种方式效果类似。调试流式接口时还有个实用技巧把输出重定向到文件再逐行看避免终端被刷屏。timeout 20 curl -N -s https://example.com/stream/events /tmp/stream.log wc -l /tmp/stream.log tail -5 /tmp/stream.log这样能清楚看到这段时间内到达了多少条事件、格式对不对、有没有心跳包比盯着滚动的终端有用得多。7. 脚本化落地把 curl 放进运维与 CI 流程命令行敲和写进脚本是两回事。脚本里要考虑退出码传播、重试策略、凭证管理、并发控制这些才是 curl 在生产环境里真正的难点。7.1 退出码与 set -e 的配合shell 脚本里如果写了set -e任何一条命令返回非零都会让脚本立即退出。curl 只要没加--failHTTP 500 也会返回退出码 0脚本会当成功继续往下跑这是很多构建成功了但产物是错的问题的根源。所以脚本里使用 curl 有两条铁律下载和调用接口一律加-f或--fail-with-body如果有哪次失败是可以容忍的显式用|| true或者在if条件里调用不要依赖隐式行为。#!/usr/bin/env bash set -euo pipefail APIhttps://api.example.com # 失败的调用会让脚本退出且能看到错误详情 curl -fsS --fail-with-body --max-time 20 ${API}/health -o /tmp/health.json # 允许失败的调用明确写在 if 里 if ! curl -fsS --max-time 10 ${API}/optional -o /tmp/optional.json; then echo 可选接口不可用继续执行 2 fiset -o pipefail这一条在管道场景里也很重要。curl ... | sh这种写法如果没有 pipefailsh 的退出码会覆盖 curl 的退出码下载失败但脚本解析失败被掩盖的情况就会发生。加上 pipefail管道里任何一段失败都会传播出来。7.2 重试、超时与并发控制的参数组合生产脚本里的 curl 调用基本都应该带上超时和重试。推荐的组合是curl -fsSL \ --connect-timeout 10 \ --max-time 60 \ --retry 3 \ --retry-delay 2 \ --retry-max-time 180 \ --retry-connrefused \ -o /tmp/artifact.tar.gz \ https://example.com/artifact.tar.gz这套参数的含义是建连最多等 10 秒整个请求最多 60 秒失败后重试 3 次、每次间隔 2 秒、重试总时长不超过 180 秒遇到连接被拒绝也重试。--retry-connrefused这个选项在服务刚启动还没就绪的场景下很有用比如容器编排里等待依赖服务起监听。需要批量请求时不要写一个 for 循环串行跑几十个请求会慢到不可接受。用xargs -P做并发控制cat urls.txt | xargs -P 8 -I {} sh -c code$(curl -s -o /dev/null -w %{http_code} --max-time 10 {}) echo {} $code -P 8表示最多 8 个并发。这个数字别开太大容易把对端打挂也会让本机的文件描述符和连接数紧张。8 到 16 之间对大多数场景是合适的。7.3 认证信息不进历史记录--netrc、-K 配置文件直接在命令行里写-H Authorization: Bearer xxx有两个问题一是会进 shell 历史记录二是会出现在ps输出里同机器上的其他用户能看到。生产脚本里应该从环境变量读取或者用 curl 的配置文件。-K可以指定一个配置文件把常用参数写进去# /etc/curlrc-app (权限设为 600) header Authorization: Bearer abc123 connect-timeout 10 max-time 60 retry 3 silent true show-error truecurl -K /etc/curlrc-app https://api.example.com/data配置文件的语法是每行一个选项名 值和命令行参数一一对应参数名前面不用加--短横线保持一致。这样做的好处是凭证不出现在命令行和历史里同时把一批公共参数集中管理脚本里只保留和业务相关的部分可读性提升明显。另一个方案是--netrc-file专注于用户名密码认证格式是三段式machine api.example.com login myuser password mypassword配合curl -n --netrc-file /path/to/netrc使用。这个文件同样要设置成chmod 600并且不要提交到任何代码仓库。如果是 CI 环境把内容放进受保护的密钥变量在流水线里临时生成这个文件、用完立即删除是比较稳妥的做法。注意配置文件里的选项是默认值命令行里显式写的参数会覆盖它。所以不用怕全局配置会影响所有调用需要临时覆盖的时候直接加参数就行。用 curl 这些年我最大的体会是这个工具的报错其实非常诚实它在尽力告诉你哪一层出了问题只是信息被压缩成了几个数字和短语不熟悉的人容易慌。真正值钱的经验不是记住所有参数而是养成一个习惯看到报错先确认版本和系统时间再按 DNS、网络、TLS、HTTP 这个顺序分层排查一层确认没问题再往下一层走别跳步。另外强烈建议在自己的机器上准备一份~/.curlrc把connect-timeout、max-time、retry、silent、show-error这几项设成默认值你会发现日常调试的体验顺滑很多至少在终端里不会再被卡死的连接和一堆进度条打扰。
