使用PHP调用Gmail API无法获取Refresh Token及令牌过期判断异常

一、无法获取Refresh Token的解决方法 #

1. 强制触发重新授权
   Google OAuth在用户已授权过相同scope的情况下，默认不会返回Refresh Token。需修改prompt参数为'consent'，强制用户重新确认授权，从而获取Refresh Token：

   $this->client->setPrompt('consent');
   

   同时，可先登录Google账号，在【安全】-【第三方应用访问权限】中移除你的应用授权，再重新走授权流程，确保首次获取完整令牌。

2. 检查OAuth客户端配置

   • 确认Google Cloud控制台中，你的OAuth客户端类型与使用场景匹配（Web应用/桌面应用），且redirect_uri与代码中完全一致。
   • 若使用外部用户，需将OAuth consent screen的用户类型设为【外部】；内部用户需确保域管理员已配置相关权限。

3. 及时保存Refresh Token
   Google仅在首次授权或强制重新授权时返回Refresh Token，后续刷新Access Token不会生成新的Refresh Token。需在获取令牌后立即保存：

   $token = $this->client->fetchAccessTokenWithAuthCode($code);
   if (isset($token['refresh_token'])) {
       // 自定义逻辑保存refresh_token，例如存入数据库
       $this->saveRefreshToken($token['refresh_token']);
   }
   // 保存完整令牌数据
   $this->saveAccessToken($token);
   

二、isAccessTokenExpired()始终返回true的解决方法 #

1. 修复异常的created时间戳
   你返回的created字段值7374384324是未来时间戳（对应2100年左右），这直接导致过期判断逻辑异常。排查方向：

   • 检查服务器系统时间是否与UTC时间同步，时间错误会导致时间戳计算偏差。
   • 尝试升级google/apiclient到v2.16.0及以上版本，v2.15.0可能存在时间戳返回异常的bug。
   • 若保存令牌时使用数据库，确保created字段的存储类型为bigint（避免大整数截断），读取时需保持整数类型。

2. 确保正确设置AccessToken
   从存储中读取令牌后，必须调用setAccessToken()将完整令牌数据传入客户端：

   // 从存储中读取保存的令牌
   $savedToken = $this->getSavedAccessToken();
   $this->client->setAccessToken($savedToken);
   
   // 验证过期状态
   if ($this->client->isAccessTokenExpired()) {
       $refreshToken = $this->client->getRefreshToken();
       if ($refreshToken) {
           // 使用refresh token刷新令牌
           $newToken = $this->client->fetchAccessTokenWithRefreshToken($refreshToken);
           $this->saveAccessToken($newToken);
       } else {
           // 无refresh token，跳转重新授权
           header('Location: ' . $this->client->createAuthUrl());
           exit;
       }
   }
   

3. 手动验证过期逻辑
   可通过手动计算过期时间，排查是方法问题还是令牌数据问题：

   $token = $this->client->getAccessToken();
   $expiresAt = $token['created'] + $token['expires_in'];
   echo "当前时间戳: " . time() . "\n";
   echo "令牌过期时间戳: " . $expiresAt . "\n";
   echo "是否过期（含30秒缓冲）: " . (time() >= $expiresAt - 30 ? '是' : '否') . "\n";
   

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