命令行与文本处理 / 知识点
curl 参数速查手册
请求方法与基础行为
显式修改 HTTP 请求方法字符串。
-X / --request · 指定请求方法
什么时候查:当你在 curl 命令里看到 -X,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
显式修改 HTTP 请求方法字符串。
参数形式
curl -X <METHOD> <URL>关键行为
只改变方法名,不会自动改变 curl 的 body、上传或 HEAD 等内部行为。
示例
curl -sS -X DELETE https://example.com/api/items/123易混参数
真正的 HEAD 用 -I;普通 POST 通常让 -d/--json/-F 自动选择。
风险与边界
不要为了“显式”给所有请求都加 -X,容易制造方法和实际行为不一致。
让 data 类参数拼到 URL query,并使用 GET。
-G / --get · 把 data 放到查询字符串
什么时候查:当你在 curl 命令里看到 -G,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
让 data 类参数拼到 URL query,并使用 GET。
参数形式
curl -G <URL>关键行为
常与 --data-urlencode 搭配安全生成查询参数。
示例
curl -sS -G --data-urlencode 'q=hello world' https://example.com/search易混参数
不加 -G 时 -d/--data-urlencode 通常发送请求体。
风险与边界
外部输入不要手工字符串拼 URL。
HTTP 下真正发送 HEAD,只取头部。
-I / --head · 发送 HEAD 请求
什么时候查:当你在 curl 命令里看到 -I,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
HTTP 下真正发送 HEAD,只取头部。
参数形式
curl -I <URL>关键行为
它会改变请求语义,而不仅仅是隐藏响应体。
示例
curl -sS -I https://example.com/易混参数
-I 和 -i 完全不同:-I=HEAD;-i=正常请求+显示响应头。
风险与边界
部分服务 HEAD 与 GET 实现不同,HEAD 正常不能证明 GET 一定正常。
只解析并连接 IPv4 地址。
-4 / --ipv4 · 仅使用 IPv4
什么时候查:当你在 curl 命令里看到 -4,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
只解析并连接 IPv4 地址。
参数形式
curl -4 <URL>关键行为
双栈域名存在 A/AAAA 时只走 A 记录路径。
示例
curl -4 -sS https://example.com/易混参数
与 -6 互斥,常用于区分 IPv4/IPv6 路径故障。
风险与边界
适合定位问题,不建议把它作为长期掩盖 IPv6 故障的方案。
只解析并连接 IPv6 地址。
-6 / --ipv6 · 仅使用 IPv6
什么时候查:当你在 curl 命令里看到 -6,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
只解析并连接 IPv6 地址。
参数形式
curl -6 <URL>关键行为
目标没有 AAAA、本机 IPv6 不可用或路由异常时失败。
示例
curl -6 -sS https://example.com/易混参数
与 -4 互斥。
风险与边界
用于单独验证 IPv6 DNS、路由、TLS 和服务监听。
覆盖 curl 默认 User-Agent。
-A / --user-agent · 设置 User-Agent
什么时候查:当你在 curl 命令里看到 -A,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
覆盖 curl 默认 User-Agent。
参数形式
curl -A <STRING> <URL>关键行为
服务端日志和应用可据此识别调用来源。
示例
curl -sS -A 'Anystack-Monitor/1.0' https://example.com/health易混参数
也可用 -H User-Agent:,但 -A 语义更直接。
风险与边界
不要用它伪装浏览器绕过访问控制或服务条款。
设置 HTTP Referer 请求头。
-e / --referer · 设置 Referer
什么时候查:当你在 curl 命令里看到 -e,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
设置 HTTP Referer 请求头。
参数形式
curl -e <URL> <URL>关键行为
常用于复现浏览器请求或调试来源校验。
示例
curl -sS -e 'https://example.com/' https://example.com/page易混参数
也可用 -H Referer:。
风险与边界
Referer 不是可信身份凭据。
声明 curl 支持其可解码的压缩,并自动解压响应。
--compressed · 请求压缩并自动解压
什么时候查:当你在 curl 命令里看到 --compressed,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
声明 curl 支持其可解码的压缩,并自动解压响应。
参数形式
curl --compressed <URL>关键行为
输出得到解压后的正文。
示例
curl -sS --compressed https://example.com/api/data易混参数
与只手写 Accept-Encoding 不同,它同时负责解码。
风险与边界
需要分析原始压缩字节时不要使用。
请求体与表单
发送 HTTP data,常用于 application/x-www-form-urlencoded POST。
-d / --data · 发送表单风格数据
什么时候查:当你在 curl 命令里看到 -d,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
发送 HTTP data,常用于 application/x-www-form-urlencoded POST。
参数形式
curl -d <DATA> <URL>关键行为
以 @ 开头时可读取文件;从文件读取时会有文本化处理。
示例
curl -sS -d 'name=alice&active=true' https://example.com/api/users易混参数
字面 @ 用 --data-raw;二进制用 --data-binary;需要编码用 --data-urlencode。
风险与边界
多次使用时 data 片段会按规则合并。
接近 --data,但不把 @ 特殊解释为文件。
--data-raw · data 但不解释 @
什么时候查:当你在 curl 命令里看到 --data-raw,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
接近 --data,但不把 @ 特殊解释为文件。
参数形式
curl --data-raw <DATA> <URL>关键行为
适合请求体本身可能以 @ 开头。
示例
curl -sS --data-raw '@literal-value' https://example.com/api/raw易混参数
它不是“二进制模式”;原样字节发送看 --data-binary。
风险与边界
默认 Content-Type 仍遵循 data 类请求行为。
版本边界
7.43.0+
尽量按字节原样发送数据,适合文件、二进制和必须保留换行的 body。
--data-binary · 原样发送请求体
什么时候查:当你在 curl 命令里看到 --data-binary,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
尽量按字节原样发送数据,适合文件、二进制和必须保留换行的 body。
参数形式
curl --data-binary <DATA> <URL>关键行为
@file 读取文件时不会像普通 --data @file 那样剥离特定换行/NUL。
示例
curl -sS --data-binary @payload.bin -H 'Content-Type: application/octet-stream' https://example.com/upload/raw易混参数
与 --data-raw 区别:binary 强调内容原样;raw 主要是不解释 @。
风险与边界
不会自动把 Content-Type 改成 octet-stream,需按 API 约定设置。
发送 data 时对指定内容进行 URL 编码。
--data-urlencode · URL 编码 data
什么时候查:当你在 curl 命令里看到 --data-urlencode,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
发送 data 时对指定内容进行 URL 编码。
参数形式
curl --data-urlencode <DATA> <URL>关键行为
适合中文、空格、&、= 等特殊字符。
示例
curl -sS -G --data-urlencode 'q=hello world' https://example.com/search易混参数
与 -G 组合生成 query;不加 -G 时通常进入请求体。
风险与边界
复杂脚本建议固定清晰的 name=value 形式。
JSON 请求快捷参数。
--json · 发送 JSON 请求体
什么时候查:当你在 curl 命令里看到 --json,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
JSON 请求快捷参数。
参数形式
curl --json <JSON|@FILE|@-> <URL>关键行为
等价于 --data-binary + JSON Content-Type + JSON Accept;curl 不校验 JSON 语法。
示例
curl -sS --json '{"name":"alice","enabled":true}' https://example.com/api/users易混参数
比手写 -H + --data-binary 更简洁;支持 @file 和 @-。
风险与边界
与 --form、--head、--upload-file 互斥;旧版本可能不支持。
版本边界
7.82.0+
创建 multipart/form-data 字段或文件上传字段。
-F / --form · 发送 multipart 表单
什么时候查:当你在 curl 命令里看到 -F,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
创建 multipart/form-data 字段或文件上传字段。
参数形式
curl -F <NAME=CONTENT> <URL>关键行为
curl 自动生成 boundary 与 Content-Type。
示例
curl -sS -F 'name=alice' -F 'file=@report.pdf' https://example.com/upload易混参数
普通字符串且内容可能以 @/< 开头时看 --form-string。
风险与边界
不要手工固定 multipart boundary。
创建 multipart 普通字符串字段,不让 @、< 触发文件语义。
--form-string · multipart 字面量字段
什么时候查:当你在 curl 命令里看到 --form-string,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
创建 multipart 普通字符串字段,不让 @、< 触发文件语义。
参数形式
curl --form-string <NAME=STRING> <URL>关键行为
字段内容按字面量处理。
示例
curl -sS --form-string 'note=@not-a-file' https://example.com/form易混参数
与 -F 相比更适合明确纯文本字段。
风险与边界
它不是文件上传参数。
把文件作为上传内容发送到目标 URL。
-T / --upload-file · 直接上传文件
什么时候查:当你在 curl 命令里看到 -T,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
把文件作为上传内容发送到目标 URL。
参数形式
curl -T <FILE> <URL>关键行为
HTTP 场景通常对应 PUT 风格上传,其他协议按各自规则。
示例
curl -sS -T artifact.bin https://example.com/upload/artifact.bin易混参数
multipart API 用 -F,原始文件/PUT 上传才优先 -T。
风险与边界
服务端必须支持对应上传方式;-T - 可从 stdin 读取。
Header、响应与输出
向请求添加自定义 Header,也可覆盖 curl 默认 Header。
-H / --header · 添加、覆盖或移除 Header
什么时候查:当你在 curl 命令里看到 -H,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
向请求添加自定义 Header,也可覆盖 curl 默认 Header。
参数形式
curl -H <HEADER|@FILE> <URL>关键行为
重复使用可添加多个;空值形式可用于移除某些默认 Header。
示例
curl -sS -H 'Accept: application/json' -H 'X-Request-ID: req-123' https://example.com/api易混参数
Content-Type 描述请求体;Accept 描述期望响应类型。
风险与边界
Authorization、Cookie 等敏感 Header 很容易进入 Shell 历史或调试日志。
把响应头放在正常正文之前一起输出。
-i / --show-headers · 显示响应头和正文
什么时候查:当你在 curl 命令里看到 -i,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
把响应头放在正常正文之前一起输出。
参数形式
curl -i <URL>关键行为
不会改变 GET/POST 请求方法。
示例
curl -sS -i https://example.com/api易混参数
-i ≠ -I:前者显示头+正文;后者真正发送 HEAD。
风险与边界
从 curl 8.10.0 起长名称是 --show-headers,旧名 --include 仍可用。
版本边界
长名称 8.10.0 起为 --show-headers
把收到的协议头部写到文件。
-D / --dump-header · 单独保存响应头
什么时候查:当你在 curl 命令里看到 -D,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
把收到的协议头部写到文件。
参数形式
curl -D <FILE> <URL>关键行为
适合与 -o 配合保存完整 HTTP 现场。
示例
curl -sS -D headers.txt -o body.json https://example.com/api易混参数
与 -i 不同,Header 不会混进正文输出。
风险与边界
Header 可能包含 Set-Cookie、内部地址和追踪信息,分享前脱敏。
把响应体保存到明确的本地文件名。
-o / --output · 指定输出文件
什么时候查:当你在 curl 命令里看到 -o,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
把响应体保存到明确的本地文件名。
参数形式
curl -o <FILE> <URL>关键行为
适合脚本固定输出路径。
示例
curl -fL -o app.tar.gz https://example.com/download易混参数
-o 用指定名字;-O 用远端 URL 文件名。
风险与边界
HTTP 错误页也可能写入文件,下载脚本通常搭配 --fail。