PHPMailer结合Google OAuth2发送邮件认证失败问题求助

核心前提说明 #

Google 已经彻底停用了低安全性应用访问权限，哪怕你手动开启这个选项也无效，别再在这上面浪费时间，重点聚焦 OAuth2 配置本身。

排查步骤与修复方案 #

1. 核对 Google Cloud 平台 OAuth2 基础配置 #

• 先确认在 Google Cloud Console 里创建了项目，并且启用了 Gmail API（没启用的话直接无法调用）
• 客户端 ID 类型要选对：
  • 本地测试选「桌面应用」，不需要配置回调地址，流程更简单
  • 线上环境选「Web 应用」，必须把 oauth2callback.php 的完整 URL（比如 https://你的域名.com/oauth2callback.php）添加到「已授权的重定向 URI」里
• 检查 client_id、client_secret 有没有拼写错误，复制的时候别多空格或者漏字符

2. 检查代码集成逻辑 #

主程序代码常见坑点：

• 必须用 PHPMailer 自带的 OAuth 类处理认证，别自己手动拼 token
• 一定要保存 refresh_token：access_token 只有1小时有效期，后续全靠 refresh_token 自动续期，首次授权才会返回这个值，丢了就得重新授权
• 正确的集成示例：

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\OAuth;
use League\OAuth2\Client\Provider\Google;

$mail = new PHPMailer(true);
try {
    $mail->isSMTP();
    $mail->Host = 'smtp.gmail.com';
    $mail->SMTPAuth = true;
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
    $mail->Port = 587;
    $mail->AuthType = 'XOAUTH2';

    // 替换成你的实际配置
    $clientId = '你的客户端ID';
    $clientSecret = '你的客户端密钥';
    $refreshToken = '首次授权拿到的refresh_token';
    $email = '你的Gmail邮箱';

    $provider = new Google([
        'clientId' => $clientId,
        'clientSecret' => $clientSecret,
    ]);

    $mail->setOAuth(
        new OAuth([
            'provider' => $provider,
            'clientId' => $clientId,
            'clientSecret' => $clientSecret,
            'refreshToken' => $refreshToken,
            'userName' => $email,
        ])
    );

    $mail->setFrom($email, '发件人名称');
    $mail->addAddress('收件人邮箱');
    $mail->Subject = 'OAuth2 测试邮件';
    $mail->Body = '测试内容';

    $mail->send();
    echo '邮件发送成功';
} catch (Exception $e) {
    echo "发送失败: {$mail->ErrorInfo}";
}

oauth2callback.php 关键检查点：

• 授权范围必须包含 https://mail.google.com/ 或 https://www.googleapis.com/auth/gmail.send，没这个权限拿到 token 也发不了邮件
• 要把拿到的 refresh_token 存到数据库或者配置文件里，别只打印出来就完事
• 示例回调逻辑：

use League\OAuth2\Client\Provider\Google;

session_start();
$clientId = '你的客户端ID';
$clientSecret = '你的客户端密钥';
$redirectUri = '回调页面的完整URL';

$provider = new Google([
    'clientId' => $clientId,
    'clientSecret' => $clientSecret,
    'redirectUri' => $redirectUri,
]);

if (!isset($_GET['code'])) {
    $options = [
        'scope' => [
            'https://mail.google.com/', // 全邮箱权限，或者选gmail.send
        ]
    ];
    $authUrl = $provider->getAuthorizationUrl($options);
    $_SESSION['oauth2state'] = $provider->getState();
    header('Location: ' . $authUrl);
    exit;
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {
    unset($_SESSION['oauth2state']);
    exit('状态验证失败');
} else {
    $token = $provider->getAccessToken('authorization_code', [
        'code' => $_GET['code']
    ]);
    // 把这个refresh_token存起来，后续发邮件要用
    echo 'Refresh Token: ' . $token->getRefreshToken();
}

3. 权限重置（如果之前授权过） #

如果之前授权时没申请正确的权限，需要先在 Google 账户里移除应用授权：

• 打开 Google 账户 -> 安全 -> 第三方应用访问 -> 找到你的应用并删除
• 然后重新走一遍授权流程，确保这次申请了正确的权限范围

4. 服务器环境检查 #

• 确认 PHP 7.4 安装了 curl 和 openssl 扩展，这俩是 OAuth2 认证和 SMTP 加密必需的
• 检查服务器能不能访问 Google 的 OAuth2 端点（https://accounts.google.com/o/oauth2/token）和 SMTP 服务器，避免防火墙或代理拦截
• 如果是 Google Workspace 企业账户，要确认管理员允许第三方应用访问邮箱

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