# cURL 常用操作指南

cURL (`Client URL`) 是一个强大的命令行工具，用于传输数据，支持多种协议（HTTP/HTTPS/FTP/SFTP等）。它广泛用于 API 测试、文件传输和网络调试。

---

## **1. 基本请求**
### **GET 请求**
```bash
curl https://example.com
```
- **获取网页内容**
- **带参数**：
  ```bash
  curl "https://example.com/api?param1=value1&param2=value2"
  ```

### **POST 请求**
```bash
curl -X POST https://example.com/api \
     -d "key1=value1&key2=value2"
```
- **发送 JSON 数据**：
  ```bash
  curl -X POST https://example.com/api \
       -H "Content-Type: application/json" \
       -d '{"key1":"value1", "key2":"value2"}'
  ```

---

## **2. 请求头设置**
### **添加自定义 Header**
```bash
curl -H "Authorization: Bearer token123" \
     -H "User-Agent: MyApp/1.0" \
     https://example.com/api
```
- **查看服务器返回的 Headers**：
  ```bash
  curl -I https://example.com  # 只显示 Headers
  ```

---

## **3. 文件上传 & 下载**
### **上传文件**
```bash
curl -X POST https://example.com/upload \
     -F "file=@/path/to/file.txt" \
     -F "name=myfile"
```
- `-F` 用于 `multipart/form-data` 上传

### **下载文件**
```bash
curl -O https://example.com/file.zip  # 保存为原文件名
curl -o custom_name.zip https://example.com/file.zip  # 自定义文件名
```

---

## **4. 认证 & Cookies**
### **Basic Auth**
```bash
curl -u username:password https://example.com
```
- **或只输入用户名，交互式输入密码**：
  ```bash
  curl -u username https://example.com
  ```

### **Cookie 管理**
```bash
curl --cookie "name=value" https://example.com
```
- **保存 Cookie 到文件**：
  ```bash
  curl -c cookies.txt https://example.com/login
  ```
- **使用 Cookie 文件**：
  ```bash
  curl -b cookies.txt https://example.com/dashboard
  ```

---

## **5. 调试 & 高级选项**
### **显示详细请求信息**
```bash
curl -v https://example.com  # 显示请求 & 响应 Headers
curl --trace-ascii debug.txt https://example.com  # 输出调试信息到文件
```

### **跟随重定向**
```bash
curl -L https://example.com  # 自动跳转
```

### **限速下载**
```bash
curl --limit-rate 100K -O https://example.com/largefile.zip
```
- `100K` = 100KB/s，可设置 `M` (MB/s) 或 `G` (GB/s)

---

## **6. 代理设置**
### **HTTP/HTTPS 代理**
```bash
curl -x http://proxy-server:8080 https://example.com
```
- **带认证的代理**：
  ```bash
  curl -x http://user:pass@proxy-server:8080 https://example.com
  ```

### **SOCKS5 代理**
```bash
curl --socks5 127.0.0.1:1080 https://example.com
```

---

## **7. 保存响应到变量（Bash）**
```bash
response=$(curl -s https://example.com/api)
echo "$response"
```
- `-s` 静默模式（不显示进度）

---

## **8. 常用组合命令**
### **检查 API 返回状态码**
```bash
curl -s -o /dev/null -w "%{http_code}" https://example.com/api
```
- `-o /dev/null` 丢弃响应体
- `-w "%{http_code}"` 只显示 HTTP 状态码

### **测试 API 响应时间**
```bash
curl -w "DNS: %{time_namelookup} | Connect: %{time_connect} | Total: %{time_total}\n" \
     -o /dev/null -s https://example.com
```

---

## **总结**
| 用途 | 命令示例 |
|------|----------|
| **GET 请求** | `curl https://example.com` |
| **POST 请求** | `curl -X POST -d "data" https://example.com/api` |
| **JSON 请求** | `curl -H "Content-Type: application/json" -d '{"key":"value"}'` |
| **下载文件** | `curl -O https://example.com/file.zip` |
| **上传文件** | `curl -F "file=@localfile.txt" https://example.com/upload` |
| **认证** | `curl -u user:pass https://example.com` |
| **代理** | `curl -x http://proxy:8080 https://example.com` |
| **调试** | `curl -v https://example.com` |

cURL 功能非常强大，适用于自动化脚本、API 测试和网络调试。更多选项可查看 `man curl` 或 `curl --help`。