curl

1. `curl` 的基本语法

curl 的基本命令格式如下：


1
1
curl [options] [URL]

[options]：各种命令行标志，用于控制 curl 的行为（例如 -X POST）。
[URL]：你想要请求的网络地址。

2. 基础操作：获取数据 (GET)

默认情况下，curl 执行的是 GET 请求，并将响应的主体（Body）直接打印到标准输出（你的终端）。

2.1 基本 GET 请求


2
1
# 获取 example.com 的 HTML 内容并打印到屏幕
2
curl http://example.com

2.2 保存输出到文件 (-o / -O)

-o (小写)：将输出保存到你指定的文件名。


2
1
# 将 URL 的内容保存为 "page.html"
2
curl -o page.html http://example.com

-O (大写)：将输出保存到文件，文件名由 URL 的远程部分决定。


3
1
# URL: https://example.com/files/data.zip
2
# 将会下载并保存为 "data.zip"
3
curl -O https://example.com/files/data.zip

2.3 跟踪重定向 (-L)

默认情况下，curl 不会跟踪 HTTP 301/302 重定向。使用 -L (Location) 标志来让它跟踪。


4
1
# google.com 会重定向到 www.google.com
2
# 如果不加 -L，你只会得到一个 301 Moved 响应
3
# 加上 -L，curl 会跟踪跳转并获取最终页面的内容
4
curl -L http://google.com

