Gmail API邮箱地址认证失败，请求问题排查帮助

以下是逐步缩小故障范围的实用方法：

1. 验证授权码的有效性 #

• 授权码仅能使用一次，且有效期约10分钟。重复使用过期/已用过的授权码必然触发该错误，请通过隐私模式打开授权链接，重新完成账号授权流程生成全新授权码后再测试。
• 检查日志中记录的授权码是否完整：确认$_GET['code']获取到的内容没有被URL截断、转义或丢失字符。

2. 严格匹配Redirect URI #

谷歌OAuth要求回调URI必须与Google Cloud控制台中配置的完全一致，包括：

• HTTP/HTTPS协议（控制台是HTTPS，脚本里不能写HTTP）
• 完整路径（比如控制台配置的是https://your-domain.com/callback.php，脚本里不能省略.php或修改路径）
• 大小写（路径中的字母大小写必须完全匹配）
• 端口号（如果使用非标准端口，必须包含在URI中）
  逐字符对比控制台配置和脚本中的$redirect_uri，确保无任何差异。

3. 确认客户端凭证正确性 #

• 重新从Google Cloud控制台复制client_id和client_secret，避免复制时带入多余空格、换行或隐形字符。
• 检查脚本中凭证变量是否被正确赋值，无拼写错误（比如把client_secret写成client_secrect）。

4. 验证测试用户配置 #

• 确认用于授权的谷歌账号已添加到OAuth consent screen的测试用户列表中。
• 项目处于测试模式时，仅测试用户能完成授权流程，使用非测试用户账号会导致授权码无效。

5. 检查请求参数与格式 #

• 确认POST参数中的grant_type值为authorization_code，无拼写错误。
• 打印$post_data变量，检查所有参数（code、client_id、client_secret、redirect_uri、grant_type）是否都存在且值正确，无缺失或错误编码。

6. 排查服务器环境问题 #

• 网络连通性：在服务器命令行执行以下curl命令，直接测试token交换，看是否返回更详细的错误：

  curl -X POST https://oauth2.googleapis.com/token -d "code=YOUR_NEW_AUTH_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=YOUR_REDIRECT_URI&grant_type=authorization_code"
  

• 系统时间同步：OAuth对时间敏感，服务器系统时间与标准时间差过大（超过5分钟）会导致token验证失败，需同步服务器时间。
• SSL证书：确保服务器能正常验证谷歌的SSL证书，可尝试添加curl选项curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);（仅用于测试，生产环境不建议），若问题解决则需修复服务器SSL证书配置。

7. 开启curl Verbose模式排查请求细节 #

在脚本中添加curl Verbose配置，查看完整的请求和响应细节，定位参数或请求头问题：

// 在curl_init后添加以下代码
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verbose_log = fopen('php://temp', 'w+');
curl_setopt($ch, CURLOPT_STDERR, $verbose_log);

// 执行curl请求后，打印verbose日志
rewind($verbose_log);
echo "Verbose Log:\n" . stream_get_contents($verbose_log);
fclose($verbose_log);

通过日志可确认请求方法、Content-Type头、发送的参数是否符合谷歌要求。

8. 确保获取Refresh Token #

若需要获取refresh_token，必须在授权请求URL中添加两个参数：

• access_type=offline：告知谷歌需要离线访问权限
• prompt=consent：强制用户重新授权，确保每次都返回refresh_token（即使之前授权过）
  完整的授权URL示例：

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=https://www.googleapis.com/auth/gmail.modify&access_type=offline&response_type=code&prompt=consent

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