Ionic+Capacitor v3集成GoogleAuth报ReferenceError: gapi is not defined求助

报错根因 #

ReferenceError: gapi is not defined 出现的核心原因是@codetrix-studio/capacitor-google-auth插件依赖的谷歌浏览器端授权SDK（gapi）未正确加载，或插件未完成初始化就被调用。你可以按照以下步骤逐一排查修复： #

1. 补充插件全局初始化逻辑 #

绝大多数该报错都是遗漏了初始化步骤导致，插件的initialize方法会自动加载gapi SDK，必须在应用启动时优先调用。
以Angular为例，在app.component.ts中添加初始化代码：

import { GoogleAuth } from '@codetrix-studio/capacitor-google-auth';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
})
export class AppComponent {
  constructor() {
    // 新增此行初始化代码
    GoogleAuth.initialize();
  }
}

2. 检查Capacitor配置正确性 #

打开项目根目录的capacitor.config.json（或.ts格式配置文件），确认已添加GoogleAuth的配置项，且serverClientId填写的是GCP控制台申请的Web类型客户端ID，不要填安卓客户端ID：

{
  "plugins": {
    "GoogleAuth": {
      "scopes": ["profile", "email"],
      "serverClientId": "你的GCP Web客户端ID",
      "forceCodeForRefreshToken": true
    }
  }
}

3. 版本兼容性检查 #

确认插件版本和Capacitor版本匹配：

• Capacitor v3必须配套使用3.x版本的@codetrix-studio/capacitor-google-auth，4.x及以上版本仅适配Capacitor v4/v5，会出现兼容性问题。
  可执行以下命令安装对应版本：

  npm install @codetrix-studio/capacitor-google-auth@3
  

4. 安卓端补充检查 #

• 确认已将GCP控制台下载的google-services.json放到安卓项目的app/目录下
• 确认GCP控制台申请安卓客户端ID时，填写的包名和项目build.gradle中的applicationId完全一致，签名SHA1指纹配置正确
• 每次修改配置后必须执行npx cap sync android同步配置到安卓项目

5. 特殊场景修复 #

如果是浏览器调试时出现该报错：

• 需保证网络可以正常访问谷歌服务，国内网络无法加载gapi SDK会触发该报错
• 可手动在index.html的<head>标签中添加gapi SDK的直接引用，避免自动加载失败：

  <script src="https://apis.google.com/js/api.js"></script>
  <script src="https://accounts.google.com/gsi/client"></script>
  

如果是国内安卓真机调试，需确认设备安装了谷歌服务框架（GMS），否则无法完成谷歌授权流程。

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