长运行脚本中Google Access Token的refreshToken失效问题排查

核心问题原因 #

调用$client->refreshToken()后getAccessToken()返回null，主要有以下几种可能：

• 刷新令牌失效：Google会在多种场景下吊销刷新令牌，包括用户修改账号密码、主动撤销应用权限、应用被标记为不安全、令牌长期未使用，或者Google的安全策略更新。
• API请求失败：网络波动导致请求未到达Google服务器、Google OAuth服务临时故障，或者请求参数错误（如数据库中存储的客户端ID/密钥与Google Cloud控制台不匹配）。
• 客户端库bug：老旧版本的Google PHP客户端库可能存在逻辑缺陷，导致刷新令牌后未正确更新客户端内部的令牌数据。

测试与定位步骤 #

• 添加详细日志捕获异常：在refreshToken()调用处增加异常捕获和日志输出，明确失败原因：

  try {
      $client->refreshToken($refreshToken);
      error_log("Refresh token succeeded for rowId: {$rowId}");
  } catch (Exception $e) {
      error_log("Refresh token failed: " . $e->getMessage());
      error_log("Refresh token in use: {$refreshToken}");
  }
  $accessTokenArray = $client->getAccessToken();
  error_log("Access token data after refresh: " . print_r($accessTokenArray, true));
  

• 手动验证刷新令牌有效性：用curl直接调用Google令牌端点，排查令牌本身是否有效：

  curl -X POST https://oauth2.googleapis.com/token \
    -d "client_id=你的客户端ID" \
    -d "client_secret=你的客户端密钥" \
    -d "refresh_token=数据库中存储的刷新令牌" \
    -d "grant_type=refresh_token"
  

  如果返回invalid_grant等错误，说明令牌已失效；若返回正常的令牌数据，则问题出在代码或客户端库。
• 核对客户端配置：检查数据库中存储的clientId、clientSecret是否与Google Cloud控制台中的应用信息完全一致，确认没有被误修改。
• 检查API状态：登录Google Cloud控制台，确认Drive API已启用，OAuth consent screen未被限制（如处于测试模式且超过用户限制）。

修复与自动运行优化 #

• 增加空值防护：在使用$accessTokenArray前先做类型判断，避免触发TypeError：

  $accessTokenArray = $client->getAccessToken();
  if (is_array($accessTokenArray) && array_key_exists('access_token', $accessTokenArray)) {
      $accessToken = $accessTokenArray['access_token'];
      $expires = $accessTokenArray['expires_in'] + time();
      $authHistoryRow['accessToken'] = $accessTokenArray['access_token'];
      $authHistoryRow['expires'] = Date('Y/m/d H:i:s', $expires);
  } else {
      // 标记刷新失败，触发重新授权流程
      $accessToken = null;
      error_log("Failed to retrieve valid access token after refresh attempt");
  }
  

• 实现自动恢复机制：当刷新令牌失效时，自动启动授权流程（无人值守环境可考虑切换为服务账号认证，或预存备用的刷新令牌）。
• 更新客户端库：将Google PHP Client库升级到最新版本，修复已知的令牌刷新相关bug。
• 轮换刷新令牌：每次成功刷新后，检查返回结果中是否包含新的刷新令牌（部分场景下Google会返回），并更新数据库中的存储值，降低令牌失效风险。

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