curl 超级详细使用手册（工程实战版）

内容纲要

curl 是工程开发、运维、部署、模型下载、接口调试中最基础、也最常用的命令行 HTTP 客户端。
本文从“下载文件 + 接口请求 + 鉴权 + 代理 + 断点续传 + 调试排错 + 自动化脚本化”六个维度，给出可直接复制执行的命令模板。

一、基础下载能力（文件下载 90% 场景覆盖）

1️⃣ 下载并保留原文件名（最常用）

curl -O https://example.com/files/app.tar.gz

适用场景：

下载发布包
下载模型文件
下载静态资源

2️⃣ 自定义文件名保存

curl -o app.tar.gz https://example.com/files/app.tar.gz

工程实践中，建议统一规范命名，避免 URL 文件名混乱。

3️⃣ 跟随 302 / 301 跳转（GitHub / OSS 必加）

curl -L -O https://github.com/user/repo/releases/download/v1.0/app.tar.gz

这是最容易踩的坑之一。
不加 -L，你下载到的往往是一个 HTML 页面，而不是文件本体。

4️⃣ 显示进度条（大文件下载必开）

curl -L -# -O https://example.com/bigfile.tar.gz

-# 比默认 verbose 更干净，适合部署脚本日志。

5️⃣ 断点续传（生产环境强烈建议）

curl -L -C - -O https://example.com/bigfile.tar.gz

适用场景：

模型权重（几百 MB / 几 GB）
不稳定网络
VPS 下载大文件

6️⃣ 限速下载（避免占满带宽）

curl -L --limit-rate 1m -O https://example.com/bigfile.tar.gz

适合低配 VPS，防止 IO / 网络打爆导致服务抖动。

二、携带认证信息下载（Token / Cookie / Header）

1️⃣ Bearer Token（API / 私有资源下载）

curl -L \
  -H "Authorization: Bearer $API_KEY" \
  -o model.bin \
  https://api.example.com/v1/files/model.bin

工程建议：

Token 永远从环境变量读取
禁止写死在脚本里

2️⃣ Cookie 下载（登录态资源）

curl -L \
  -H "Cookie: session=xxxxx" \
  -o private.zip \
  https://example.com/private/download

3️⃣ 自定义 Header（内部网关 / 鉴权系统）

curl -L \
  -H "X-APP-ID: app01" \
  -H "X-APP-TOKEN: tokenxxx" \
  -o file.bin \
  https://gateway.example.com/download

三、接口请求调试（后端 / AI API / 网关）

1️⃣ GET 请求

curl -X GET https://api.example.com/v1/models

2️⃣ POST JSON

curl -X POST https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "hello"}]
  }'

3️⃣ 查看完整请求细节（排错必备）

curl -v https://api.example.com/v1/models

4️⃣ 仅查看响应头

curl -I https://example.com/file.zip

用于判断：

是否 302
Content-Length
是否支持 Range

四、网络问题定位（连接不上 ≠ 服务不可用）

1️⃣ 只测试连通性（不关心内容）

curl -v http://96.44.131.74:8317/v1

用于区分：

网络问题
路径问题
API 类型错误

2️⃣ 设置超时（防止卡死）

curl --connect-timeout 5 --max-time 20 https://example.com

3️⃣ 忽略 HTTPS 证书（仅调试用）

curl -k https://self-signed.example.com

生产环境严禁使用 -k。

五、Windows 使用 curl 的工程坑位

PowerShell 里的 curl 是别名，参数行为不同。
统一使用：

curl.exe -L -o app.tar.gz https://example.com/app.tar.gz

如果出现：

参数不生效
-L 报错
-o 行为异常

99% 是因为调用了 PowerShell 内置别名。

六、自动化脚本封装（部署标准姿势）

Linux 下载脚本模板

#!/bin/bash
set -e

URL="$1"
OUT="$2"

if [ -z "$URL" ] || [ -z "$OUT" ]; then
  echo "Usage: download.sh <url> <output>"
  exit 1
fi

curl -L -C - -# -o "$OUT" "$URL"
echo "Downloaded: $OUT"

调用：

./download.sh https://example.com/app.tar.gz app.tar.gz

Windows PowerShell 版

param(
  [string]$Url,
  [string]$Out
)

if (-not $Url -or -not $Out) {
  Write-Host "Usage: download.ps1 <url> <output>"
  exit 1
}

curl.exe -L -o $Out $Url
Write-Host "Downloaded: $Out"

七、curl 常见错误速查表

现象	根因
下载到 HTML	忘了加 `-L`
401 / Missing API Key	Header 没传 Token
连接成功但接口报错	路径错 / API 类型错
Windows 参数异常	用了 PowerShell 别名 curl
下载一半失败	未使用 `-C -`
一直卡住	未设置超时

八、工程最佳实践总结

所有下载命令默认加：-L -C - -#
所有 Token 从环境变量读取
Windows 强制使用 curl.exe
大文件下载必须支持断点续传
部署脚本统一封装 curl 调用
调试接口第一步永远加 -v