Curl完全指南：从基础语法到高级实战技巧

说实话，curl这个工具，很多人都在用，但真正把它用明白的人并不多。工作里最常见的场景就是“接口报错了，你 curl 一下看看”，然后大家 curl 一下返回个 JSON，能看出个大概就算完事。但再往后呢？带 Cookie 的登录态怎么模拟？文件上传怎么传？批量请求怎么做？超时重试怎么配？这些一旦要正经用起来，很多人就开始现查现试了。

这篇文章我想系统性地把 curl 拆开讲一遍，从最基础的 URL 请求开始，一路讲到调试、认证、Cookie、文件传输、并发请求、脚本自动化，最后再补一批我在实际项目里踩过的坑。内容不追求大而全的手册式罗列，而是围绕“实际开发中真正用得上”这条主线来展开。无论你是刚接触命令行的新人，还是天天和接口打交道、却只把 curl 当成“高级 wget”的老手，这篇指南里应该都有你能直接抄走的东西。

1. curl到底能干什么，为什么值得系统掌握

1.1 一个被严重低估的命令行工具

curl 全称是 Command Line URL Tool，名字平平无奇，但它的能力覆盖面比大多数人想象中大得多。它不只是“命令行里发 HTTP 请求”那么简单，它支持的协议包括 HTTP、HTTPS、FTP、SFTP、SMTP、IMAP、POP3、LDAP、RTSP 等一长串。当然日常打交道最多的还是 HTTP/HTTPS，但知道它能干这么多事，你就能理解为什么很多运维脚本里，curl 是那个“万能触手”。

我见过不少人对 curl 的认知停留在 curl http://xxx，然后把返回内容打印到终端上就完事了。但实际上，curl 单是请求相关的参数就有几十个，再加上输出控制、连接控制、认证、代理、传输优化这些维度，组合起来能覆盖开发联调、线上排查、自动化巡检、数据抓取、文件同步等各种各样的场景。可以说，只要涉及“机器与机器之间的数据交换”，curl 几乎都是最先被想到的那批工具里的一个。

也有人觉得，现在图形化接口调试工具那么多，直接鼠标点点不就行了？确实，日常调试用图形化工具很方便，但 curl 有几个不可替代的场景：一是服务器上没法开图形界面，排查问题只能靠命令行；二是脚本化，你不可能让图形工具帮你跑定时任务；三是可复现性，一条 curl 命令可以直接贴给对方，对方复制就能跑，效率和沟通成本完全不一样。这也是为什么很多技术文档、接口文档、开源项目的 README 里，示例请求清一色都是 curl 命令。

1.2 什么人适合学，学到什么程度算学会

这篇内容适合三类人。第一类是刚开始接触命令行和 HTTP 协议的初学者，你可能连 -X POST 和 -d 是什么意思都还不清楚，没关系，我会从最原始的请求讲起，你跟着敲一遍就能理解。第二类是日常写代码、调接口的开发者，前端、后端、测试都算在内，你可能已经会用 curl 发 GET 和 POST 了，但遇到认证、Cookie、文件上传、代理这些场景时还是有点含糊，这篇文章会把常见的高级用法串起来讲。第三类是运维和 SRE 同学，你们大概率已经在脚本里用 curl 了，但你可能还不知道 --retry、--connect-timeout、--write-out 这些参数能帮你省多少事。

那“学会 curl”到底是一个什么状态？我的定义很朴素：给你一个接口文档，你能徒手写出对应的 curl 命令，并且对每个用到的参数都知道是干什么的、为什么要加、不加行不行；给你一个线上故障，你能用 curl 快速判断是网络问题、DNS 问题、证书问题、代理问题还是后端逻辑问题；给你一个自动化需求，你能把 curl 嵌进脚本里，配合条件判断和输出解析，完成接口监控或数据采集。达到这几条，curl 就算真正入门到实战了。

2. 基础语法与高频参数，先把地基打牢

2.1 从一条最简单的命令开始学起

curl 最基本的用法就是一句话：curl <URL>。你把 URL 给它，它把服务器返回的内容打印到标准输出。比如访问一个公开的 API，curl https://api.example.com/v1/users，返回的 JSON 文本直接就在终端里了。看着很简单，但哪怕是最简单的命令，也有几个隐藏细节值得说。

