应根据需求选择：需开箱即用选nuwave/lighthouse，需底层定制选webonyx/graphql-php；前者为Laravel专用完整方案，后者为无框架依赖的解析引擎。

直接装 nuwave/lighthouse 还是 webonyx/graphql-php？

取决于你要的是「开箱即用的 GraphQL 服务端」还是「底层可定制的解析引擎」。nuwave/lighthouse 是 Laravel 专用的完整方案，自带 schema 定义、查询解析、Eloquent 集成、认证绑定；webonyx/graphql-php 是纯 PHP 实现的参考规范库，不依赖框架，但所有路由、输入验证、数据获取都得自己写。

用 composer require 装 nuwave/lighthouse 的实操要点

这是 Laravel 项目快速启用 GraphQL 的主流选择。注意版本对齐和发布资源：

Json Schema Toolkit

使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。

下载

• Laravel 10+ 请用 composer require nuwave/lighthouse:^6.0（^5.0 不兼容 PHP 8.2+ 类型声明）
• 装完必须运行 php artisan lighthouse:install，它会生成 graphql/ 目录、基础 schema.graphql 和配置文件 lighthouse.php
• 别跳过 php artisan vendor:publish --provider="NuwaveLighthouseLighthouseServiceProvider"，否则中间件、指令、模板全缺失
• 路由默认不自动注册，需在 routes/api.php 手动加：

  use NuwaveLighthouseSupportHttpControllersGraphQLController;
  Route::post('/graphql', [GraphQLController::class, 'query']);

单独集成 webonyx/graphql-php 的典型场景和坑

适合非 Laravel 项目、需要细粒度控制执行流程、或已有自定义 resolver 逻辑的场景。但它不处理 HTTP 层，也不生成 SDL schema：

• 执行 composer require webonyx/graphql-php 后，你只拿到 GraphQLGraphQL 类和类型系统，没路由、没解析器注册机制
• 必须手写入口脚本，例如响应 POST 请求时调用 GraphQL::executeQuery(...)，且要传入完整 Schema 对象
• 类型定义要用 PHP 数组或 ObjectType 类手动拼，比 SDL 写法冗长；推荐搭配 webonyx/graphql-php-tools 做 SDL 解析
• 错误堆栈默认暴露敏感路径，上线前务必设置 ['debug' => false] 并捕获 GraphQLErrorError 异常

两个库共存可能引发的冲突点

极少有人同时装两者，但若误操作或依赖传递引入了双版本，会出现类型类加载冲突或 Schema 构建失败：

• webonyx/graphql-php 的 GraphQLTypeSchema 和 lighthouse 内部封装的同名类不是同一实例，不能混用
• lighthouse v6 锁定了 webonyx/graphql-php:^14.11，如果你手动 require 了 ^15.0，Composer 会报 conflict 并拒绝安装
• 调试时看到 Class 'GraphQL\Type\Schema' not found，大概率是 autoloader 没生效——检查 vendor/composer/autoload_psr4.php 是否包含 GraphQL\ 映射

实际跑通的关键不在装哪个包，而在 schema 文件是否被正确加载、resolver 方法是否存在且返回结构匹配、HTTP 入口是否把原始请求体传给了执行器。很多“400 Bad Request”其实是 JSON body 没被正确读取，而不是 GraphQL 本身的问题。