curl 报 option --fail-with-body: is unknown，安装脚本在下载前退出

运行安装脚本或 API 请求脚本，终端出现：

curl: option --fail-with-body: is unknown

这条错误来自本机 curl 的参数解析。它还不能说明下载站故障、服务器拒绝请求或证书不可信；即使脚本接着打印“下载失败”，也应先处理不认识的参数。

--fail-with-body 从 curl 7.76.0 开始提供。它让 HTTP 400 及以上响应返回失败码 22，同时保留响应正文。旧版本不支持这个选项时，请求无法按脚本预期执行。下文适用于 Linux 等使用 curl 命令行工具的环境，示例脚本使用 Bash。

检查脚本实际调用的 curl

在发生错误的执行环境中查看版本：

curl --version

第一行同时显示 curl、libcurl 和其他依赖库的信息，核对开头的 curl 版本。安装应用的新版本，不会自动升级系统中的 curl；只更新某个语言的 HTTP 库，也不能保证命令行程序支持新选项。

若终端显示的版本已支持该选项，脚本却仍报错，应检查脚本是否写死了另一个 curl 路径，或实际在容器、CI 任务、另一个用户环境中运行。对脚本指定的程序直接查询，例如：

/usr/bin/curl --version

这个路径只是示例，要换成脚本实际使用的路径。宿主机上的新版本不能代表容器内的版本。确认调用目标，避免把新包装到脚本不会使用的位置。

第三方安装器优先使用兼容版本

如果出错的是第三方安装器，先获取项目当前正式提供的安装脚本，检查其 curl 版本要求及兼容处理。安装器可能已经改为按能力选择参数；旧副本仍可能保留不兼容的调用。

若项目明确要求支持 --fail-with-body，通过操作系统或运行环境支持的安装渠道更新 curl，并再次核对实际调用路径。7.76.0 是这个选项的引入版本，不是建议固定安装的旧版本；应选当前受支持、符合环境要求的版本。

长期支持发行版中的 curl 可能保持较早的功能版本。不要只为了一个选项，随意替换系统的 libcurl、覆盖发行版管理的可执行文件，或混用另一发行版的软件包。无法更新时，先确认安装器是否提供兼容方案。

更新或修改前保留原脚本、工具版本和安装来源。需要回退时，通过原渠道恢复工具或脚本；如果安装器已经改动了应用，回退 curl 并不会撤销这些改动，应按应用的回退说明处理。

自己的脚本可以换成 --fail，但错误正文会丢失

如果脚本只需要在 HTTP 错误时失败，并不读取错误响应正文，可以把 --fail-with-body 替换为较早就支持的 --fail。不要把两个选项同时放进命令，它们互斥。

下面是一次 GET 下载的示例，URL 和文件名都需按实际用途替换。输出文件应放在专用工作目录中，避免覆盖已有文件：

curl --silent --show-error --fail \
  --output ./download.part \
  'https://download.example.invalid/package.tar.gz'

--silent --show-error 隐藏进度条但保留失败信息；--fail 在 HTTP 错误时不输出响应正文。网络错误仍会让 curl 失败。curl 对认证相关的 HTTP 错误有例外情形，不能把这个参数当成应用鉴权与返回值校验的替代品。

如果后续逻辑需要读取 API 返回的错误 JSON，换成 --fail 会丢掉这份信息。此时应使用支持原选项的 curl，或单独设计保留正文并检查状态码的流程，不能只改参数后声称行为完全相同。

也不要直接删掉失败选项：curl 默认不会仅因 HTTP 状态为 404 或 500 就返回失败。脚本可能把错误页面当成安装包，继续交给解压或执行步骤。

保留退出码，再决定是否使用下载结果

消除“未知选项”只解决了参数兼容。下载脚本还必须处理 curl 的失败结果，否则下一条成功命令可能掩盖真正的错误。

以下 Bash 片段把下载成功与失败分开处理，失败时不使用 download.part：

#!/usr/bin/env bash

if curl --silent --show-error --fail \
  --output ./download.part \
  'https://download.example.invalid/package.tar.gz'; then
  printf '%s\n' 'HTTP transfer completed; verify the file before use.'
else
  curl_status=$?
  printf 'Download failed, curl exit code: %s\n' "$curl_status" >&2
  exit "$curl_status"
fi

示例域名不可用于实际下载。else 中立即保存的是 curl 的退出码；失败时输出文件可能为空或不完整，应作为失败产物保留检查，不能继续安装。成功也只表示传输成功，还需按发布方提供的校验和或签名核对文件。

修复后，在受控测试环境中分别验证一个成功下载地址和一个已知返回 404 的地址：成功请求应完成下载，404 请求应使脚本返回非零，且不进入安装步骤。若仍然出现 unknown，重新核对实际执行程序；若错误变成 DNS、TLS 或 HTTP 错误，再按新错误处理。不要为消除参数错误而关闭 TLS 证书校验。