第一个细节是输出长度。接口返回内容很长时，终端显示不完整，很多人第一反应是“让后端把返回改短一点”，其实正确做法有很多：可以加 -o 保存到文件，curl -o resp.json https://api.example.com/v1/users；可以加 -s 静默模式，去掉进度条和错误信息，只保留响应内容本身，方便重定向到文件里做后续处理；还可以配合 jq 之类的工具做格式化，后面我会专门说。第二个细节是 URL 的引号问题。URL 里如果带 & 这种字符，在 shell 里会被解释成“后台执行”，命令行为直接就变了。所以只要 URL 里带了查询参数，我习惯一律加单引号或双引号包起来，这是新手最容易忽略、也最坑的一点。比如：

bash复制curl 'http://api.example.com/search?q=keyword&page=1'

不加引号的话，shell 会把 &page=1 之前的部分当成一个命令放到后台执行，后面那截直接成了另一个命令，结果完全不可控。

输出保存这里还有一个细节：-o 是用来“指定保存文件名”的，-O（大写字母 O）则是“用 URL 末端的文件名自动保存”。比如 curl -O https://example.com/files/report.pdf，它会自动保存成当前目录下的 report.pdf。如果你只是下载文件，用 -O 最省事；如果你想把接口返回存成自定义名字，用 -o。

2.2 请求方法与数据提交

HTTP 请求方法里，GET 是最常见的，但真实业务里 POST、PUT、DELETE、PATCH 一样天天见。curl 里指定请求方法有明确参数：-X。比如 curl -X DELETE http://api.example.com/users/123，发一个 DELETE 请求。

这里要特别提醒一个容易搞错的地方：很多人以为“只要加 -d 传数据，就必须配 -X POST”，这句话只说对了一半。-d 参数本身确实会触发 POST 请求，即使你没写 -X POST，curl 也会默认发 POST。问题出在当你用 -X PUT 或 -X PATCH 并且同时想传 body 时，-d 依然有效，但如果你用了类似 -X GET 再配 -d，服务器大概率会拒掉或者行为异常，因为 GET 带 body 本来就不是标准做法。

-d 传数据的方式是表单格式，也就是 key=value&key2=value2 这种，curl 会自动帮你做 URL 编码。如果需要传给后端的 JSON 字符串，推荐直接用 -H 'Content-Type: application/json' 加 -d '{"name":"test","age":18}' 的组合。有人会问为什么要显式指定 Content-Type？因为不指定的话，curl 默认会带 Content-Type: application/x-www-form-urlencoded，很多后端框架拿到 JSON 字符串却看到表单类型，解析直接失败。我调接口时第一步就先看请求头，Content-Type 不对，后端再怎么看也是白搭。

还有个参数叫 --data-urlencode，适合处理复杂字符串。比如你要提交一段文本，里面可能包含中文、空格、特殊字符，写成 -d 容易因为转义问题出错，用 --data-urlencode 'content=一段含特殊字符的文本' 就稳妥得多。

2.3 用 -i 和 -I 看清响应全貌

调试接口时，只看响应 body 是不够的，响应头里的状态码、Server 字段、Set-Cookie、缓存策略等信息往往才是问题的关键。curl -i http://api.example.com/users 会在响应 body 前面带上响应头，一条命令就能看到 HTTP 状态行、Header 和 Body 的完整内容。-I 则更极端一点，它只发 HEAD 请求，只拿响应头，不取 body。这个在“只看资源是否存在、只查 Content-Length、只想确认 Server 是否存活”的场景下非常高效。

实际排查问题的时候，我通常先 curl -I 快速确认服务通不通、返回什么状态码，然后再用 -i 看完整响应。如果状态码是 302 重定向，-i 的响应头里会有 Location 字段，就能看到它跳去了哪里；如果状态码是 401，你会看到 WWW-Authenticate 头，提示你要用哪种认证方式。这些信息，光看最终渲染出来的页面或者光看 body 是拿不到的。

3. 进阶技能：认证、Cookie、文件传输与代理

3.1 接口认证的三种常见解法

现实中很少有接口是裸奔的，最常见的认证方式有三种。第一种是 Basic Auth，直接在 URL 里带用户名密码，或者用 -u 参数：curl -u admin:secret http://api.example.com/private。这条命令等价于 curl 自动帮你算出 Authorization: Basic base64(admin:secret) 请求头。第二种是 Token 认证，最常见的 Bearer Token，需要手动加请求头：curl -H 'Authorization: Bearer eyJhbGci...' http://api.example.com/me。第三种是 Cookie 会话认证，登录之后服务端下发一个 Session Cookie，你在后续请求里把它带上，这个放到下一小节专门讲。

这三种方式对应不同的系统设计，但有一条通用经验分享一下：如果接口提示 401 Unauthorized，优先看响应头里的 WWW-Authenticate 字段，它会在一定程度上告诉你服务器期望的认证类型是 Basic 还是 Bearer。比对着文档猜快得多。

