php cURL 常用参数详解与实用指南

PHP 的 cURL 扩展是实现 HTTP/HTTPS 网络请求的核心工具。通过 curl_setopt() 函数设置多种请求参数。

一、核心基础参数（必选 / 必备）

这些参数是构建 cURL 请求的基础，确保请求能够正常初始化和执行。

|------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_URL | 字符串 | **必填。**目标请求 URL，例如 https://api.example.com/user。 |
| CURLOPT_RETURNTRANSFER | 布尔值（true/false） | - true：将请求结果作为字符串返回（推荐） - false：直接输出到页面（默认，不推荐） |
| CURLOPT_HEADER | 布尔值（true/false） | - true：响应结果包含响应头信息 - false：仅返回响应体（默认，常用）补充：如需单独获取响应头，可用 CURLOPT_HEADERFUNCTION |
| CURLOPT_TIMEOUT | 整数 | 设置请求的超时时间（秒），超时自动终止，推荐设置（如 30 秒），防止无限等待。 |
| CURLOPT_CONNECTTIMEOUT | 整数 | 设置连接服务器的超时时（秒），仅针对建立 TCP 连接阶段，常与 CURLOPT_TIMEOUT 配合使用（如 10 秒）。 |

二、请求方法与请求体参数（POST/PUT/DELETE 等）

默认 cURL 请求为 GET 方法。以下参数用于修改请求方法及传递请求体数据。

1. 请求方法相关

|-----------------------|-----------------|-------------------------------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_POST | 布尔值（true/false） | - true：请求方法设为 POST（常用） - false：不使用 POST（默认） |
| CURLOPT_CUSTOMREQUEST | 字符串 | 自定义请求方法（如 PUT、DELETE、PATCH），如： curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT") 注意：设置后需手动处理请求体数据。 |

2. 请求体数据相关

|--------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_POSTFIELDS | 字符串 / 数组 / JSON 字符串 | 用于传递 POST/PUT 等请求的请求体数据，常见三种场景： 1. 表单提交（ application/x-www-form-urlencoded ）：传数组或 url 编码字符串（如 name=test&age=20） 2. JSON 提交（ application/json）：传 JSON 编码字符串（需配合 CURLOPT_HTTPHEADER 设置请求头） 3. 文件上传：PHP < 5.5 用 @文件路径，新版本推荐用 CURLFile 类 |
| CURLOPT_UPLOAD | 布尔值（true/false） | 启用文件上传模式，配合 CURLOPT_INFILE 使用（较少用，文件上传建议优先用 CURLOPT_POSTFIELDS ） |

三、请求头参数

用于设置 HTTP 请求头，可模拟浏览器、指定数据格式、携带认证信息等。

|------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_HTTPHEADER | 数组 | 设置自定义请求头，数组每元素为一条请求头，如： "Content-Type: application/json", "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0", "Authorization: Bearer token123456"] |
| CURLOPT_USERPWD | 字符串 | HTTP 基础认证，格式为用户名:密码，等价于请求头 Authorization: Basic {base64编码}。 |
| CURLOPT_FOLLOWLOCATION | 布尔值（true/false） | - true：自动跟随 3xx 重定向（如 301、302） - false：不跟随（默认）补充：最大跟随次数可用 CURLOPT_MAXREDIRS 设置。 |

四、HTTPS 相关参数（重点）

请求目标 URL 为 https 时，需要配置以下参数解决 SSL 证书验证问题，否则可能请求失败。

|------------------------|-----------------|-------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_SSL_VERIFYPEER | 布尔值（true/false） | - true：验证服务器 SSL 证书（生产环境推荐，默认） - false：跳过证书验证（开发/测试环境可临时用，生产环境禁止，安全风险大） |
| CURLOPT_SSL_VERIFYHOST | 整数（0/1/2） | - 2：验证证书主机名与目标一致（推荐，默认） - 1：已废弃，无实际作用 - 0：跳过主机名验证（不推荐，存在风险） |
| CURLOPT_SSLCERT | 字符串 | 客户端 SSL 证书文件路径（服务器要求客户端证书时使用） |
| CURLOPT_SSLKEY | 字符串 | 客户端 SSL 证书对应的私钥文件路径 |
| CURLOPT_SSLVERSION | 整数 | 指定 SSL/TLS 版本，CURL_SSLVERSION_TLSv1_2 （强制用 TLS 1.2，防止因版本不兼容导致失败） |

