curl 常用法速查：HTTP 请求、文件传输与网络排障

curl 是命令行数据传输工具，常用于调用 HTTP API、下载文件、检查响应和定位网络问题。以下示例使用保留的示例域名，实际使用时替换为目标地址；路径、用户和令牌均为占位示例。

1. 基本格式与运行环境

curl [选项] "URL"
curl --version
curl --help all

• 普通 HTTP 请求默认使用 GET，响应正文输出到终端。
• URL 建议始终加引号，避免 &、? 等被 Shell 解释。
• 下面的命令按 Bash 写法展示，并尽量使用单行；Windows PowerShell 中建议将命令名换成 curl.exe。Windows PowerShell 5.1 的 curl 常是 Invoke-WebRequest 的别名，参数含义不同。
• Bash 多行续行用反斜杠，PowerShell 用反引号，CMD 用 ^，不要直接混用。
• Windows PowerShell 5.1 及部分旧版 PowerShell 的原生命令参数传递可能改变内联 JSON 的引号。发送 JSON 时优先从 UTF-8 无 BOM 文件读取。

2. GET 与查询参数

直接请求：

curl "https://api.example.com/users?page=1&size=10"

让 curl 编码查询参数：

curl -G "https://api.example.com/search" --data-urlencode "q=hello world" --data-urlencode "page=1"

-G 将数据放进 URL 查询串并使用 GET；--data-urlencode 处理空格、中文及特殊字符，避免手工拼接参数时出错。

3. 响应头、状态码与重定向

curl -i "https://api.example.com/users"
curl -I "https://example.com"
curl -L "https://example.com"
curl -D headers.txt -o body.txt "https://example.com"
curl -sS -o response.json -w "HTTP %{http_code}\n" "https://api.example.com/users"

选项	含义
-i	将响应头与正文一起输出
-I	发起 HEAD 请求，只获取头部；有些服务不支持 HEAD
-L	跟随 HTTP 重定向，curl 默认不自动跟随
-D 文件	将响应头保存到文件
-o 文件	将响应正文保存到指定文件
-sS	关闭进度显示，同时保留 curl 错误信息
-w 格式	传输结束后输出状态码、耗时等信息

要检查真实 GET 的响应头，用 -D，不要把 HEAD 的结果等同于 GET。跟随重定向时，POST 在部分 301、302、303 情况下可能变成 GET；307、308 通常保留方法和正文。不要随手添加 -X POST 来修正重定向行为。

4. POST：JSON、表单与原始数据

JSON 请求

先准备 UTF-8 无 BOM 的 payload.json：

{
  "name": "demo",
  "enabled": true
}

通用写法：

curl "https://api.example.com/users" -H "Content-Type: application/json" --data-binary "@payload.json"

curl 7.82.0 及以上支持简写：

curl "https://api.example.com/users" --json "@payload.json"

--json 相当于发送原始数据，并设置 Content-Type: application/json 和 Accept: application/json；它不会校验 JSON 内容是否合法。以上数据选项在未指定其他方法时会触发 POST，一般无需额外写 -X POST。

URL 编码表单

curl "https://api.example.com/form" --data-urlencode "name=hello world" --data-urlencode "role=reader"

选项	适用场景
-d "a=1&b=2"	已自行编码的表单数据，默认类型为 application/x-www-form-urlencoded
--data-urlencode "字段=值"	自动 URL 编码每个字段值
--data-binary "@文件"	保留文件原始字节，适合 JSON、文本或二进制请求体
--json "@文件"	JSON 请求的便捷写法
-F "字段=值"	multipart/form-data 表单，常用于上传文件

-d 不会自动把任意字符串转换成 JSON，也不会自动 URL 编码字段值。-d @文件 读取文件时会处理换行等内容；需要保留原始字节时使用 --data-binary。

5. PUT、PATCH 与 DELETE

curl -X PUT "https://api.example.com/users/123" --json "@payload.json"
curl -X PATCH "https://api.example.com/users/123" --json "@patch.json"
curl -X DELETE "https://api.example.com/users/123"

-X 指定 HTTP 方法，接口的具体语义由服务端定义。通常 PUT 用于整体替换，PATCH 用于部分修改，DELETE 用于删除。示例中的 patch.json 需要按接口约定准备；某些 PATCH 接口要求专用 Content-Type。

6. 自定义请求头、认证与 Cookie

curl "https://api.example.com/me" -H "Accept: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
curl -u demo_user "https://api.example.com/me"
curl -c cookies.txt "https://example.com"
curl -b cookies.txt -c cookies.txt "https://example.com/account"

• -H 可重复使用，添加多个请求头。
• -u demo_user 不在命令中附带密码，curl 会交互式提示输入；默认 HTTP Basic 认证应配合 HTTPS。
• -c 保存 Cookie，-b 读取并发送 Cookie；同时使用可持续更新 Cookie 文件。
• 保存 Cookie 本身不代表完成登录，认证流程仍由应用决定。
• 令牌、密码和 Cookie 不应写进知识笔记或提交到仓库；复制调试命令及 -v 输出前注意脱敏。

7. 下载、断点续传与上传

指定下载文件名、使用 URL 中的文件名、尝试续传：

curl -fL -o archive.zip "https://example.com/files/archive.zip"
curl -fLO "https://example.com/files/archive.zip"
curl -fL -C - -o archive.zip "https://example.com/files/archive.zip"

• -o 指定本地文件名；大写 -O 使用 URL 路径中的文件名，-fLO 是 -f -L -O 的组合。
• -C - 从现有文件长度继续下载，需要服务端支持范围请求，并确认远端文件未变化。
• -f 在 HTTP 400 及以上错误时通常返回非零退出码，并抑制错误响应正文；下载脚本可据此判定失败。