OAuth 2.0 的接口调试比前面几种稍微绕一点，因为通常需要先拿令牌再调业务接口。拿令牌这一步往往是一个 POST 请求，带上 client_id、client_secret、grant_type 等参数。拿到 access_token 之后，把 token 作为请求头发送。这种场景我在脚本里比较推荐两步走：第一步用 curl 请求令牌接口并保存响应；第二步把响应里的 token 解析出来组装下一个请求。解析 JSON 这事用 jq 最顺手，后面脚本化部分会给出完整示例。

3.2 维持会话：Cookie 的写入与发送

很多系统的登录态是基于 Cookie 的，模拟这种场景时，光发一次登录请求不够，你得把登录后返回的 Cookie 保留下来，再在后续请求里带上。curl 专门有两个参数干这事：-c 是“写 Cookie 到文件”，-b 是“从文件读取 Cookie 并发送”。

典型流程是这样的。第一步，用登录接口获取 Cookie 并保存到文件：

bash复制curl -c cookies.txt -d 'username=admin&password=123456' http://api.example.com/login

这一步执行完，cookies.txt 里通常会有 session ID 之类的字段。第二步，请求需要登录态的接口时，带上这个文件：

bash复制curl -b cookies.txt http://api.example.com/profile

这里有几个细节。第一，-c 和 -b 用的是同一个文件路径，文件格式是 Netscape Cookie 格式，把文本编辑器打开就能看到字段含义。第二，有些情况下服务端校验的不只是 Cookie，还有 Referer、Origin 这些头，如果登录后依然 403，可以对比浏览器里实际发的请求头，缺哪个补哪个。第三，Cookie 文件是有失效时间的，脚本常年跑的话，过期之后需要重新登录获取，这个逻辑要写到自动化任务里。

3.3 文件上传下载的完整姿势

文件上传是 curl 的强项。先说明确一点：-F 参数是用来模拟浏览器那种“表单文件上传”的，它支持 -F 'file=@/path/to/file' 这种写法。例如：

bash复制curl -F 'file=@./report.pdf' -F 'note=月度报告' http://api.example.com/upload

这条命令会以 multipart/form-data 格式提交请求，后端用常见的文件接收方案就能解析。注意文件路径前的 @ 必须有，它的意思是“把这个文件的内容作为字段值”。如果你想在字段名里自定义文件名，可以这样写：-F 'file=@./report.pdf;filename=final.pdf'，这在上传文件但希望服务端以另一个名字保存时非常实用。

下载文件的姿势前面提到过 -O 和 -o。实际下载场景里两个参数非常值得加：一个是 --limit-rate，限制下载速度，用来避免测试环境带宽被打满；另一个是 -C -，它是断点续传，比如下载到一半断了，重新执行时加上 -C -，curl 会自动从断点处继续下载。

上传这块还有一个容易踩的坑：-T 参数。它是用 HTTP PUT 方法直接传文件，语义是把文件内容放到指定的 URL 上，和浏览器表单上传完全不同。有些对象存储服务就是用 PUT 方式做直传的，但很多后端接口并不支持，所以拿到需求时先确认对方期望的是 multipart 表单还是 raw body 直传，别一上来就用 -F 硬怼。

3.4 代理与内网环境的正确保真

代理是我自己工作里踩过不少坑的地方。开发环境里经常会有正向代理，尤其是公司内网访问外部资源的时候，curl 默认不走代理的话就直接连接失败了。curl 支持两种方式指定代理：一是在命令里加 --proxy，比如 curl --proxy http://proxy.company.local:8080 http://external.example.com/api；二是读取环境变量，http_proxy、https_proxy、all_proxy 这些环境变量如果被设置了，curl 默认就会走代理。这里的坑在于中间环节：如果你在服务器上排查问题，发现 curl 超时，但浏览器能访问，十有八九是环境变量里代理设置和实际网络环境不一致导致的。多敲一句 env | grep -i proxy 就能看到当前代理配置。

另外，curl 默认对 localhost 和 127.0.0.1 的请求是直接连接的，不走代理。但“本机 IP”或者“内网其他机器”不一定在内置白名单里。如果你希望某些网段强制不走代理，可以用 --noproxy 参数，比如 --noproxy '*.local,10.0.0.0/8'。这个在调试本地服务和内网服务时特别有用。打个比方，你配置好了代理，结果所有请求都往代理拐了，本地 mock 服务反而连不上，排查半天才想起是代理问题，这个经历我太熟了。

