3
0

curl

2026-06-22
软件用法
curl / 命令行 / HTTP

curl 命令详解

curl 是一个功能强大的命令行工具，用于在网络上传输数据，支持 HTTP、HTTPS、FTP、SFTP 等多种协议。

基本语法

curl [options] [URL]

请求方法

参数说明
-X, --request <METHOD>指定请求方法（GET、POST、PUT、DELETE 等）
-G, --get强制使用 GET 方法，将 -d 数据附加到 URL
curl -X GET https://api.example.com/users
curl -X POST https://api.example.com/users
curl -X DELETE https://api.example.com/users/1

请求头

参数说明
-H, --header <header>添加自定义请求头
-A, --user-agent <agent>设置 User-Agent
-e, --referer <URL>设置 Referer 头
--compressed请求压缩响应（自动处理解压）
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer token123" \
     https://api.example.com

curl -A "Mozilla/5.0" https://example.com

请求体与数据

参数说明
-d, --data <data>发送 POST 数据（application/x-www-form-urlencoded）
--data-raw <data>发送原始数据，不处理 @ 字符
--data-binary <data>以二进制方式发送数据
--data-urlencode <data>对数据进行 URL 编码后发送
-F, --form <name=value>发送 multipart/form-data 表单数据
-T, --upload-file <file>上传文件（PUT 方法）
-J, --remote-header-name使用服务器返回的文件名保存文件
# 发送 JSON 数据
curl -X POST https://api.example.com/users \
     -H "Content-Type: application/json" \
     -d '{"name":"Alice","email":"alice@example.com"}'

# 发送表单数据
curl -d "username=alice&password=secret" https://example.com/login

# 上传文件
curl -F "file=@/path/to/file.jpg" https://example.com/upload

# 从文件读取数据
curl -d @data.json https://api.example.com

响应处理

参数说明
-o, --output <file>将响应保存到指定文件
-O, --remote-name使用 URL 中的文件名保存响应
-i, --include在输出中包含响应头
-I, --head只获取响应头（HEAD 请求）
-D, --dump-header <file>将响应头保存到文件
-s, --silent静默模式，不显示进度信息
-S, --show-error静默模式下仍显示错误信息
-v, --verbose显示详细的请求和响应信息
--trace <file>将完整的调试信息保存到文件
-w, --write-out <format>输出自定义格式的统计信息
# 保存响应到文件
curl -o output.html https://example.com

# 显示响应头
curl -I https://example.com

# 显示完整请求响应过程
curl -v https://example.com

# 查看响应时间
curl -w "\nTime: %{time_total}s\nHTTP: %{http_code}\n" -o /dev/null -s https://example.com

认证

参数说明
-u, --user <user:password>设置 Basic 认证用户名和密码
--basic使用 HTTP Basic 认证
--digest使用 HTTP Digest 认证
--bearer <token>使用 Bearer Token 认证
--oauth2-bearer <token>使用 OAuth 2.0 Bearer Token
-n, --netrc从 ~/.netrc 文件读取认证信息
curl -u admin:password123 https://api.example.com
curl -H "Authorization: Bearer eyJhbGci..." https://api.example.com
参数说明
-b, --cookie <data/file>发送 Cookie（字符串或文件）
-c, --cookie-jar <file>将响应 Cookie 保存到文件
-j, --junk-session-cookies忽略会话 Cookie
# 发送 Cookie
curl -b "session=abc123" https://example.com

# 保存并复用 Cookie
curl -c cookies.txt https://example.com/login -d "user=alice&pass=secret"
curl -b cookies.txt https://example.com/dashboard

HTTPS / SSL/TLS

参数说明
-k, --insecure跳过 SSL 证书验证（不推荐在生产环境使用）
--cacert <file>指定 CA 证书文件
--capath <dir>指定 CA 证书目录
--cert <file[:password]>指定客户端证书文件
--key <file>指定私钥文件
--tlsv1.2强制使用 TLS 1.2
--tlsv1.3强制使用 TLS 1.3
--ssl-no-revoke禁用证书吊销检查
curl -k https://self-signed.example.com
curl --cacert /path/to/ca.crt https://internal.example.com

代理

