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）。
命令示例
发一个 JSON POST，区分字符串与数字字段
http POST https://api.example.com/users name=John age:=30age:=30 里的冒号等号保证它以数字类型进 JSON；写成 age=30 服务端收到的是字符串。
复用命名 Session 访问需要登录的接口
http --session=logged-in https://api.example.com/profile会话在第一次带同样 --session 名的请求时创建，之后自动带上存下的 cookies 与 headers。
同时上传文件与表单字段
http POST https://api.example.com/upload file@./photo.jpg field=value@ 前缀读文件内容，等号形式照常作为普通字段，两者可并存于同一条请求。
断点续传下载一个压缩包
http -d https://example.com/file.zip --continue中断后重跑同一条命令即可续传；想边下边看进度，把 -d 换成 --download。
常见坑与注意事项
- 请求体里的数字字段务必用 := 而不是 =，否则 JSON 里会出现字符串形式的数字，服务端校验类型直接失败。
- 查询参数必须用 == 拼进 URL，用 = 写会变成请求体字段，服务端从 query 取不到值。
- --verify=no 只用于本地自签证书排查，绝不能进 CI 或生产配置，那等于放弃了证书校验。
- CI 与冒烟脚本务必加 --check-status，否则 4xx/5xx 也会让脚本显示成功，问题被静默放过。
- 用命名 Session 时注意其状态会被后续请求回写，只需借凭据时改用 --session-read-only，避免调试动作污染正式会话。
提示
- 安装：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 更不容易漏参数。
常见问题
=、== 和 := 这三个符号分别用在什么场景？
= 写的是请求体里的普通字符串字段，比如 name=John；:= 强制按 JSON 数字或布尔类型发送，比如 age:=30，服务端拿到的是数字而不是字符串；== 拼的是 URL 查询参数，比如 page==2，值会出现在 ? 后面而不是请求体。混淆 = 和 == 最典型的后果就是参数跑到 body 里，服务端从 query 取不到值。
同一个 Session 第二次请求却返回 401，第一次登录明明是成功的？
Session 复用靠的是上一次请求存下来的 cookies 和 headers，如果第一次登录返回的是 Set-Cookie 而你又在后续命令里手动覆盖了同名 Cookie 头，Session 里存的值就被冲掉了。另外 Session 文件在第一次请求时就落盘了，若要确认它到底存了什么，用 --session-read-only 复用凭据但不回写，观察是凭据的问题还是别的头在打架。
本地自签证书的站点 http 报 SSL 验证失败，该怎么处理？
调试自签证书时加 --verify=no 跳过证书校验，请求就能发出去。但这个开关只能用于本地排查，一旦写进脚本或长期配置就等于关掉了中间人防护。正式环境和 CI 里应该保留校验，证书问题从服务端证书链本身解决。
上传接口要同时传文件和普通字段，怎么写请求项？
文件用 @ 前缀，普通字段照常写等号，两种可以并排出现在同一条命令里，比如 file@./photo.jpg field=value，httpie 会自动切到 multipart/form-data 并生成 boundary。请求体如果本来就是一份 JSON 文件，则直接用 @data.json 作为唯一的请求项，不要再叠加其他字段。
大文件下载中断后怎么不用从头再来？
用下载模式加断点续传：http -d URL --continue。中断之后重跑同一条命令，它会带着已下载的部分继续；配合 -o 指定文件名可以固定落盘位置。只想要进度反馈就加 --download。想存下来离线分析时，把 -o 指向一个文件，再用管道工具处理。
由 巧匠 维护
公开更新于 2026年7月19日，内容持续校对官方文档。