5月28日 02:37

cURL 如何设置请求头（Headers）？

在 cURL 中，请求头（Request Headers）用于向服务器传递元数据，比如认证凭证、内容类型、客户端标识等。API 调试和接口对接时，设置请求头是最常见的操作之一。

基本语法

使用 -H 或 --header 参数添加请求头，格式必须为 "Name: Value"：

bash
curl -H "Header-Name: Header-Value" https://api.example.com

设置多个请求头时，每个 -H 单独写一个：

bash
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer token123" \
     -H "Accept: application/json" \
     https://api.example.com/users

常用请求头

bash
# Content-Type — 指定请求体格式
curl -H "Content-Type: application/json" \
     -d '{"name":"test"}' \
     https://api.example.com/users

# Authorization — 身份认证（Bearer Token）
curl -H "Authorization: Bearer your_token_here" \
     https://api.example.com/protected

# Authorization — HTTP Basic Auth
curl -H "Authorization: Basic $(echo -n 'user:pass' | base64)" \
     https://api.example.com/protected

# Accept — 告诉服务器你期望的响应格式
curl -H "Accept: application/json" \
     https://api.example.com/users

# User-Agent — 标识客户端
curl -H "User-Agent: MyApp/1.0" \
     https://api.example.com/data

# Cookie — 发送 Cookie
curl -H "Cookie: session_id=abc123; user_id=456" \
     https://api.example.com/profile

请求头	用途	常见值
Content-Type	请求体格式	application/json, application/x-www-form-urlencoded, multipart/form-data
Authorization	身份认证	Bearer token, Basic base64(user:pass)
Accept	期望的响应格式	application/json, text/html, /
User-Agent	客户端标识	Mozilla/5.0, MyApp/1.0
Cookie	发送 Cookie	session_id=abc123
Cache-Control	缓存控制	no-cache, no-store
Referer	来源页面	https://example.com/page

快捷选项

cURL 为几个常用请求头提供了专用选项，比 -H 更简洁：

bash
# -A / --user-agent — 设置 User-Agent
curl -A "MyApp/1.0" https://api.example.com/data

# -e / --referer — 设置 Referer
curl -e "https://example.com/page" https://api.example.com/data

# -b / --cookie — 设置 Cookie（也支持从文件读取）
curl -b "session_id=abc123; user_id=456" https://api.example.com/profile

# -b 从文件读取 Cookie
curl -b cookies.txt https://api.example.com/profile

删除请求头

cURL 默认会发送一些内部请求头（如 Host、Accept、User-Agent）。如果想删除某个默认头，将值设为空：

bash
# 删除默认的 Accept 头
curl -H "Accept:" https://api.example.com

# 删除默认的 User-Agent（某些反爬场景需要）
curl -H "User-Agent:" https://api.example.com

冒号后面没有任何内容，cURL 就不会发送该头部。

对于没有值的头部字段，在名称后加分号：

bash
curl -H "X-Empty-Header;" https://api.example.com

从文件读取请求头

请求头较多时，可以写入文件，用 @ 引用：

bash
# headers.txt 内容：
# Content-Type: application/json
# Authorization: Bearer token123
# X-Custom-Header: custom-value

curl -H @headers.txt https://api.example.com/users

每行一个请求头，格式与 -H 参数一致。

验证请求头是否生效

加 -v（verbose）参数可以看到实际发出的请求头，以 > 开头的行就是发出的头部：

bash
curl -v -H "Authorization: Bearer token123" \
     https://api.example.com/protected

# 输出中可以看到：
# > GET /protected HTTP/2
# > Host: api.example.com
# > Authorization: Bearer token123
# > User-Agent: curl/8.1.2
# > Accept: */*

也可以用 httpbin.org 快速验证，它会把收到的请求头原样返回：

bash
curl -H "X-Test: hello" https://httpbin.org/headers
# 返回 JSON 中会显示你发送的所有请求头

如果只想看响应头（以 < 开头的行），用 -I（HEAD 请求）或 -D -（转储响应头到 stdout）。

重复头部的处理

多次用 -H 设置同一个头部名称时，行为取决于 cURL 的内部实现：

bash
# 对标准头部（如 User-Agent），后者覆盖前者
curl -H "User-Agent: Agent1" -H "User-Agent: Agent2" URL
# 实际发送：User-Agent: Agent2

# 对自定义头部，cURL 可能发送多个同名头部
curl -H "X-Custom: value1" -H "X-Custom: value2" URL
# 可能发送两个 X-Custom 头部

大多数服务器按照 RFC 7230 将同名头部合并为逗号分隔的单个值。如果需要覆盖而非追加，用 -v 确认实际发送结果，或确保只写一次该头部。

特殊场景

发送压缩请求体：

bash
# 告诉服务器请求体是 gzip 压缩的
curl -H "Content-Encoding: gzip" \
     --data-binary @compressed.gz \
     https://api.example.com/upload

CORS 预检请求：

bash
# 模拟浏览器发送 OPTIONS 预检
curl -X OPTIONS \
     -H "Origin: https://example.com" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: X-Custom-Header" \
     https://api.example.com/data

带摘要认证（Digest Auth）：

bash
# curl 内置摘要认证支持，不必手动构造 Authorization 头
curl --digest -u user:pass https://api.example.com/protected

发送 multipart 表单时自动设置的头部：

bash
# -F 会自动设置 Content-Type: multipart/form-data; boundary=...
# 不要手动设置 Content-Type，否则会覆盖 boundary
curl -F "file=@photo.jpg" \
     -F "name=test" \
     https://api.example.com/upload

常见踩坑

1. 冒号后面没有空格

bash
# 可能出问题 — 部分服务端解析失败
curl -H "Content-Type:application/json" URL

# 推荐 — 冒号后加空格
curl -H "Content-Type: application/json" URL

HTTP 规范允许冒号后无空格，但实际中部分服务端解析会出问题，建议始终加空格。

2. 值含特殊字符未加引号

bash
# 错误 — 分号会被 shell 解释
curl -H Cookie: session=abc; user=123 URL

# 正确 — 整个头用双引号包裹
curl -H "Cookie: session=abc; user=123" URL

3. multipart 表单手动设置了 Content-Type

bash
# 错误 — 覆盖了 boundary，服务端无法解析
curl -H "Content-Type: multipart/form-data" -F "file=@data.bin" URL

# 正确 — 让 -F 自动设置 Content-Type
curl -F "file=@data.bin" URL

4. 后设置的头部覆盖前一个

bash
# 最终 User-Agent 是 Agent2
curl -H "User-Agent: Agent1" \
     -H "User-Agent: Agent2" \
     URL

对标准头部是覆盖行为，用 -v 确认实际发送结果。

标签：cURL