HTTPie 命令行 HTTP 客户端速查表 - 接口调试命令大全
写接口联调脚本时，真正拖慢人的不是记不住 HTTP 方法，而是要查哪个字段该用等号、哪个该用冒号。HTTPie 把这些细节收进语法：冒号后是 HTTP 头，== 是查询参数，= 往 JSON 体塞字符串，:= 塞数字或布尔，@ 读文件内容。记住映射，DevTools 复制出的 cURL 就能直接改写成可读形式，不必查 -H、-d 各自吃哪种引号。输出侧才是它更实际的优势：响应自动按 JSON 美化着色，不用再判断该接 jq 还是 python。--session 把 cookie 与凭据存成命名会话，多步流程只需第二跳写一次名字，不必重复粘贴 token。该用它时：接口调试、替代 Postman、CI 冒烟请求；不该用时：要压测、要复杂重试，流水线里已有冻结的 curl 脚本。
典型使用场景
面向需要在终端里手工调接口的后端与前端开发者，以及写接口冒烟脚本的测试同学。curl 在语法上要背一堆 -H、-d、--data-binary，而 HTTPIE 把它做成了接近自然语言的写法：字段名=value、:=强制数字类型、==拼查询串、@ 读文件、字段@文件传上传。本表覆盖方法与数据类型、内置认证（Basic / Bearer / Digest）、命名 Session 复用登录态、下载与断点续传、流式输出与代理，以及排错时最常用的 -v / -h / --check-status。
基础请求 7
http GET https://api.example.com/usershttp https://api.example.com/usershttp POST https://api.example.com/users name=John age:=30http PUT https://api.example.com/users/1 name=Janehttp DELETE https://api.example.com/users/1http PATCH https://api.example.com/users/1 email=new@mail.comhttp HEAD https://api.example.com/users请求头与参数 7
http https://api.example.com X-Token:abc123http https://api.example.com X-Token:abc123 Cookie:session=xyzhttp https://api.example.com page==2 size==10http -j https://api.example.comhttp -f https://api.example.com field=valuehttp -v https://api.example.comhttp -p Hh https://api.example.com认证与 Session 6
http -a user:pass https://api.example.comhttp -A bearer -a TOKEN https://api.example.comhttp -A digest -a user:pass https://api.example.comhttp --session=logged-in https://api.example.comhttp --session=logged-in https://api.example.com/profilehttp --session-read-only=logged-in https://api.example.com文件与下载 6
http -d https://example.com/file.zip -o file.ziphttp --download https://example.com/file.ziphttp POST https://api.example.com/upload file@./photo.jpghttp POST https://api.example.com/data @data.jsonhttp -d https://example.com/file.zip --continuehttp POST https://api.example.com/upload file@./photo.jpg field=value输出与格式化 6
http https://api.example.com | jq ".data"http -b https://api.example.comhttp -h https://api.example.comhttp --pretty=none https://api.example.comhttp -o response.json https://api.example.comhttp --stream https://api.example.com/stream实用技巧 5
http --proxy http:http://127.0.0.1:7890 https://api.example.comhttp --follow https://example.com/redirecthttp --timeout=30 https://api.example.comhttp --verify=no https://self-signed.example.comhttp --check-status https://api.example.com/users参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
field=value / field:=value | 普通字段按字符串发送；:= 强制数字类型 | http POST https://api.example.com/users name=John age:=30 |
param==value | == 把字段拼进 URL 查询字符串而不是请求体 | http https://api.example.com page==2 size==10 |
-f / -j | -f 提交 form-urlencoded；-j 强制 Content-Type 为 JSON | http -f https://api.example.com field=value |
file@./photo.jpg / @data.json | @ 前缀从文件读取内容，字段@文件即上传文件 | http POST https://api.example.com/upload file@./photo.jpg |
-a / -A | -a user:pass 为 Basic 认证；-A bearer -a TOKEN 为 Bearer Token | http -A bearer -a TOKEN https://api.example.com |
--session=name | 创建并复用命名 Session，自动携带 cookies 与 headers | http --session=logged-in https://api.example.com/profile |
--session-read-only=name | 只读 Session，用其中的凭据请求但不更新其状态 | http --session-read-only=logged-in https://api.example.com |
-v / -p Hh / -h / -b | 输出控制：完整请求响应 / 只头 / 只响应头 / 只响应体 | http -v https://api.example.com |
-d / --download / --continue | 下载模式；配合 --continue 可断点续传 | http -d https://example.com/file.zip --continue |
--check-status / --timeout=30 / --verify=no | CI 里按状态码决定退出码；限制超时；跳过自签证书校验 | http --check-status https://api.example.com/users |
易错点与避坑指南
现象请求体里的数字字段到了服务端变成字符串，或 JSON 里出现字符串形式的数字。
原因默认按 = 赋值时全部字段都是字符串类型，需要用 := 强制声明类型。
处置数字/布尔/空值用 := 形式：http POST https://api.example.com/users name=John age:=30。
现象参数拼到了请求体里，服务端从 query 取不到值。
原因用了单个 = 而不是 ==，= 写入请求体，== 才写入 URL 查询串。
处置改用 ==：http https://api.example.com page==2 size==10。
现象本地脚本 / 自签证书站点直接报 SSL 验证失败，curl 加 -k 反而正常。
原因HTTPIE 默认严格校验证书链与主机名，不会像 curl -k 那样自动降级。
处置仅在本地自签场景加 --verify=no（http --verify=no https://self-signed.example.com），不要在生产脚本里长期使用。
现象脚本在 CI 里全绿，但接口其实返回了 500。
原因默认输出响应体后即视为成功，退出码不随 4xx/5xx 变化。
处置加 --check-status：http --check-status https://api.example.com/users，让状态码异常时返回非零退出码。
现象第二次带 Session 请求返回 401，明明第一次登录是成功的。
原因Session 名写错导致读不到之前保存的 cookies 与 headers，等于匿名请求。
处置确认会话名一致：先用 http --session=logged-in https://api.example.com 登录，再对同一名字的 --session 复用；只想读取不更新时用 --session-read-only。
现象下载大文件中断后只能从头再来。
原因未使用续传选项，每次都会重新写整个文件。
处置加 --continue：http -d https://example.com/file.zip --continue（或 --download 带进度条）。
排障路径
1接口不通时先看完整交换过程
http -v https://api.example.com-v 同时打印请求与响应，能立刻看出请求头有没有带上、状态码是多少。
2只看请求头确认自定义请求头是否生效
http -p Hh https://api.example.com-p Hh 只输出请求头(H)与响应头(h)，排查 Authorization / Content-Type 时最省事。
3只想拿响应头（探活、重定向链）
http -h https://api.example.com-h 只输出响应头；确认 301/302 跳转目标时配合 --follow 一起用。
4把响应体存成文件再做 jq 处理
http -o response.json https://api.example.com也可以直接管道：http https://api.example.com | jq ".data"；只要纯响应体用 -b。
5本地自签证书与代理环境下的排查
http --verify=no --proxy http:http://127.0.0.1:7890 https://api.example.com--verify=no 仅限本地调试；真实网络不通先看是否需要走代理，以及请求是否超时（--timeout=30）。
提示
- 安装：pip install httpie 或 brew install httpie。
- := 用于 JSON 数字/布尔类型，== 用于 URL 查询参数，= 用于 JSON 字符串字段。
- httpie 的输出自动 JSON 格式化和高亮，比 curl | jq 更方便。
- --session 可以保存 cookies 和认证信息，适合需要多步操作的 API 调试。
- 请求项语法：头字段 Header:Value、查询参数 param==value、数据字段 field=value、JSON 字段 field:=value、文件 field@/path。
- 用 -o 保存响应体到文件，结合 --download 适合下载大文件并显示进度。
- http --form POST ... user@~/avatar.png 会自动切成 multipart/form-data 并生成 boundary，纯手写 curl -F 时最容易在这里漏掉引号或文件名。
- --print=HBh 表示只输出 header 和 body（H 大写、B 大写、h 小写各代表一种），调试接口时用它可以把响应头摘出来单独核对 Content-Type 和缓存头。
- 用 --offline 生成等价的 cURL 命令而不发请求，写进文档或 issue 时用它，比手抄一长串 -H 更不容易漏参数。
由 巧匠 维护
公开更新于 2026年7月19日，内容持续校对官方文档。