企业官网建设流程全解析

google-api-nodejs-client 的 @googleapis/oauth2：3 个端点搞定令牌校验与用户信息查询

【免费下载链接】google-api-nodejs-clientGoogle's officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址: https://gitcode.com/gh_mirrors/go/google-api-nodejs-client

google-api-nodejs-client里的@googleapis/oauth2是一个被标记为废弃、但至今仍在生效的授权辅助模块。它只做一件事：帮你校验一张 OAuth2 令牌是否有效，并顺手查出当前登录用户的邮箱、姓名等基础资料。对于仍在维护传统授权链路的存量项目，这套tokeninfo加userinfo的轻量调用链路，比直接解析 JWT 更省心，也是本文要讲透的全部内容。

什么场景下你还会用到这个模块

src/apis/oauth2/目录承载的是 Google OAuth2 API（版本v2），发现文档 discovery/oauth2-v2.json 里的revision还停在20200213，README 也挂着[Deprecated]前缀——官方早已不为它增加新功能。

但这不意味着它不能用。两个真实场景仍然会踩到它：

• 你手里有一张access_token或id_token，想在业务代码里快速判断它是否过期、授权范围够不够，不想自己解码、验签；
• 你要展示"当前用户是谁"，需要邮箱、姓名、头像这些公开资料，而不想引入整套 People API。

只要落在这两类需求里，@googleapis/oauth2仍然是最短路径。

最小可用调用：3 行代码查一个用户

先把能跑起来的最小例子放在前面，方便你直接照抄。安装聚合包后，用统一入口拿到v2实例，再调userinfo.get：

const {google} = require('googleapis'); const oauth2 = google.oauth2('v2'); const res = await oauth2.userinfo.get({}); console.log(res.data); // { email, name, picture, ... }

这段在做什么：google.oauth2('v2')通过VERSIONS表拿到Oauth2实例，userinfo.get({})以 GET 方式请求https://www.googleapis.com/oauth2/v2/userinfo，返回体直接落在res.data里。注意它没有任何必填参数——身份完全来自全局绑定的认证客户端，下一节讲怎么绑。

两种引入方式与包信息

除了聚合包googleapis，还可以装独立子包，它由src/apis/oauth2生成并单独发布：

npm install @googleapis/oauth2

独立包与聚合包指向同一份实现，二选一即可。从 src/apis/oauth2/package.json 能确认这个子包的关键信息：

走聚合包时，工厂函数与主包导出是这么接起来的：src/apis/oauth2/index.ts 里的oauth2()调用getAPI<T>('oauth2', versionOrOptions, VERSIONS, this)，其中VERSIONS把字符串'v2'绑定到oauth2_v2.Oauth2类；主入口 src/index.ts 再把oauth2_v2从包里导出，于是你在代码里能直接写出google.oauth2('v2')。

三个端点各管一件事

这个模块对外就暴露三处方法，都挂在同一个Oauth2实例上：

• tokeninfo：校验令牌。POST https://www.googleapis.com/oauth2/v2/tokeninfo，用于验证access_token或id_token并回传元信息。
• oauth2.userinfo.get：拉当前用户资料。GET https://www.googleapis.com/oauth2/v2/userinfo。
• oauth2.userinfo.v2.me.get：同一资料的旧端点。GET https://www.googleapis.com/userinfo/v2/me，是历史遗留的userinfo/v2/me路径，返回结构与上一项完全一致。

资源挂载结构决定了调用路径：Oauth2构造时先挂userinfo资源，Resource$Userinfo内部再级联出v2.me子资源，最终拼出userinfo.get与userinfo.v2.me.get两条链。三个方法在 src/apis/oauth2/v2.ts 中都是同一套createAPIRequest骨架，差别只在url、method与返回的 Schema。

调用前：Scope 与全局认证怎么配

调userinfo之前，必须给认证客户端配好对应 Scope。整个 API 只涉及这三个（见发现文档auth.oauth2.scopes与两个userinfo方法的scopes数组）：

配置方式有两种，二选一：