2.4 显示进度条 (-#)

当你下载大文件时，curl 默认的进度表信息量很大。使用 -% (或 --progress-bar) 可以显示一个更简洁的进度条。


2
1
# 下载文件并显示一个漂亮的进度条
2
curl -# -O https://example.com/files/large-file.iso

3. 网络调试：查看详细信息

这部分是 curl 用于调试的精华。

3.1 Verbose 模式 (-v)

curl -v 会打印出所有详细的通信过程，包括你的请求头、SSL 握手信息和服务器的响应头。这对于调试 "为什么连接失败" 至关重要。


1
1
curl -v http://example.com

你会看到类似这样的输出：


15
1
* Trying 93.184.216.34:80...
2
* Connected to example.com (93.184.216.34) port 80 (#0)
3
> GET / HTTP/1.1
4
> Host: example.com
5
> User-Agent: curl/7.81.0
6
> Accept: */*
7
>
8
* Mark bundle as not supporting multiuse
9
< HTTP/1.1 200 OK
10
< Content-Type: text/html; charset=UTF-R
11
< Content-Length: 1256
12
< ... (省略其他响应头) ...
13
<
14
<!doctype html>
15
... (HTML 内容) ...

3.2 仅显示响应头 (-I)

使用 -I (大写 i) 会让 curl 发送一个 HEAD 请求。服务器只会返回响应头 (Headers)，不返回主体内容。这非常适合快速检查服务器状态、Content-Type 或重定向。


5
1
curl -I -L http://google.com
2
# 输出:
3
# HTTP/2 200
4
# content-type: text/html; charset=ISO-8859-1
5
# ...

3.3 显示响应头和主体 (-i)

使用 -i (小写 i) 会在输出中同时包含响应头和主体内容。


1
1
curl -i http://example.com

3.4 静默模式 (-s)

curl -s (silent) 会隐藏进度表和错误信息。这在脚本中非常有用，你只关心最终的输出数据。


3
1
# 在脚本中获取公网 IP，不显示任何额外信息
2
IP=$(curl -s https://ifconfig.me)
3
echo "My IP is: $IP"

专业提示： curl -sS 是一个常用组合，它在保持静默（-s）的同时，如果真的发生错误，仍然会显示错误信息（-S）。

4. API 调试：HTTP 方法与数据 (POST, PUT, DELETE)

这是 curl 作为 API 测试工具的核心功能。

4.1 指定请求方法 (-X)

使用 -X 标志来指定 GET 以外的 HTTP 方法。


5
1
# 发送一个 DELETE 请求
2
curl -X DELETE http://api.example.com/items/123
3
4
# 发送一个 PUT 请求
5
curl -X PUT http://api.example.com/items/123

4.2 发送 POST 数据 (-d 或 --data)

这是 POST 请求最常用的部分。

a) 发送 URL 编码的表单数据

当你使用 -d 时，curl 默认会使用 application/x-www-form-urlencoded 的 Content-Type 来发送数据。


5
1
# 发送 key=value 数据
2
curl -X POST -d "username=admin&status=active" http://api.example.com/login
3
4
# 如果数据包含特殊字符，用引号包围
5
curl -X POST -d "comment=Hello world!" http://api.example.com/comments

b) 发送 JSON 数据 (重要!) ⭐

现代 API 大多使用 JSON。当发送 JSON 时，你必须同时做两件事：

用 -d 传递 JSON 字符串。
用 -H (Header) 显式设置 Content-Type 为 application/json。


4
1
curl -X POST \
2
  -H "Content-Type: application/json" \
3
  -d '{"name":"New Item","price":199}' \
4
  http://api.example.com/items

c) 从文件读取 POST 数据

如果你的 JSON 数据非常大，可以先存在一个文件里（例如 data.json），然后使用 @ 符号来让 curl 读取文件内容。


6
1
# data.json 内容: {"name":"New Item","price":199}
2
3
curl -X POST \
4
  -H "Content-Type: application/json" \
5
  -d @data.json \
6
  http://api.example.com/items

4.3 发送文件 (Multipart/form-data) (-F)

当你需要上传文件（例如图片、zip），必须使用 -F (Form) 来发送 multipart/form-data 请求。


6
1
# 上传一个文件，就像在网页表单中点击 "Browse..."
2
# "@" 符号告诉 curl 这是一个文件路径
3
curl -X POST \
4
  -F "username=bob" \
5
  -F "profile_pic=@/home/user/avatar.jpg" \
6
  http://api.example.com/upload

5. 自定义请求：Headers 与认证

5.1 设置自定义请求头 (-H)

-H (Header) 标志可能是 curl 最强大的标志之一。


8
1
# 模拟浏览器 User-Agent
2
curl -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; ...)" http://example.com
3
4
# API Key 认证 (例如 Bearer Token)
5
curl -H "Authorization: Bearer YourApiTokenHere" http://api.example.com/me
6
7
# 组合使用
8
curl -H "Content-Type: application/json" -H "Accept-Language: en-US" ...

5.2 基本认证 (-u)

如果 API 使用的是 HTTP 基本认证 (Basic Auth)，curl 提供了简单的 -u 标志。


2
1
# curl 会自动将其编码为 Base64 并放入 Authorization 头中
2
curl -u "username:password" http://api.example.com/admin

curl 可能会提示你输入密码，以避免密码在命令行历史中暴露。

curl 可以模拟登录，因为它能处理 Cookies。

-c cookie-jar.txt：(Cookie Jar) 将服务器返回的 Cookies 保存到 cookie-jar.txt 文件中。
-b cookie-jar.txt：(Cookie) 从 cookie-jar.txt 文件中读取 Cookies 并发送给服务器。

示例：模拟登录


9
1
# 1. 登录并保存会话 cookie
2
curl -X POST \
3
  -d "user=admin&pass=12345" \
4
  -c cookies.txt \
5
  http://example.com/login
6
7
# 2. 携带 cookie 访问需要登录的页面
8
#    服务器会读取 cookie，识别出你已登录
9
curl -b cookies.txt http://example.com/dashboard

7. 安全与网络选项

7.1 忽略 SSL 证书验证 (-k)

curl -k (或 --insecure) 会跳过 SSL/TLS 证书的验证。

⚠️ 警告： 这非常不安全，会使你受到中间人攻击。仅在你完全信任网络，并且在测试使用自签名证书的开发服务器时使用。


2
1
# 访问一个使用自签名证书的本地开发服务器
2
curl -k https://dev.local:8443/

7.2 设置超时

--connect-timeout <seconds>：设置建立连接的超时时间。
--max-time <seconds>：设置整个操作（连接+数据传输）的总超时时间。


2
1
# 如果 5 秒内连不上，或 30 秒内没传完，就失败
2
curl --connect-timeout 5 --max-time 30 http://example.com

7.3 使用代理 (-x)


5
1
# 通过 http 代理
2
curl -x http://myproxy.example.com:8080 http://example.com
3
4
# 通过 socks5 代理
5
curl -x socks5://myproxy.example.com:1080 http://example.com

`curl` 快速备忘录

标志	全称	功能
`-o [file]`	`--output`	将输出保存到指定文件。
`-O`	`--remote-name`	使用 URL 中的文件名保存。
`-L`	`--location`	跟踪 HTTP 重定向。
`-v`	`--verbose`	显示详细的通信过程 (调试用)。
`-i`	`--include`	在输出中包含响应头。
`-I`	`--head`	(发 `HEAD` 请求) 仅获取响应头。
`-s`	`--silent`	静默模式，不显示进度或错误。
`-S`	`--show-error`	配合 `-s`，在出错时显示错误。
`-#`	`--progress-bar`	显示简洁的进度条。
`-X [METHOD]`	`--request`	指定 HTTP 方法 (如 `POST`, `PUT`, `DELETE`)。
`-H [header]`	`--header`	发送自定义请求头 (如 `Content-Type: ...`)。
`-d [data]`	`--data`	发送 `POST` 数据 (URL 编码)。
`-F [data]`	`--form`	发送 `multipart/form-data` (用于文件上传)。
`-u [user:pass]`	`--user`	HTTP 基本认证。
`-b [file]`	`--cookie`	从文件读取并发送 Cookies。
`-c [file]`	`--cookie-jar`	将收到的 Cookies 保存到文件。
`-k`	`--insecure`	忽略 SSL 证书验证 (不安全)。
`-x [proxy]`	`--proxy`	使用 HTTP/SOCKS 代理。

1. curl 的基本语法