Linux curl 上传文件如何检查状态码和响应体

Linux 上用 curl 上传文件时，不能只看“命令有没有报错”。curl 的传输退出码、HTTP 状态码和服务端响应体是三件事：网络没断，不代表接口返回了成功；接口返回 404，也不一定会让 curl 退出非零。把这三项分开记录，脚本才能既判断结果，又留下排障线索。

先分清三个结果：传输、HTTP 状态码、响应体

curl 负责完成一次传输，HTTP 服务端再返回状态行、响应头和响应体。默认行为下，只要通信过程完成，即使状态码是 404 或 500，curl 也可能正常退出。因此，$? 只能说明 curl 这次传输是否遇到本地或网络层错误，不能单独当成业务成功标志。

-w（--write-out）适合输出机器可读的结果。当前 curl 文档中，%{response_code} 是最近一次传输的 HTTP 状态码，%{exitcode} 是 curl 的数值退出码。上传文件可用 -T，响应体则用 -o 单独落盘：

最小可用写法：状态码和响应体分别保存

下面的命令适合先在 Linux 终端验证接口。状态信息写到标准输出，服务端正文写入 /tmp/curl-upload-response.txt；真实项目中可以换成任务目录或日志目录。

# 上传文件，并把响应正文与状态摘要分开保存
response_file="/tmp/curl-upload-response.txt"
status_line=$(curl --silent --show-error \
  --request PUT \
  --upload-file "./build.tar" \
  --output "$response_file" \
  --write-out 'http=%{response_code} curl=%{exitcode} bytes=%{size_upload}\n' \
  "https://upload.example.test/artifacts/build.tar")
curl_rc=$?

# 先看传输是否失败，再根据 HTTP 状态码决定业务结果
printf '%s\n' "$status_line"
if [ "$curl_rc" -ne 0 ]; then
  printf '传输失败，响应体：%s\n' "$response_file" >&2
  exit "$curl_rc"
fi

http_code=${status_line#http=}
http_code=${http_code%% *}
case "$http_code" in
  2[0-9][0-9]) printf '上传成功，响应体：%s\n' "$response_file" ;;
  *) printf '接口返回 HTTP %s，响应体：%s\n' "$http_code" "$response_file" >&2; exit 1 ;;
esac

这里有一个容易忽略的点：命令替换结束后要立即保存 $?，否则后面的 printf 会覆盖 curl 的退出码。另一个边界是重定向：如果接口要求 multipart 表单，不应把 --upload-file 和接口约定混用，而应按接口要求改用 -F 'file=@./build.tar'。

脚本里的可靠写法：保存响应体，再判断退出码

如果目标是让 HTTP 400 以上直接进入失败分支，同时保留服务端返回的 JSON 或文本错误，应使用 --fail-with-body。它从 curl 7.76.0 起提供：HTTP 400 以上会返回退出码 22，但响应体仍会写入指定输出位置。它与 --fail 互斥，后者会抑制这类响应体。

# --fail-with-body 保留服务端错误正文，适合自动化排障
response_file="/tmp/curl-upload-response.txt"
status_file="/tmp/curl-upload-status.txt"

curl --silent --show-error --fail-with-body \
  --upload-file "./build.tar" \
  --output "$response_file" \
  --write-out 'http=%{response_code} curl=%{exitcode} bytes=%{size_upload}\n' \
  "https://upload.example.test/artifacts/build.tar" \
  >"$status_file"
curl_rc=$?

# 退出码非零时仍读取响应体，便于定位 401、413 或 500
if [ "$curl_rc" -ne 0 ]; then
  printf '上传失败：%s\n' "$(cat "$status_file")" >&2
  sed -n '1,12p' "$response_file" >&2
  exit "$curl_rc"
fi
printf '上传完成：%s\n' "$(cat "$status_file")"

生产脚本还应处理临时文件清理、上传文件不存在、认证信息不出现在命令历史中等问题。不要用 --insecure 掩盖证书问题，也不要把响应体当成可信 JSON 直接执行。

常见问题

为什么 curl 返回 0，但接口其实失败了？

默认情况下，HTTP 状态码不是 curl 的传输错误。使用 -w '%{response_code}' 单独取状态码，或使用 --fail-with-body 让 4xx/5xx 进入非零分支。

--fail 和 --fail-with-body 怎么选？

只关心失败与否可以用 --fail；需要保留服务端错误详情时选 --fail-with-body，两者不能同时使用。

上传接口返回 JSON，应该把 JSON 打到终端吗？

自动化任务建议用 -o 保存响应体、用 -w 输出短状态行。这样日志既可读，也不会因服务端返回大段正文而难以检索。