const auth = new google.auth.GoogleAuth({ // 可传数组，也可传一个空格分隔的字符串 scopes: [ 'openid', 'https://www.googleapis.com/auth/userinfo.email', 'https://www.googleapis.com/auth/userinfo.profile', ], }); const authClient = await auth.getClient(); google.options({auth: authClient}); // 绑定全局，后续调用自动携带令牌

这段在做什么：GoogleAuth拿到客户端后，用google.options({auth: authClient})做全局绑定，之后oauth2的所有请求都自动带上访问令牌，无需在每个调用里重复传认证信息。scopes既可写成数组，也可写成单个空格分隔字符串，这点在源码注释里已明确。

调用时：标准参数与请求选项

无论调哪个方法，都会自动支持一组标准参数（定义在 v2.ts 的StandardParameters接口，与发现文档parameters段对齐）：

• auth：本请求用的认证客户端或 API Key，支持OAuth2Client、JWT、Compute、UserRefreshClient、BaseExternalAccountClient、GoogleAuth及字符串形式；
• alt：响应数据格式，默认json；
• fields：部分响应字段选择器，只取你要的字段；
• key：API Key，用于标识项目与计入配额，未提供 OAuth 2.0 token 时为必填；
• oauth_token：当前用户的 OAuth 2.0 token；
• prettyPrint：是否返回带缩进换行的响应，默认true；
• quotaUser：配额统计用的不透明用户标识，最长 40 字符；
• userIp：已废弃，请改用quotaUser。

几个容易忽略的点：

1. rootUrl默认取options.rootUrl || 'https://www.googleapis.com/'，因此你可以在请求选项里覆盖rootUrl，把请求打到自己或代理的域名上；
2. 每个方法都支持 Promise 与 callback 两种风格，返回类型分别是Promise<GaxiosResponseWithHTTP2<Schema$Userinfo>>与void；
3. 传入StreamMethodOptions时，方法返回流式响应Readable而非普通对象，适合处理大体积返回或做管道转发。

tokeninfo的参数只有两个且都不是必填，需至少提供其一：

const res = await oauth2.tokeninfo({ access_token: 'your-access-token', // 校验访问令牌 // id_token: 'your-id-token', // 或校验 ID 令牌 });

服务端根据你传入的令牌类型回传对应信息，具体字段见下一节。

响应怎么读：Tokeninfo 与 Userinfo 字段

tokeninfo返回Schema$Tokeninfo：

两个userinfo端点返回同一个Schema$Userinfo：

授权码流程：从换令牌到调接口

tokeninfo/userinfo本身只是"校验与查询"，而拿到那张贴身的access_token，通常靠google.auth.OAuth2客户端驱动。仓库里的 samples/oauth2.js 给出了完整参考，核心三步：

1. 用CLIENT_ID、CLIENT_SECRET、REDIRECT_URI三要素（来自 Cloud Console 凭据页）构造google.auth.OAuth2客户端，并google.options({auth: oauth2Client})做全局绑定；
2. generateAuthUrl({access_type: 'offline', scope: scopes.join(' ')})生成授权地址，在本地启动 HTTP 服务接收回调里的code；
3. 拿到code后调getToken(code)换令牌，把结果写回oauth2Client.credentials，此后客户端即可自动带令牌发请求。

示例里最终演示的是people.people.get——用它证明"授权完成后就能访问其他 Google API"，正好呼应这个模块"为其他 Google API 获取授权许可"的定位。授权逻辑本身即上述三步，People 调用属于示例演示范畴。

弃用状态、引擎要求与现代替代方案

上手前先把这几条注意事项记牢：

• 官方已弃用：README 明确标注[Deprecated]，发现文档revision停留在20200213，Google 不再为其加新功能。新项目应优先转向 Google Identity 平台的现代方案（如直接解析/验证 ID token、或对接更新的 Identity API），而不是把@googleapis/oauth2当作新的授权地基。
• 运行环境要求抬高：src/apis/oauth2/CHANGELOG.md 显示 2026 年起最低 Node 版本提升至22，package.json里engines.node已写死>= 22.0.0。确认你的运行环境达标，否则安装/构建会出问题。
• 存量项目可继续用：该模块仍随主仓库持续发布与维护，tokeninfo与userinfo方法本身不受影响，作为传统授权链路的兼容实现保留没有问题。
• 配额与 Key：key参数在没走 OAuth token 时是必填的，配合quotaUser做配额归因；别再用已废弃的userIp。

简言之：这是一个"老但仍有效"的工具——校验令牌、查用户资料这两件事它做得干脆利落，但别拿它去搭建全新的授权体系。

【免费下载链接】google-api-nodejs-clientGoogle's officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址: https://gitcode.com/gh_mirrors/go/google-api-nodejs-client