排查自定义插件导致WPGraphiQL内部服务器错误的方法

问题描述 #

访问wp/wp-admin/admin.php?page=graphiql-ide时页面卡顿，浏览器控制台抛出：

app.js?ver=b46a34de121156c88432:30 Uncaught (in promise) Error: Internal server error
    at new t (app.js?ver=b46a34de121156c88432:30:39347)
    at app.js?ver=b46a34de121156c88432:30:78333
    at n (app.js?ver=b46a34de121156c88432:30:32923)
    at app.js?ver=b46a34de121156c88432:30:32848
    at new Promise (<anonymous>)
    at Object.then (app.js?ver=b46a34de121156c88432:30:32814)
    at Object.next (app.js?ver=b46a34de121156c88432:30:32933)
    at rh (app.js?ver=b46a34de121156c88432:30:7097)
    at ih (app.js?ver=b46a34de121156c88432:30:7610)
    at t.next (app.js?ver=b46a34de121156c88432:30:8150)

已开启以下调试配置但无额外错误日志输出：

Config::define('SAVEQUERIES', true);
Config::define('WP_DEBUG', true);
Config::define('WP_DEBUG_DISPLAY', true);
Config::define('WP_DISABLE_FATAL_ERROR_HANDLER', true);
Config::define('SCRIPT_DEBUG', true);
Config::define('GRAPHQL_DEBUG', true);
Config::define('WP_DEBUG_LOG', true);
ini_set('display_errors', 1);

额外调试方法 #

• 直接调用GraphQL端点获取原始错误
  用Postman或curl直接发送请求到your-site.com/graphql，执行GraphiQL默认的Schema自省查询（获取全量Schema的请求），查看响应体中的详细错误信息，比如PHP报错、字段解析失败的具体原因。

• 启用WPGraphQL错误捕获钩子
  在自定义插件或主题的functions.php中添加以下代码，强制记录GraphQL错误细节到日志：

  add_filter('graphql_response_errors', function($errors, $source, $context, $info) {
      if (WP_DEBUG) {
          foreach ($errors as $error) {
              if (isset($error->debugMessage)) {
                  error_log('GraphQL Error: ' . $error->debugMessage);
                  error_log('Trace: ' . print_r($error->getTraceAsString(), true));
              }
          }
      }
      return $errors;
  }, 10, 4);
  

  之后查看wp-content/debug.log，会得到更具体的错误追踪栈。

• 逐步排查自定义插件的GraphQL逻辑
  分段注释自定义插件中注册GraphQL类型、字段、Resolver的代码，每注释一段就刷新GraphiQL页面，定位触发错误的具体代码块。重点检查：

  • Resolver函数中是否有未处理的PHP错误（如调用不存在的函数、未定义变量）
  • 自定义类型定义是否符合WPGraphQL规范（如字段类型不匹配、缺少必填参数）
  • 是否修改了WPGraphQL核心逻辑导致Schema生成失败

• 检查服务器级错误日志
  除了WordPress的debug.log，查看服务器自身的错误日志（如Nginx的error.log、Apache的error_log），很多500内部错误会被服务器记录，比如PHP内存耗尽、文件权限问题等。

• 强制开启PHP详细错误日志
  在wp-config.php中添加以下配置，捕获WordPress错误系统未记录的底层PHP报错：

  ini_set('error_reporting', E_ALL);
  ini_set('log_errors', 1);
  ini_set('error_log', ABSPATH . 'php-error.log');
  

  之后查看站点根目录下的php-error.log文件。

内容的提问来源于stack exchange，提问作者linucks