参数说明
-x, --proxy <host:port>使用指定代理服务器
--socks5 <host:port>使用 SOCKS5 代理
--socks5-hostname <host:port>使用 SOCKS5 代理（DNS 也走代理）
--proxy-user <user:pass>代理认证
--noproxy <list>不使用代理的域名列表
curl -x http://proxy.example.com:8080 https://target.com
curl --socks5 127.0.0.1:1080 https://target.com

重定向

参数说明
-L, --location跟随 HTTP 重定向
--max-redirs <num>最大重定向次数（默认 30）
--location-trusted重定向时也发送认证信息
curl -L https://short.url/abc

超时与速率

参数说明
-m, --max-time <seconds>最大总时间（秒）
--connect-timeout <seconds>连接超时时间（秒）
--speed-limit <rate>最低传输速率（bytes/s）
--speed-time <seconds>低速超时时间（秒）
--limit-rate <rate>限制传输速率（如 100K、1M）
--retry <num>失败后重试次数
--retry-delay <seconds>重试间隔时间
--retry-max-time <seconds>重试最大总时间
curl -m 30 https://example.com
curl --connect-timeout 5 --retry 3 --retry-delay 2 https://example.com
curl --limit-rate 500K -O https://example.com/large-file.zip

并发与多 URL

参数说明
--parallel, -Z并行执行多个请求（curl 7.66+）
--parallel-max <num>最大并行连接数（默认 50）
# 同时下载多个文件
curl --parallel -O https://example.com/file1.zip \
                -O https://example.com/file2.zip \
                -O https://example.com/file3.zip

FTP 操作

参数说明
-T, --upload-file <file>上传文件到 FTP
--ftp-create-dirs自动创建远端目录
-P, --ftp-port <address>使用主动模式 FTP
--ftp-pasv使用被动模式 FTP
curl -u user:pass -T file.txt ftp://ftp.example.com/uploads/
curl -u user:pass ftp://ftp.example.com/file.txt -o local.txt

网络接口

参数说明
--interface <name>绑定到指定网络接口
--local-port <range>使用指定本地端口范围
-4, --ipv4强制使用 IPv4
-6, --ipv6强制使用 IPv6
--resolve <host:port:addr>自定义 DNS 解析
--dns-servers <servers>使用指定 DNS 服务器
curl -4 https://example.com
curl --resolve example.com:443:1.2.3.4 https://example.com

输出格式化

-w 参数支持多种变量，用于输出请求统计信息：

变量说明
%{http_code}HTTP 响应状态码
%{time_total}总耗时（秒）
%{time_connect}连接建立耗时
%{time_starttransfer}TTFB（首字节时间）
%{size_download}下载字节数
%{speed_download}下载速率（bytes/s）
%{url_effective}最终请求的 URL
%{remote_ip}服务器 IP 地址
%{remote_port}服务器端口
curl -o /dev/null -s -w "HTTP: %{http_code}\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\nIP: %{remote_ip}\n" \
     https://example.com

配置文件

参数说明
-K, --config <file>从配置文件读取参数
-q, --disable禁用 ~/.curlrc 配置文件

~/.curlrc 示例：

# 默认开启跟随重定向
location
# 默认显示错误
show-error
# 默认使用代理
# proxy = http://proxy.example.com:8080

常用实战示例

REST API 调用

# GET 请求
curl -s https://api.github.com/users/octocat | python3 -m json.tool

# POST JSON
curl -X POST https://api.example.com/items \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"name":"widget","price":9.99}'

# PUT 更新
curl -X PUT https://api.example.com/items/42 \
     -H "Content-Type: application/json" \
     -d '{"name":"updated widget"}'

# DELETE
curl -X DELETE https://api.example.com/items/42 \
     -H "Authorization: Bearer $TOKEN"

下载文件

# 下载并保留原文件名
curl -O https://example.com/archive.tar.gz

# 断点续传
curl -C - -O https://example.com/large-file.iso

# 下载并显示进度条
curl --progress-bar -O https://example.com/file.zip

调试请求

# 查看完整请求/响应头
curl -v https://example.com 2>&1 | less

# 只看响应头
curl -sI https://example.com

# 测量各阶段耗时
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://example.com

推荐资源

评论