五、响应处理与调试参数

用于获取更详细的请求/响应信息，便于调试排查问题。

|------------------------|-----------------|----------------------------------------------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_HEADERFUNCTION | 回调函数 | 自定义响应头处理函数，可单独捕获每行响应头，避免与响应体混淆。 |
| CURLOPT_VERBOSE | 布尔值（true/false） | - true：开启详细模式，输出完整调试信息（包括连接、请求头、响应头等） - false：关闭（默认）补充：建议配合 CURLOPT_STDERR，将调试信息写入文件，避免输出到页面。 |
| CURLOPT_STDERR | 资源句柄 | 将 CURLOPT_VERBOSE 产生的调试信息写入指定文件，如： curl_setopt($ch, CURLOPT_STDERR, fopen('curl_debug.log', 'w')); |

六、其他常用辅助参数

|--------------------|-----------------|----------------------------------------------------------------|
| 参数常量 | 取值类型 | 详细说明 |
| CURLOPT_COOKIE | 字符串 | 携带 Cookie 信息，格式如key1=value1; key2=value2。 |
| CURLOPT_COOKIEJAR | 字符串 | 请求结束后，将服务器返回的 Cookie 保存到指定文件路径。 |
| CURLOPT_COOKIEFILE | 字符串 | 从指定文件读取 Cookie 并携带到请求中，实现会话保持。 |
| CURLOPT_PROXY | 字符串 | 设置代理服务器，格式如http://代理IP:端口或socks5://代理IP:端口。 |
| CURLOPT_NOBODY | 布尔值（true/false） | - true：仅发送请求头，不获取响应体（常用于 HEAD 请求，检测资源是否存在） - false：获取完整响应体（默认） |

七、完整可运行示例（整合核心参数）

php 复制代码

<?php
// 1. 初始化 cURL 句柄
$ch = curl_init();

// 2. 设置核心参数
$targetUrl = "https://api.example.com/user";
curl_setopt($ch, CURLOPT_URL, $targetUrl); // 目标 URL
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 结果以字符串返回
curl_setopt($ch, CURLOPT_TIMEOUT, 30); // 整体超时 30 秒
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10); // 连接超时 10 秒

// 3. 设置 HTTPS 相关（开发环境临时跳过证书验证，生产环境请删除这两行）
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

// 4. 设置请求方法与请求体（POST + JSON 格式）
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); // POST 方法（也可直接用 CURLOPT_POST => true）
$postData = [
    "name" => "测试用户",
    "age" => 25
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($postData)); // JSON 编码请求体

// 5. 设置请求头
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "User-Agent: PHP-CURL/7.4",
    "Authorization: Bearer your_token_here"
]);

// 6. 执行请求并获取结果
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 获取响应状态码（200 表示成功）

// 7. 错误处理
if (curl_errno($ch)) {
    $errorMsg = curl_error($ch);
    echo "cURL 请求失败：" . $errorMsg;
} else {
    echo "响应状态码：" . $httpCode . "<br>";
    echo "响应结果：" . $response;
}

// 8. 关闭 cURL 句柄，释放资源
curl_close($ch);
?>

总结

cURL 参数设置核心在于 curl_setopt()，建议按功能分类记忆。优先掌握「核心基础参数」「HTTPS 相关参数」「请求体 / 请求头参数」。
CURLOPT_RETURNTRANSFER = true 是获取响应结果的关键。生产环境下 HTTPS 请求务必保留证书验证，开发环境可临时跳过。
不同请求格式（表单/JSON）需对应配置 CURLOPT_POSTFIELDS 和 Content-Type 请求头。调试时可启用 CURLOPT_VERBOSE 查看详细日志。

如需查阅更多参数或遇到疑问，欢迎留言交流！