multipart 文件上传：

curl "https://api.example.com/upload" -F "file=@report.pdf" -F "description=demo"

原始文件上传到支持 HTTP PUT 的接口：

curl -T report.pdf "https://example.com/uploads/report.pdf"

-F 中的 @ 表示读取文件。multipart 的 Content-Type 和 boundary 由 curl 自动生成，不要手写不完整的 multipart Content-Type。-T 在 HTTP 场景下默认使用 PUT，是否可上传取决于服务端支持。

8. 超时、重试与脚本错误处理

适合读取类 API 的模板：

curl -sS --fail-with-body --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 -o response.json -w "HTTP %{http_code}\n" "https://api.example.com/health"

• --connect-timeout 5：限制连接阶段时间，覆盖 DNS 解析、连接建立和相关握手。
• --max-time 20：限制单次传输时间；存在重试时，总耗时可能超过 20 秒。
• --retry 2：对 curl 认定的暂时性失败最多额外重试两次，不代表所有错误都会重试。
• --retry-delay 1：将重试等待时间设为 1 秒。
• --retry-max-time：限制是否继续发起重试的时间窗口，窗口内已启动的传输仍可能继续。
• --fail-with-body：HTTP 错误时保留响应正文，并通常返回退出码 22；需要 curl 7.76.0 及以上。与 -o 配合时，错误正文也会写入该文件。
• 重试 POST 等有副作用的请求前，需要确认接口支持幂等键或重复请求不会造成重复操作。

HTTP 状态码与 curl 进程退出码是两回事。 默认收到 HTTP 404、500 时，curl 仍可能退出为 0，因为网络传输已经完成；脚本应结合失败选项、HTTP 状态码和业务响应判断结果。

Bash 可在命令后读取 $?，PowerShell 可读取 $LASTEXITCODE。常见 curl 退出码：

退出码	常见含义
6	无法解析目标主机
7	无法连接目标
22	配合失败选项时遇到 HTTP 错误
28	超时
35	TLS/SSL 握手失败
60	TLS 证书验证失败

9. 代理、指定 IP 与 IPv4/IPv6

HTTP 代理与 SOCKS5 代理：

curl -x "http://127.0.0.1:7890" "https://example.com"
curl -x "socks5h://127.0.0.1:1080" "https://example.com"
curl --noproxy "*" "https://example.com"

socks5h:// 让代理端解析域名；socks5:// 一般在本地解析域名。--noproxy "*" 用于禁用当前请求的代理，方便与代理路径对照。

保持域名、Host 和 TLS SNI，同时把连接定向到指定 IP：

curl --resolve "example.com:443:203.0.113.10" "https://example.com"

适合在直连场景验证指定服务器。直接把 HTTPS URL 的域名改成 IP，可能引入证书匹配和 SNI 问题。203.0.113.10 是文档示例地址，需要替换。

分别测试 IPv4 与 IPv6：

curl -4 "https://example.com"
curl -6 "https://example.com"

10. 网络排障、耗时与流式响应

查看连接、TLS、请求头和响应头：

curl -v --connect-timeout 5 --max-time 20 "https://example.com"

打印关键耗时，以下使用 Linux/macOS 的空设备：

curl -sS -o /dev/null -w "code=%{http_code} dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s first_byte=%{time_starttransfer}s total=%{time_total}s\n" "https://example.com"

Windows 中使用 curl.exe，并将 /dev/null 换成 NUL。CMD 的 .bat 文件里，格式字符串中的 % 通常需要写为 %%；PowerShell 不需要这样改写。

这些时间是相对于传输开始的累计指标：

• time_namelookup：域名解析完成时间。
• time_connect：TCP 连接建立时间。
• time_appconnect：TLS 等应用层握手完成时间。
• time_starttransfer：收到首字节的时间，包含此前的网络阶段和服务端处理时间。
• time_total：总传输时间。

在单次直连 HTTPS 请求下，相邻指标相减可粗略估算各阶段耗时；代理、连接复用和重定向会改变解释，不能把首字节时间直接当成服务端处理时间。

读取 SSE 等流式响应：

curl -N "https://api.example.com/events"

-N 关闭 curl 自身的输出缓冲，但不能消除服务端或代理的缓冲。

证书验证失败时，优先检查证书链、主机名、系统时间和信任库；需要自定义 CA 时使用：

curl --cacert ca.pem "https://example.com"

-k / --insecure 会跳过证书验证，只适合临时定位问题，不应作为长期修复。

11. 高频选项速记

需求	选项
GET 查询参数	-G --data-urlencode
JSON 请求体	--json @payload.json
指定方法 / 请求头	-X / -H
显示响应头 / HEAD	-i / -I
跟随跳转	-L
保存正文 / 保存响应头	-o / -D
按 URL 文件名保存	-O
上传表单文件	-F "file=@路径"
安静运行且保留错误	-sS
HTTP 错误返回失败且保留正文	--fail-with-body
连接超时 / 单次总超时	--connect-timeout / --max-time
查看连接过程 / 输出指标	-v / -w
指定代理 / 绕过代理	-x / --noproxy
指定域名连接 IP	--resolve
即时输出流式响应	-N

版本与资料

整理时本机 curl.exe --version 输出为 curl 8.21.0（Windows，Schannel）。本文未对示例域名发起接口请求；示例需结合实际接口、文件和运行环境调整。

• curl 官方命令手册
• Everything curl