开发工具 curl multipart 上传 怎样处理

用 curl 上传文件并同时提交表单字段时，关键是先看接口要求的编码类型：如果服务端接收的是 multipart/form-data，使用 -F 或 --form；不要把文件字段写进 -d。文件字段用 @本地文件 表示，普通文本字段可以用 --form-string 发送。

官方地址：https://curl.se/docs/manpage.html

最小可用写法是：curl -F 'title=月度报告' -F 'file=@report.csv' https://api.example.test/upload。字段名必须和接口约定一致，文件路径必须指向当前机器可读的文件。

先确认请求体类型和字段名

打开接口文档或表单 HTML，先确认它是否声明了 enctype="multipart/form-data"。只有这一类表单才适合用 -F。如果接口只接收普通键值对，通常应使用 -d，两者不是同一个请求体。

curl 的字段名来自服务端表单字段，例如服务端定义的是 file，命令中的左侧就必须是 file；本地文件名只写在 @ 后面。

用 -F 组合普通字段和文件字段

下面的命令把一个文本字段和一个文件字段放到同一个 multipart 请求中。示例中的注释说明了每个参数的用途，实际使用时把 URL、字段名和路径替换成接口文档中的值。

# -F 让 curl 组织 multipart/form-data 请求体
curl \
  -F 'title=月度报告' \
  -F 'file=@./report.csv' \
  'https://api.example.test/upload'

@./report.csv 表示读取本地文件内容并作为文件部件上传；它不是把字符串 @./report.csv 当作普通文本发送。文件字段缺失时，优先检查路径、当前工作目录和服务端字段名。

文本值有 @ 或分号时改用 --form-string

如果普通文本本身来自用户输入，可能以 @ 开头，或包含 ;type= 这样的片段，直接写在 -F 中容易触发 curl 的特殊语义。此时用 --form-string，让值按字面发送。

# --form-string 保留文本原样，不把开头的 @ 解释成文件路径
curl \
  --form-string 'title=@临时标签' \
  -F 'file=@./report.csv' \
  'https://api.example.test/upload'

文件仍然使用 -F，因为它需要告诉 curl 读取本地文件并建立文件部件。不要为了规避特殊字符而把整个 multipart 请求改成 -d，那会改变请求体类型。

多个文件和 MIME 类型怎么写

不同字段上传不同文件时，重复写 -F 即可；如果接口允许同一个字段接收多个文件，也可以在一个字段值中列出多个文件。文件类型不明确时，可以在文件名后追加 ;type=...，但最终是否接受仍由服务端校验规则决定。

# 两个字段对应两个文件，字段名必须按接口约定填写
curl \
  -F 'avatar=@./avatar.png;type=image/png' \
  -F 'attachment=@./report.csv;type=text/csv' \
  'https://api.example.test/profile'

常见错误是把服务端字段名写成了本地文件名，或者把多个文件误放进只允许单文件的字段。先对照接口定义，再决定是重复字段还是拆成不同字段。

根据响应排查上传问题

请求返回后，先看服务端响应，不要只看 curl 是否输出了进度条。字段缺失通常说明左侧字段名不对；服务端提示无法读取文件时，检查本地路径和权限；收到“不是 multipart”之类的提示时，检查是否误用了 -d 或手工覆盖了 Content-Type。

通常不需要手写 multipart 的 boundary。让 curl 根据各个 -F 参数自动组织请求体，手工设置一个不匹配的 Content-Type 反而可能让服务端无法解析。

常见问题

为什么用 -d 上传文件后服务端拿不到文件？

-d 默认发送的是普通表单或原始数据，不会按文件部件组织 multipart。改为 -F 'file=@文件路径'，并核对字段名。

为什么文本字段里的 @ 被当成文件？

这是 -F 的文件语义。需要原样发送文本时使用 --form-string。

是否应该自己设置 Content-Type？

一般不需要。curl 会根据 -F 生成 multipart 请求及边界；只有接口文档明确要求额外请求头时，才单独添加其它业务头。

小结

curl multipart 上传可以按三点记忆：-F 负责文件部件和 multipart 请求，--form-string 负责不应被特殊解析的文本，字段左侧名称必须服从接口约定。遇到失败时，从请求体类型、字段名、本地路径和响应信息四处排查，通常能快速定位问题。