首页 > php学习 > PHP cURL 实战教程：从入门到 REST API 调用

PHP cURL 实战教程：从入门到 REST API 调用

2026年6月30日
- php学习
103 次
标签： error, form, js, set, 字符串, 服务器, 目标, 自定义

文章目录

一、什么是 cURL？
二、环境准备
三、基础用法：GET 请求
四、POST 请求与数据提交
五、实战：调用 WordPress REST API 发布文章
六、常见 cURL 错误及排查
七、实用技巧与优化
1. 批量请求用 cURL 多句柄
2. 封装请求日志
3. 处理重定向
八、总结

一、什么是 cURL？

cURL 是一个利用 URL 语法传输数据的命令行工具和库，在 PHP 中通过 curl_* 系列函数实现。简单说，你可以把它理解为 PHP 世界里的"浏览器"——它能模拟 HTTP 请求，获取远程资源，提交表单数据，甚至完成文件上传下载。

在日常开发中，cURL 最常见的应用场景包括：

调用第三方 API（微信支付、阿里云、GitHub API 等）
抓取远程网页内容
文件远程上传与下载
模拟登录和 Session 维持
RESTful API 的客户端实现

二、环境准备

使用 PHP cURL 前，请确认你的 PHP 环境已开启 cURL 扩展：

// 运行以下代码检查
php -m | grep curl

// 或在 PHP 文件中输出
<?php
phpinfo();
?>

如果输出中没有 curl，在宝塔面板中进入 PHP 设置 → 安装扩展 → 找到 cURL 启用即可。

三、基础用法：GET 请求

先从一个最简单的 GET 请求开始：

<?php
function http_get($url) {
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 跳过 SSL 证书验证（开发环境）
    curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/5.0');

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        return ['error' => $error];
    }

    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return [
        'http_code' => $http_code,
        'body' => $response,
    ];
}

// 调用示例：获取 GitHub API 信息
$result = http_get('https://api.github.com');
print_r($result);

这里重点说明几个关键选项：

CURLOPT_RETURNTRANSFER：设为 true 时，curl_exec 返回结果字符串而不是直接输出
CURLOPT_TIMEOUT：请求超时时间（秒），防止接口卡死
CURLOPT_SSL_VERIFYPEER：生产环境建议设为 true 并配置 CA 证书

四、POST 请求与数据提交

POST 请求是调用 API 最常用的方式：

<?php
function http_post($url, $data = [], $headers = []) {
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);

    // 自定义请求头
    if (!empty($headers)) {
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    }

    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return [
        'http_code' => $http_code,
        'body' => $response,
    ];
}

// 示例：POST JSON 数据
$json_data = json_encode([
    'title' => 'PHP cURL 教程',
    'content' => '本文由 API 自动发布',
]);

$result = http_post(
    'https://jsonplaceholder.typicode.com/posts',
    $json_data,
    ['Content-Type: application/json']
);
print_r($result);

注意 CURLOPT_POSTFIELDS 的传参方式：

传入数组时，PHP 会自动编码为 application/x-www-form-urlencoded
传入 JSON 字符串时，务必在 Header 中指定 Content-Type: application/json

五、实战：调用 WordPress REST API 发布文章

结合我们之前配置好的 Application Password，用 PHP cURL 调用 WordPress REST API 发布文章：

<?php
/**
 * WordPress REST API 客户端（PHP 版）
 * 使用前先在 WordPress 后台生成 Application Password
 */

$site_url = 'https://www.example.com';
$username = 'your_admin_username';
$app_password = 'xxxx xxxx xxxx xxxx xxxx xxxx'; // 注意保留空格

/**
 * 调用 WordPress REST API
 */
function wp_api_request($method, $endpoint, $data = null) {
    global $site_url, $username, $app_password;

    $url = rtrim($site_url, '/') . '/wp-json/wp/v2/' . ltrim($endpoint, '/');
    $ch = curl_init();

    // 设置 Basic Auth
    curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $app_password);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'User-Agent: PHP-cURL/1.0',
    ]);

    // 设置请求方法
    switch (strtoupper($method)) {
        case 'POST':
            curl_setopt($ch, CURLOPT_POST, true);
            if ($data) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
            break;
        case 'PUT':
        case 'PATCH':
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, strtoupper($method));
            if ($data) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
            break;
        case 'DELETE':
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
            break;
    }

    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        die("cURL 错误: " . $error);
    }

    curl_close($ch);

    return [
        'http_code' => $http_code,
        'data' => json_decode($response, true),
    ];
}

// ----- 使用示例 -----

// 1. 获取最新文章列表
echo "=== 最新文章 ===\n";
$posts = wp_api_request('GET', 'posts?per_page=3&status=publish');
foreach ($posts['data'] as $post) {
    echo "- " . $post['title']['rendered'] . "\n";
}

// 2. 创建一篇新文章（草稿）
echo "\n=== 创建新文章（草稿）===\n";
$new_post = wp_api_request('POST', 'posts', [
    'title' => 'PHP cURL 实战教程：从入门到REST API调用',
    'content' => '<p>这是一篇通过 PHP cURL 调用 WordPress REST API 自动发布的文章。</p>',
    'status' => 'draft',
    'categories' => [39], // php学习 分类
]);