4. 高级实践：调试接口、并发请求与自动化脚本

4.1 调试接口必备：-v 与 --trace 的正确打开方式

接口联调的时候最怕什么？怕你这边请求发出去了，后端说没收到，或者收到了但解析不出来。这时候你需要把整个请求链路拉出来看。curl -v 就是干这个的。它会输出请求连接的详细过程：DNS 解析结果、TCP 连接建立、TLS 握手细节、发送出去的请求头、接收的响应头以及最终 body。一行一行读下来，问题往往就现形了。

举个例子，curl -v https://api.example.com/login -d 'user=admin' 的输出大概是这样的模式：先是 * Connected to api.example.com，说明 TCP 连接没问题；然后是 TLS 相关的一串 * SSL connection using TLS...；接着是 > POST /login HTTP/1.1 这类箭头开头的行，表示发出去的请求内容；再往下 < HTTP/1.1 200 OK 之类的 < 开头的行，是响应内容。如果你发现请求头里的 Host 和你域名对不上，或者 Content-Length 是 0，那问题就很好定位了。

如果 -v 还不够细，可以上 --trace 或 --trace-ascii，它能把原始字节流都记录下来。哪边多了个空格、哪个字符被 URL 编码变了形，原始数据里看得一清二楚。我在处理签名类接口时特别喜欢用 --trace-ascii trace.txt，把请求原文保存下来，方便和签名规则逐字符比对。毕竟有时候问题不是参数对不对，而是字符串编码后和预期不一致。

4.2 并发与批量请求的高效玩法

单个请求能跑通，下一步就是批量执行。批量请求最原始的方式是写 shell 循环：

bash复制for id in 1 2 3 4 5; do
  curl -s "http://api.example.com/users/$id" -o "user_$id.json"
done

这个写法简单直接，但它是串行的，5 个请求慢没关系，如果要对几百上千个 URL 做探测，串行性能就太差了。提高并发度的思路有几种。一种是用 xargs 的 -P 参数指定并行度：

bash复制cat urls.txt | xargs -P 10 -I {} curl -s -o /dev/null -w "%{http_code} {}\n" {}

-P 10 表示同时跑 10 个进程，输出每个 URL 的状态码。另一种是用专门的并发工具，用于做压测或者批量探测时，效率和信息完整度更高。但如果你不想引入额外工具，curl 自己也有并发能力，不过不是多线程，而是用 --next 参数在同一命令行里发多个独立请求。例如：

bash复制curl http://api.example.com/a --next curl http://api.example.com/b --next curl http://api.example.com/c

实际批量探测场景里，我更喜欢把 URL 清单放文件里，配合脚本逐行读取，再根据输出结果分类处理。这样方便记录日志、统计成功率，后面就算要改成定时任务也容易维护。

4.3 把 curl 嵌进自动化脚本的几种典型套路

curl 本身是命令，真正的威力来自和 shell 脚本、其他命令行工具的组合。最常见的套路是接口健康检查：定时执行 curl，如果返回码不对或响应超时则触发告警。这里要用到 -f 参数，它让 curl 在遇到 HTTP 错误码（4xx、5xx）时直接静默失败，并返回非零退出码。脚本里就可以这么写：

bash复制if curl -sf -o /dev/null http://api.example.com/health; then
  echo "OK"
else
  echo "FAIL"
  # 触发告警的逻辑
fi

-o /dev/null 是把响应体丢掉，我们只关心状态；-s 是静默掉进度条；-f 保证失败时能被条件分支捕获。这是线上巡检脚本里最优美的一种写法。

另一种套路是接口返回 JSON，需要解析出字段继续下一步。比如先获取 token 再请求业务接口：

