【保姆级教程】PHP / Laravel 接入 Claude API 完整指南（HTTP Client + Service 封装 + 上线优化）

关键词：PHP、Laravel、Claude API、Anthropic、Messages API、AI 集成、HTTP Client

本文面向有一定 Laravel 基础的 PHP 开发者，完整讲解如何在项目中集成 Claude API，从最小示例到生产级封装，附常见错误排查表。

目录

1. 方案选型
2. Claude API / Code / 网页版区别
3. 环境准备
4. HTTP Client 最小示例
5. 原生 PHP cURL 示例
6. ClaudeService 封装
7. 参数详解
8. 错误排查表
9. 上线优化清单

1. 方案选型

方案	适合场景	建议
Laravel HTTP Client	快速接入、逻辑简单	✅ 优先
Claude PHP SDK	tool use / files / vision / batch	有需要再用
Prism / Provider 抽象	多模型（Claude/OpenAI/Gemini）	中大型项目
Claude Code / Agent SDK	辅助开发	非业务调用

2. 三者区别

• Claude 网页版：面向个人的聊天产品。
• Claude Code：开发者 CLI 工具，代码理解/重构。
• Claude API：应用系统调用的接口（本文主角）。

接入可用 Anthropic 官方 API，也可用第三方兼容服务如 ClaudeAPI（www.claudeeapi.com），通常提供兼容接口、多线路、中文支持、企业开票。注意：第三方兼容平台非 Anthropic 官方，模型/额度/计费以平台官网为准。

3. 环境准备

PHP ≥ 8.1，Laravel 10/11/12 均可。

.env：

ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_BASE_URL=https://api.anthropic.com
ANTHROPIC_VERSION=2023-06-01
ANTHROPIC_MODEL=claude-3-5-sonnet-latest

config/services.php：

'anthropic' => [
    'key' => env('ANTHROPIC_API_KEY'),
    'base_url' => env('ANTHROPIC_BASE_URL', 'https://api.anthropic.com'),
    'version' => env('ANTHROPIC_VERSION', '2023-06-01'),
    'model' => env('ANTHROPIC_MODEL', 'claude-3-5-sonnet-latest'),
],

改 .env 后执行 php artisan config:clear；生产环境开了配置缓存需重新生成。

4. HTTP Client 最小示例

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Route;

Route::post('/ai/chat', function () {
    $response = Http::withHeaders([
        'x-api-key' => config('services.anthropic.key'),
        'anthropic-version' => config('services.anthropic.version'),
        'content-type' => 'application/json',
    ])->post(config('services.anthropic.base_url') . '/v1/messages', [
        'model' => config('services.anthropic.model'),
        'max_tokens' => 800,
        'messages' => [
            ['role' => 'user', 'content' => '请用三句话解释 Laravel 队列的作用。'],
        ],
    ]);

    if ($response->failed()) {
        return response()->json(['error' => $response->json()], $response->status());
    }
    return response()->json(['text' => $response->json('content.0.text')]);
});

关键字段：model、max_tokens（最大输出，非输入）、messages、role、content、anthropic-version、x-api-key。

避坑：不要把 messages 拼成字符串，也不要对数组重复 json_encode，Laravel HTTP Client 直接传数组即可。

5. 原生 PHP cURL 示例

$apiKey = getenv('ANTHROPIC_API_KEY');
$payload = [
    'model' => 'claude-3-5-sonnet-latest',
    'max_tokens' => 800,
    'messages' => [
        ['role' => 'user', 'content' => '请生成一段商品详情页的 SEO 描述。'],
    ],
];

$ch = curl_init('https://api.anthropic.com/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'content-type: application/json',
        'x-api-key: ' . $apiKey,
        'anthropic-version: 2023-06-01',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 30,
]);
$result = curl_exec($ch);
if ($result === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
$data = json_decode($result, true);
echo $data['content'][0]['text'] ?? '';

6. ClaudeService 封装

namespace App\Services;

use Illuminate\Support\Facades\Http;
use RuntimeException;

class ClaudeService
{
    public function chat(string $prompt, ?string $system = null): string
    {
        $payload = [
            'model' => config('services.anthropic.model'),
            'max_tokens' => 800,
            'temperature' => 0.3,
            'messages' => [['role' => 'user', 'content' => $prompt]],
        ];
        if ($system) {
            $payload['system'] = $system;
        }

        $response = Http::timeout(30)->retry(2, 500)
            ->withHeaders([
                'x-api-key' => config('services.anthropic.key'),
                'anthropic-version' => config('services.anthropic.version'),
                'content-type' => 'application/json',
            ])
            ->post(config('services.anthropic.base_url') . '/v1/messages', $payload);

        if ($response->failed()) {
            throw new RuntimeException('Claude API request failed: ' . $response->body());
        }
        return $response->json('content.0.text') ?? '';
    }
}

7. 参数详解

• model：决定能力/速度/成本。
• max_tokens：最大输出 token。
• temperature：客服/分类用 0~0.3，创意写作调高。
• system：定义角色与输出约束；要 JSON 输出时服务端仍需校验。

8. 错误排查表

错误	常见原因	处理
401	Key 错 / .env 没加载 / Header 写错	检查 x-api-key，php artisan config:clear
400	请求体格式错 / messages 嵌套错	打印请求数组，别 JSON 套 JSON
429	限流或额度不足	退避重试、用户限流、队列削峰
500/529	服务端繁忙	稍后重试，切备用方案
timeout	长文本阻塞	调 timeout()，长任务用 Queue

注意：retry() 不是越大越好。会写库/生成订单/扣额度的任务必须先做幂等，否则重复扣费。

9. 上线优化清单

限制输入长度 → 用户级限流（RateLimiter）→ 请求日志（脱敏）→ 成本用量统计（ai_requests 表）→ 降级方案。长任务上 Queue，聊天场景升级 Streaming，复杂能力再评估 SDK / Prism。

觉得有用的话，点赞 + 收藏，方便以后查阅。有问题欢迎评论区交流。