if ($new_post['http_code'] == 201) {
    $post_id = $new_post['data']['id'];
    echo "文章创建成功！ID: " . $post_id . "\n";
    echo "编辑链接: " . $site_url . "/wp-admin/post.php?post=" . $post_id . "&action=edit\n";
} else {
    echo "创建失败: " . print_r($new_post['data'], true) . "\n";
}

// 3. 更新文章状态为已发布
echo "\n=== 发布文章 ===\n";
if (isset($post_id)) {
    $publish = wp_api_request('POST', 'posts/' . $post_id, [
        'status' => 'publish',
    ]);
    if ($publish['http_code'] == 200) {
        echo "文章已发布！\n";
    }
}

// 4. 上传特色图片
echo "\n=== 上传图片 ===\n";
$image_path = '/path/to/featured-image.jpg';
if (file_exists($image_path)) {
    $ch = curl_init();
    $url = rtrim($site_url, '/') . '/wp-json/wp/v2/media';

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $app_password);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $file = new CURLFile($image_path);
    curl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => $file]);

    $result = curl_exec($ch);
    $media = json_decode($result, true);
    curl_close($ch);

    if (isset($media['id'])) {
        echo "图片上传成功！ID: " . $media['id'] . "\n";
    }
}

六、常见 cURL 错误及排查

错误代码	错误信息	常见原因	解决方案
6	Couldn't resolve host	DNS 解析失败	检查 URL 是否正确，服务器能否访问外网
7	Failed to connect	目标服务器无法连接	检查端口是否开放，有无防火墙拦截
28	Operation timed out	请求超时	增大 CURLOPT_TIMEOUT 值
52	Empty reply from server	服务器无响应	检查服务器状态和 PHP 错误日志
60	SSL certificate problem	SSL 证书验证失败	配置 CA 证书或临时设为 false（不推荐生产）
77	Problem with CA cert	CA 证书路径错误	设置 CURLOPT_CAINFO 指向正确的证书文件

七、实用技巧与优化

1. 批量请求用 cURL 多句柄

当需要同时请求多个 API 时，使用 curl_multi_* 系列函数可以大幅提升效率：

<?php
function http_multi_get($urls) {
    $mh = curl_multi_init();
    $handles = [];

    foreach ($urls as $key => $url) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);
        curl_multi_add_handle($mh, $ch);
        $handles[$key] = $ch;
    }

    $running = null;
    do {
        curl_multi_exec($mh, $running);
        curl_multi_select($mh); // 避免忙等，节省 CPU
    } while ($running > 0);

    $results = [];
    foreach ($handles as $key => $ch) {
        $results[$key] = curl_multi_getcontent($ch);
        curl_multi_remove_handle($mh, $ch);
        curl_close($ch);
    }
    curl_multi_close($mh);

    return $results;
}

// 同时请求 3 个 API
$urls = [
    'github' => 'https://api.github.com',
    'json' => 'https://jsonplaceholder.typicode.com/posts/1',
    'wp' => 'https://www.example.com/wp-json/wp/v2/posts?per_page=1',
];
$results = http_multi_get($urls);

2. 封装请求日志

<?php
function log_curl_request($url, $http_code, $duration, $error = '') {
    $log = sprintf(
        "[%s] %s | HTTP %d | %.4fs | %s\n",
        date('Y-m-d H:i:s'),
        $url,
        $http_code,
        $duration,
        $error ?: 'OK'
    );
    file_put_contents(__DIR__ . '/curl_log.txt', $log, FILE_APPEND);
}

// 使用示例
$start = microtime(true);
$result = http_get('https://api.example.com');
$duration = microtime(true) - $start;
log_curl_request($url, $result['http_code'], $duration, $result['error'] ?? '');

3. 处理重定向

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);  // 自动跟随重定向
curl_setopt($ch, CURLOPT_MAXREDIRS, 5);           // 最多跟随 5 次

八、总结

PHP cURL 是服务端 HTTP 请求的基石，无论是调用第三方 API、抓取远程数据，还是构建 REST API 客户端，都离不开它。掌握好 cURL 的常用选项和错误处理，你的 PHP 开发能力会上一个台阶。

本文通过 GET、POST、REST API 实战、批量请求优化等场景，完整展示了 PHP cURL 的使用方法。如果你刚开始接触，建议从 GET 请求开始，逐步尝试 POST 提交数据，最后挑战用 WordPress REST API 实现自动化内容管理——就像我们在这篇文章中做的那样。

希望这篇文章对你有帮助！欢迎在评论区交流你的 cURL 使用经验。

若非作者标注皆为李涛自留地原创文章，转载或复制请以超链接形式并注明出处。

上一篇: PHP concat() 函数详解：字符串拼接的 N 种方法
下一篇: PHP array_merge() vs + 运算符：数组合并的 N 种方法与性能对比