cURL上传文件实用技巧分享

Linux下用cURL上传文件看似简单，实则极易因协议理解偏差而失败：-F仅适用于multipart/form-data表单接口，而多数现代API实际要求application/octet-stream直传或JSON base64封装；大文件上传需规避内存加载、超时中断和代理截断，认证场景则对Header格式、大小写、字符转义极度敏感；真正可靠的上传不靠堆砌参数，而在于精准匹配目标接口的协议层级——是表单、REST、对象存储还是自建服务，决定了你该用-F、--upload-file还是定制化封装，选错机制，连错误提示都在误导你。

curl -F 上传文件时为什么服务器收不到数据

因为 -F 默认以 multipart/form-data 编码模拟表单提交，但很多后端接口实际期望的是原始二进制流（比如 PUT 接口）或 application/json 包裹的 base64。直接用 -F 往非表单接口发，服务端解析失败是常态。

• 确认目标接口文档：是接收 multipart/form-data（如 PHP 的 $_FILES）、application/octet-stream（如对象存储直传），还是需要 JSON 封装？
• 表单上传场景才用 -F，例如：curl -F "file=@/path/to/image.jpg" https://api.example.com/upload
• @ 符号必须紧挨 file=，中间不能有空格；路径错误会导致静默失败（curl 不报错，但 body 为空）
• 如果后端用 Node.js Express + multer，需确保字段名（如 file）和服务端配置的 name 一致

用 curl PUT 上传大文件时连接被重置

默认 curl 使用短连接，且无分块、无进度反馈，大文件易超时或被中间代理切断。这不是 curl 本身的问题，而是传输模式不匹配。

• 加 -H "Content-Type: application/octet-stream" 明确类型，避免服务端按 text 解析乱码
• 强制使用 HTTP/1.1 并禁用 chunked 编码：curl -X PUT --http1.1 --upload-file /big.zip -H "Transfer-Encoding:" https://storage.example.com/file.zip
• --upload-file 比 -d @file 更可靠：它不读入内存，适合 GB 级文件；而 -d @file 会尝试加载整个文件到内存再发
• 某些 CDN 或 Nginx 默认限制 body 大小，需同步调高 client_max_body_size 和超时参数

上传带认证或特殊 Header 的文件总返回 401 或 400

Header 顺序和值格式稍有偏差就会触发鉴权失败或解析异常，尤其是含空格、引号、特殊字符的 token。

• Token 中若含点号或斜杠，用单引号包裹整个 header：-H 'Authorization: Bearer eyJhb...'，避免 shell 把 $ 或 ! 当变量展开
• 上传同时带多个 header 时，每个 -H 必须独立写，不能合并：-H "X-Upload-ID: abc" -H "X-File-Name: log.txt"
• 部分 API 要求 Content-MD5，得先算哈希：md5sum file.pdf | cut -d' ' -f1，再拼进 header，少一位都会 400
• 用 -v 看真实请求头是否符合预期，别只信文档——有些服务对 header 大小写敏感（如 X-Amz-Date 不可写成 x-amz-date）

如何让 curl 上传时显示进度并自动重试失败

原生命令不支持断点续传，但基础进度和简单重试可以靠参数组合实现，复杂逻辑建议交给脚本封装。

• 加 --progress-bar 显示实时进度条（不是百分比数字，是横向填充）；加 -# 是另一种风格，二者不可共存
• 网络抖动导致失败时，--retry 3 --retry-delay 2 可重试 3 次，每次间隔 2 秒；注意：仅对网络层失败有效，HTTP 4xx 错误不会重试
• 上传中途 Ctrl+C 不会自动清理已发部分，服务端可能收到残缺文件——务必确认后端支持校验（如比对 Content-Length 或 MD5）
• 真正需要断点续传（比如上传到 S3 分片），得换用 awscli 或 rclone，curl 做不了

上传这件事，关键不在命令多长，而在你清楚自己在跟哪一层协议打交道：是表单、REST API、对象存储，还是自建服务。一个 -F 和一个 --upload-file 的差别，背后是两种完全不同的数据协商机制。搞混了，连错误提示都可能是误导。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《cURL上传文件实用技巧分享》文章吧，也可关注golang学习网公众号了解相关技术文章。