bash复制TOKEN=$(curl -s -d 'grant_type=client_credentials&client_id=xxx&client_secret=yyy' http://api.example.com/token | jq -r '.access_token')

curl -s -H "Authorization: Bearer $TOKEN" http://api.example.com/orders

这里 jq 是 JSON 解析器，-r 参数输出纯字符串而不是带引号的 JSON 字符串。token 提取出来赋给变量，下一行直接引用。这套写法我用了很多年，简单、可靠、易扩展。

还有一个我比较常用的参数是 --write-out，它可以在请求结束后输出自定义信息。配合格式化字符串，可以输出状态码、耗时、DNS 时间、下载大小等数据。例如：

bash复制curl -s -o /dev/null -w 'HTTP %{http_code} | time_total %{time_total}s | size %{size_download} bytes\n' http://api.example.com

这比肉眼盯着响应头看快多了，而且数据更结构化，直接重定向到日志做趋势分析都行。

5. 常见问题与避坑图谱

5.1 报错信息速查表

几个月实操下来，我把最常遇见的 curl 报错整理成了下面这个表，照着比对能少走很多弯路。

绝大多数“本地 curl 能通，服务器上不通”的问题，集中在前三行里。DNS、端口、超时，这是排查顺序上最高频的三板斧。

5.2 我在项目里踩过的几个坑

这里说几个我真实踩过、并且后来经常提醒别人的坑，希望你能直接绕开。

第一个坑是 URL 没加引号。某个接口地址带了 & 参数，我同学在脚本里写 curl http://api.example.com?a=1&b=2，结果命令执行后直接把 b=2 当成第二条命令解释了。那一次的排查经历特别典型：有人死活想不通为什么接口老报参数缺失，后来把命令打印出来才发现，传给 curl 的 URL 已经被 shell 截断了。从那以后，只要 URL 里可能有特殊字符，我必加引号。

第二个坑是 -d 和 -X POST 的混用。有些老后端对请求方法特别敏感，你 -X POST 加上 -d 没问题，但如果你把 -d 改成自定义请求体，比如 --data-binary 或者 --json，又混着 -X 改方法，很容易出现“我明明改了 PUT，后端却说收到了 POST”的诡异局面。原因是 -d 本来就默认 POST，-X 只是强行改方法名，两者叠加时不注意优先级和默认行为，很容易翻车。

第三个坑是 Cookie 文件路径的坑。写自动化脚本时，我习惯把 Cookie 文件放在临时目录，但有一次脚本进程的工作目录切换了，导致 -b cookies.txt 读不到文件，会话直接失效。后来我在所有脚本里都用绝对路径指定 Cookie 文件，再没出过类似问题。

第四个坑是自签名证书和 -k 参数。内网联调时经常遇到 HTTPS 证书是自签的，curl 默认会拦截，很多人习惯直接加 -k 跳过校验。这在本地测试阶段确实高效，但一旦脚本上线、连的是生产环境，-k 就相当于关掉了安全校验的大门。如果必须兼容自签名环境，更稳的做法是把这个证书下载下来，用 --cacert 参数指定给它，既保障了链路加密的可信度，也不用全局跳过校验。

5.3 安全使用与规避误伤的建议

curl 很强大，所以更要小心用。第一，不要在命令行直接写明文密码。curl -u admin:secret http://... 虽然是文档里最常见的示例，但它会把密码留在 shell history 里。稳妥做法是用 -u admin:secret 改成运行时提示输入密码：curl -u admin http://...，这样 curl 会交互式地让你输入密码，不会落盘。脚本环境里可以用环境变量或者密钥管理服务来存敏感信息，别硬编码在脚本里。

第二，在线上环境执行 curl 时，注意请求会不会触发线上写操作。尤其是一些 POST/PUT/DELETE 请求，在排查问题时很容易误操作，最好先在测试环境验证一遍命令完全正确，再考虑对线上发起请求。

第三，日志和输出信息的脱敏。curl 加了 -v 或 --trace 之后，输出的内容里可能包含 Authorization 头、Cookie、Token 之类的敏感数据。把这类日志直接贴到工单或者群里前，一定要检查一遍是否泄漏了敏感信息。

写在最后的一点私人经验

回头想想，curl 最打动我的一点是它的“可拼接性”：它不只是一个发请求的工具，而是能和其他命令、脚本、解析器无缝嵌合在一起的一条积木块。判断一个工具是否值得深入掌握，不是看它的功能列表有多长，而是看你能否在解决实际问题的过程中顺手就把它用进去。curl 对很多开发和运维场景来说，恰好就是这样一种“顺手”，因为你几乎不需要额外安装任何东西，它默认就在那里。

我自己最满意的一套组合拳是这样的：curl -s -f --connect-timeout 3 --max-time 10 配合 -w 输出耗时和状态码，再接到日志系统里做接口稳定性看板。这套方案不用写任何复杂的代码，轻量、可靠、覆盖了我绝大部分接口拨测需求。如果你也想从“会 curl”进阶到“用得好 curl”，建议从下一次联调开始，强迫自己不用图形化工具，纯命令行把接口完整跑一遍，你会很快找到感觉。

最后分享一个对我帮助很大的习惯：拿到一个新接口，不要急着去看封装好的 SDK 或者客户端工具，先用 curl 把原始请求、原始响应看一遍。你会发现很多让你迷惑的行为，在原始层都能一眼看穿。这个习惯，值得保留。