curl 使用 multipart 上传并保留响应头

如果接口要求文件和普通字段一起提交，curl 应使用 -F/--form 组成 multipart/form-data 请求；如果还要保留服务端返回的状态码、Location、Set-Cookie 或自定义头，关键在于选择 -i 还是 -D。前者把响应头和正文放在同一输出流，后者把响应头单独写入文件。

官方地址：https://curl.se/

先把文件字段和普通字段分开

假设接口约定文件字段名为 file，还接收一个文本字段 scene。文件项的 @ 表示从本地读取内容，;type= 可以为文件声明更合适的媒体类型。不要把本机真实目录、令牌或私人域名直接放进文章命令。

# 用 -F 生成 multipart/form-data，同时提交文件和普通字段
curl --request POST \
  --url https://api.example.test/upload \
  --form "file=@./report.csv;type=text/csv" \
  --form "scene=monthly" \
  --header "Authorization: Bearer YOUR_TOKEN"

每一个 --form 都对应一个 multipart part。接口若把字段名写成 upload，就必须把 file= 改成 upload=；这比盲目追加请求头更重要。通常不需要手写 Content-Type: multipart/form-data，让 curl 自动生成 boundary，手写错误的 boundary 反而会导致服务端无法解析。

用 -i 在同一输出中保留响应头

调试接口或人工核对返回值时，可以加 --show-headers（短参数 -i）。它会把 HTTP 状态行和响应头放在正文前面，适合一次性查看“服务端返回了什么”。

# -i 把响应头和正文放到同一标准输出，便于人工对照
curl --request POST \
  --url https://api.example.test/upload \
  --form "file=@./report.csv;type=text/csv" \
  --form "scene=monthly" \
  --show-headers

看到 HTTP/1.1 201 或实际接口约定的成功状态后，再检查 Location、Content-Type 和正文中的任务编号。-i 不是查看请求头的参数；如果要看发送出去的请求细节，应使用 --verbose，但其中可能包含认证信息，复制日志前要先脱敏。

脚本处理时改用 -D 和 -o 分离文件

混合输出对人友好，却不适合直接交给 JSON 解析器。要让脚本分别读取响应头和正文，可使用 --dump-header（短参数 -D）与 --output（短参数 -o）。

# -D 保存响应头，-o 保存正文，避免把 HTTP 头传给 JSON 解析器
curl --request POST \
  --url https://api.example.test/upload \
  --form "file=@./report.csv;type=text/csv" \
  --form "scene=monthly" \
  --dump-header response-headers.txt \
  --output response-body.json

# 只读取本次响应的状态行和关键头，正文仍保留原始 JSON
sed -n '1,12p' response-headers.txt

response-headers.txt 是头部留档，response-body.json 才是接口正文。若服务端发生多次重定向，头文件可能包含多组响应头，因此脚本应按状态行分段，而不是假定第一组就是最终响应。

重定向、认证和失败状态要单独检查

接口返回 3xx 时，是否跟随跳转不是默认的上传逻辑。确认跳转地址仍属于可信服务后，再考虑 --location；不要为了“让请求成功”直接把认证头和 Cookie 无条件带到未知主机。更稳妥的做法是记录最终 URL、状态码和响应头，再判断是否需要重新构造请求。

在自动化脚本里，可以把错误输出与返回码也留住，但不要把返回码当成业务成功的唯一条件：HTTP 状态码、响应正文里的业务码、响应头中的任务位置都应按接口约定核对。上传接口若要求幂等键或分片协议，单纯增加 -F 并不能替代它。

常见问题

为什么上传接口提示不是 multipart？

优先检查是否真的使用了 -F，以及字段名和文件路径是否正确。不要手写一个与 curl 实际边界不一致的 Content-Type。

-i 和 -D 应该怎么选？

人工查看选 -i；需要把响应交给脚本、保存正文或比较多次结果时，用 -D 配合 -o。

响应头里为什么会出现多组状态行？

常见原因是重定向或代理返回了中间响应。脚本应识别每一组状态行，确认最终响应，而不是只取文件第一行。

记住这个最小决策：先用 -F 正确组成表单；调试时用 -i 看完整返回；自动化时用 -D 和 -o 分离头体；涉及跳转和认证时，再按信任边界决定是否继续。