命令行与文本处理 / 知识点
curl 命令速查手册
基础请求与协议
curl --version确认 curl 版本、TLS 后端、支持协议以及 HTTP/2、HTTP/3、IPv6 等编译特性。
查看 curl 版本与特性
确认 curl 版本、TLS 后端、支持协议以及 HTTP/2、HTTP/3、IPv6 等编译特性。
基本语法
curl --version高频用法
curl --version预期结果:
首行显示 curl/libcurl 版本,随后列出 Protocols 和 Features。读取方法
重点看 Features 是否包含 HTTP2、HTTP3、IPv6,并确认 TLS 后端。
使用说明
不同发行版即使 curl 版本相同,编译特性也可能不同;使用高级参数前先看这里。
curl <URL>向目标 URL 发送最基础的 HTTP GET 请求并输出响应体。
发送 GET 请求
向目标 URL 发送最基础的 HTTP GET 请求并输出响应体。
基本语法
curl <URL>高频用法
curl https://example.com/api/health预期结果:
成功时标准输出出现响应正文;HTTP 状态本身默认不会让 curl 失败。读取方法
只需要正文时直接使用;排障时通常再配合 -i、-v 或 -w。
使用说明
URL 中含 &、?、* 等 Shell 特殊字符时应整体使用单引号包裹。
curl -I <URL>只请求响应头,快速检查状态码、缓存、内容类型和重定向。
发送 HEAD 请求
只请求响应头,快速检查状态码、缓存、内容类型和重定向。
基本语法
curl -I <URL>高频用法
curl -sS -I https://example.com/预期结果:
输出 HTTP 状态行及响应头,不下载常规 GET 响应体。读取方法
适合检查 Location、Content-Type、Cache-Control、ETag 等。
使用说明
部分服务对 HEAD 与 GET 的实现不同;HEAD 正常不能完全证明 GET 正常。
curl -X <METHOD> <URL>显式设置请求方法,如 DELETE、PATCH、OPTIONS。
指定 HTTP 方法
显式设置请求方法,如 DELETE、PATCH、OPTIONS。
基本语法
curl -X <METHOD> <URL>高频用法
curl -sS -X DELETE https://example.com/api/items/123预期结果:
服务端按指定方法返回状态码与响应体。读取方法
-X 只改变方法字符串,不会自动改变请求体、Header 或上传行为。
使用说明
GET/POST/HEAD 等常见场景优先使用对应专用参数;不要为了“显式”到处写 -X POST。
curl -G --data-urlencode <KEY=VALUE> <URL>把参数安全 URL 编码后追加到查询字符串。
发送带查询参数的 GET
把参数安全 URL 编码后追加到查询字符串。
基本语法
curl -G --data-urlencode <KEY=VALUE> <URL>高频用法
curl -sS -G --data-urlencode 'q=hello world' --data-urlencode 'page=1' https://example.com/search预期结果:
实际请求类似 `/search?q=hello%20world&page=1`。读取方法
-G 让 -d/--data-urlencode 生成查询参数而不是 POST body。
使用说明
用户输入包含空格、中文、&、= 时优先 --data-urlencode,不要手拼 URL。
curl --http1.1 <URL>强制 HTTPS/HTTP 请求使用 HTTP/1.1,适合排查协议协商或代理兼容问题。
强制使用 HTTP/1.1
强制 HTTPS/HTTP 请求使用 HTTP/1.1,适合排查协议协商或代理兼容问题。
基本语法
curl --http1.1 <URL>高频用法
curl -sS --http1.1 -I https://example.com/预期结果:
响应状态行通常显示 `HTTP/1.1`。读取方法
若默认正常、强制 HTTP/1.1 正常而 HTTP/2 异常,可继续排查网关或协议实现。
风险与边界
这不是性能优化参数,只应用于兼容性测试或明确的协议要求。
curl --http2 <URL>请求使用 HTTP/2;HTTPS 场景通常通过 ALPN 协商。
尝试使用 HTTP/2
请求使用 HTTP/2;HTTPS 场景通常通过 ALPN 协商。
基本语法
curl --http2 <URL>高频用法
curl -sS --http2 -I https://example.com/预期结果:
支持时响应状态行通常显示 `HTTP/2`。读取方法
先用 curl --version 确认 Features 包含 HTTP2。
风险与边界
目标、代理或本机 libcurl 未支持 HTTP/2 时可能降级或报错,取决于场景。
curl --http3 <URL>优先尝试 HTTP/3;建立过慢或失败时允许回退到较早 HTTP 版本。
尝试使用 HTTP/3
优先尝试 HTTP/3;建立过慢或失败时允许回退到较早 HTTP 版本。
基本语法
curl --http3 <URL>高频用法
curl -sS --http3 -I https://example.com/预期结果:
支持且协商成功时可通过 verbose/write-out 确认 HTTP/3。读取方法
--http3 是带回退策略的测试方式;先确认 curl 构建支持 HTTP3。
风险与边界
HTTP/3 仅适用于 HTTPS,并依赖 QUIC 支持;不是所有发行版 curl 都编译启用。
curl --http3-only <URL>只允许 HTTP/3,不回退到 HTTP/2 或 HTTP/1.1。
强制只用 HTTP/3
只允许 HTTP/3,不回退到 HTTP/2 或 HTTP/1.1。
基本语法
curl --http3-only <URL>高频用法
curl -sS --http3-only -I https://example.com/预期结果:
成功时使用 HTTP/3;无法建立 QUIC 时命令失败。读取方法
适合验证目标是否真正具备可用的 HTTP/3 能力。
风险与边界
仅用于专项验证;普通业务探测优先 --http3,避免把回退能力关闭。
请求体与表单
curl -d <DATA> <URL>发送 application/x-www-form-urlencoded 风格的 POST 数据。
发送表单 POST
发送 application/x-www-form-urlencoded 风格的 POST 数据。
基本语法
curl -d <DATA> <URL>高频用法
curl -sS -d 'username=alice&active=true' https://example.com/api/users预期结果:
服务端收到表单字段并返回业务响应。读取方法
-d 会使 curl 默认使用 POST,并设置表单内容类型。
使用说明
值来自用户输入时应考虑 URL 编码,复杂字段优先 --data-urlencode。
curl --data-urlencode <KEY=VALUE> <URL>对表单字段进行 URL 编码,避免特殊字符破坏 body 格式。
发送 URL 编码表单
对表单字段进行 URL 编码,避免特殊字符破坏 body 格式。
基本语法
curl --data-urlencode <KEY=VALUE> <URL>高频用法
curl -sS --data-urlencode 'name=张三' --data-urlencode 'note=a&b' https://example.com/api/form预期结果:
服务端收到正确编码的字段值。读取方法
适合中文、空格、&、+、= 等需要编码的内容。
使用说明
该方式仍是表单编码,不等同于 JSON。
curl --json <JSON> <URL>发送 JSON body,并自动设置适合 JSON 的请求头。
发送 JSON 请求
发送 JSON body,并自动设置适合 JSON 的请求头。
基本语法
curl --json <JSON> <URL>高频用法
curl -sS --json '{"name":"alice","enabled":true}' https://example.com/api/users预期结果:
服务端收到 JSON 请求并返回业务响应。读取方法
--json 等价于组合 JSON 数据发送与 JSON Header,命令更清晰。
风险与边界
较旧 curl 版本可能没有 --json;先用 curl --version 确认环境。
curl --json @<FILE> <URL>直接把 JSON 文件作为请求体,避免在命令行中处理大量转义。
从文件发送 JSON
直接把 JSON 文件作为请求体,避免在命令行中处理大量转义。
基本语法
curl --json @<FILE> <URL>高频用法
curl -sS --json @payload.json https://example.com/api/users预期结果:
服务端收到 `payload.json` 的完整内容。读取方法
适合复杂 JSON、可复现接口测试和脚本。
风险与边界
文件可能包含密码、Token 或个人数据;注意文件权限和提交仓库风险。
curl --json @- <URL>从标准输入读取 JSON body,适合动态生成请求。
从标准输入发送 JSON
从标准输入读取 JSON body,适合动态生成请求。
基本语法
curl --json @- <URL>高频用法
printf '%s' '{"name":"alice"}' | curl -sS --json @- https://example.com/api/users预期结果:
管道输出成为 HTTP 请求体。读取方法
@- 表示从 stdin 读取。
风险与边界
重试请求时,stdin 是否能重新读取需要特别注意;不要盲目结合激进重试。
curl --data-raw <DATA> <URL>发送原始文本数据,并避免把开头的 @ 当成本地文件引用。
发送原始文本数据
发送原始文本数据,并避免把开头的 @ 当成本地文件引用。
基本语法
curl --data-raw <DATA> <URL>高频用法
curl -sS --data-raw '@literal-value' https://example.com/api/raw预期结果:
请求体包含字面量 `@literal-value`。读取方法
当内容可能以 @ 开头时比普通 -d 更明确。
使用说明
它仍遵循 data 类处理规则;真正二进制内容使用 --data-binary。
curl --data-binary @<FILE> <URL>按原样发送文件内容,不做文本换行等转换。
发送二进制请求体
按原样发送文件内容,不做文本换行等转换。
基本语法
curl --data-binary @<FILE> <URL>高频用法
curl -sS --data-binary @payload.bin -H 'Content-Type: application/octet-stream' https://example.com/upload/raw预期结果:
服务端收到与本地文件字节内容一致的请求体。读取方法
--data-binary 适合 protobuf、压缩包、自定义二进制协议载荷等。
使用说明
大文件上传优先考虑 --upload-file;不要把二进制内容直接打印到终端。
curl -F <NAME=VALUE> <URL>发送 multipart/form-data 表单字段。
发送 multipart 表单
发送 multipart/form-data 表单字段。
基本语法
curl -F <NAME=VALUE> <URL>高频用法
curl -sS -F 'name=alice' -F 'active=true' https://example.com/api/form预期结果:
服务端按 multipart 字段读取 name、active。读取方法
-F 会自动生成 multipart boundary 和对应 Content-Type。
使用说明
不要手动固定 multipart boundary,交给 curl 生成。
curl -F <NAME=@FILE> <URL>以 multipart 文件字段上传本地文件。
multipart 上传文件
以 multipart 文件字段上传本地文件。
基本语法
curl -F <NAME=@FILE> <URL>高频用法
curl -sS -F 'file=@report.pdf' -F 'type=monthly' https://example.com/api/upload预期结果:
服务端收到名为 `file` 的文件字段和其他普通字段。读取方法
@文件 表示读取文件内容并作为上传字段。
使用说明
文件路径来自变量时必须正确引用并限制来源,避免上传错误或敏感文件。
curl -F 'file=@<PATH>;filename=<NAME>' <URL>上传本地文件时显式控制服务端看到的文件名。
自定义 multipart 文件名
上传本地文件时显式控制服务端看到的文件名。
基本语法
curl -F 'file=@<PATH>;filename=<NAME>' <URL>高频用法
curl -sS -F 'file=@/tmp/report.bin;filename=report.dat' https://example.com/api/upload预期结果:
服务端 multipart 元数据中的 filename 使用指定名称。读取方法
适合本地临时文件名与业务文件名不同的场景。
风险与边界
filename 只是 multipart 元数据,不改变本地文件。
请求头与内容协商
curl -H '<HEADER>' <URL>添加自定义 HTTP Header。
添加请求头
添加自定义 HTTP Header。
基本语法
curl -H '<HEADER>' <URL>高频用法
curl -sS -H 'X-Request-ID: req-123' https://example.com/api预期结果:
服务端收到指定请求头。读取方法
可重复使用 -H 添加多个 Header。
使用说明
不要把长期 Token 直接写进共享 Shell 历史或工单。