【保姆级教程】PHP / Laravel 接入 Claude API 完整指南HTTP Client Service 封装 上线优化关键词PHP、Laravel、Claude API、Anthropic、Messages API、AI 集成、HTTP Client本文面向有一定 Laravel 基础的 PHP 开发者完整讲解如何在项目中集成 Claude API从最小示例到生产级封装附常见错误排查表。目录方案选型Claude API / Code / 网页版区别环境准备HTTP Client 最小示例原生 PHP cURL 示例ClaudeService 封装参数详解错误排查表上线优化清单1. 方案选型方案适合场景建议Laravel HTTP Client快速接入、逻辑简单✅ 优先Claude PHP SDKtool use / files / vision / batch有需要再用Prism / Provider 抽象多模型Claude/OpenAI/Gemini中大型项目Claude Code / Agent SDK辅助开发非业务调用2. 三者区别Claude 网页版面向个人的聊天产品。Claude Code开发者 CLI 工具代码理解/重构。Claude API应用系统调用的接口本文主角。接入可用 Anthropic 官方 API也可用第三方兼容服务如 ClaudeAPIwww.claudeeapi.com通常提供兼容接口、多线路、中文支持、企业开票。注意第三方兼容平台非 Anthropic 官方模型/额度/计费以平台官网为准。3. 环境准备PHP ≥ 8.1Laravel 10/11/12 均可。.envANTHROPIC_API_KEYyour_api_key_here ANTHROPIC_BASE_URLhttps://api.anthropic.com ANTHROPIC_VERSION2023-06-01 ANTHROPIC_MODELclaude-3-5-sonnet-latestconfig/services.phpanthropic [ 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_encodeLaravel 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. 错误排查表错误常见原因处理401Key 错 /.env没加载 / Header 写错检查x-api-keyphp artisan config:clear400请求体格式错 /messages嵌套错打印请求数组别 JSON 套 JSON429限流或额度不足退避重试、用户限流、队列削峰500/529服务端繁忙稍后重试切备用方案timeout长文本阻塞调timeout()长任务用 Queue注意retry()不是越大越好。会写库/生成订单/扣额度的任务必须先做幂等否则重复扣费。9. 上线优化清单限制输入长度 → 用户级限流RateLimiter→ 请求日志脱敏→ 成本用量统计ai_requests表→ 降级方案。长任务上 Queue聊天场景升级 Streaming复杂能力再评估 SDK / Prism。觉得有用的话点赞 收藏方便以后查阅。有问题欢迎评论区交流。
