• 后端

导读

本文以 google-api-nodejs-client 仓库中 src/apis/airquality/CHANGELOG.md 为主体，系统梳理 Air Quality API 官方 Node.js 客户端包@googleapis/airquality从 2024 年首发 0.1.0 到 2026 年 9.0.1 的完整版本演进历程，并结合仓库内的 v1.ts、package.json 与 discovery/airquality-v1.json 等源码佐证，深入解读每次大版本升级背后的原因：API 文档更新、代码生成器重跑、Node 运行时版本门槛提升与底层依赖googleapis-common升级。读完本文，你将掌握该包的版本脉络、每个版本号对应的实际变更内容，以及如何依据 CHANGELOG 判断升级风险并规划自己的使用版本。

一、@googleapis/airquality 是什么

@googleapis/airquality是 Google Air Quality API 的官方 Node.js 客户端，随 google-api-nodejs-client 仓库按 API 拆分独立发布。它在仓库中的入口文件为 src/apis/airquality/index.ts，对外暴露airquality_v1命名空间、auth认证对象以及主函数airquality(versionOrOptions)，底层通过googleapis-common的getAPI完成实例化。

从 src/apis/airquality/v1.ts 的源码结构看，Airquality类挂载了四个资源：

这四项能力直接对应发现文档 discovery/airquality-v1.json 中的resources定义，服务的baseUrl为https://airquality.googleapis.com/，全部请求都要求https://www.googleapis.com/auth/cloud-platform这一 OAuth 2.0 scope。独立安装方式见 src/apis/airquality/README.md：

npm install @googleapis/airquality

若使用聚合包则直接npm install googleapis，然后通过const airquality = google.airquality('v1')获取客户端实例。

二、版本演进全景：从首发到 9.0.1

CHANGELOG 记录了从 2024-07-26 的0.1.0到 2026-09-23 的9.0.1共 17 个版本。将全部条目按类型归纳，可以发现该包的变更始终围绕四条主线：

1. API 更新（update the API）：重新拉取 Google Air Quality API 的发现文档并重新生成客户端代码，通常属于小版本或补丁级变更；
2. 运行生成器（run the generator）：仓库层面的全量代码生成动作，通常会带来 Breaking Changes；
3. Node 运行时版本门槛：从 node 18 起步，历经提升到 node 22、暂时回退支持 node 18、再提升到 node 22 的反复；
4. 底层依赖升级：googleapis-common从 8.0.0 一路升级到 9.0.0。

各版本号与对应变更速览如下：

三、四大变更主线逐一拆解

3.1 API 更新：update the API意味着什么

CHANGELOG 中反复出现的**airquality:** update the API是出现频率最高的一类变更，共 7 次（0.1.0、0.1.1、2.0.0、2.0.1、4.0.1、9.0.1 等）。这代表 Google 侧更新了 Air Quality API 的发现文档（discovery document），仓库随后重新生成对应客户端代码。本仓库的发现文档即 discovery/airquality-v1.json，其revision字段为20240901，代码生成产物则对应 src/apis/airquality/v1.ts。

这类更新通常不改变方法签名，但可能调整请求/响应字段、枚举值或描述文本。例如发现文档中extraComputations的枚举就同时出现在三个请求模型中（LookupCurrentConditionsRequest、LookupForecastRequest、LookupHistoryRequest），服务端若新增枚举值，就需要通过update the API同步到客户端。因此，在 API 更新发布后升级依赖，是确保客户端与服务端字段对齐的推荐做法。

3.2run the generator：为什么总会伴随 Breaking Changes

run the generator出现于 5.0.0、5.1.0、8.0.0 等版本，且在 5.0.0、6.0.0、8.0.0 中明确标注This release has breaking changes。从仓库结构看，代码生成器位于 src/generator，它读取 discovery 文档并产出v1.ts这类类型化客户端。每当生成器自身的模板、依赖或输出格式升级（例如接口定义变化、参数类型收紧），重跑生成就会批量影响所有 API 包，从而构成 Breaking Changes。

这也解释了 CHANGELOG 中多版本同一天扎堆发布的现象：例如 2026-09-09 同时发布 5.1.1 与 6.0.0，2026-09-10 同时发布 7.0.0 与 8.0.0——这是全仓库统一重新生成与统一发布的结果，而非单个包独有。

3.3 Node 运行时门槛：node 18 与 node 22 的拉锯

Node 版本要求是本包演进中最具破坏性也最值得关注的变更线：

• 1.0.0（2025-05-29）与 2.0.0（2025-06-30）：upgrade to node 18，将最低运行时提升到 Node 18，标注为 Breaking Changes；
• 5.1.0（2026-09-02）：开始将生成包依赖升级到 Node 22；
• 5.1.1（2026-09-09）：add back support for node 18，临时回补 Node 18 兼容；
• 6.0.0 / 7.0.0 / 8.0.0（2026-09-09~10）：Update apiary to minimum Node version of 22成为正式门槛，同时 6.0.0、8.0.0 再次add back support for node 18；
• 9.0.0（2026-09-14）：表述为Update apiary to minimum Node version of 22 again - all packages，其中 "again" 表明这是对 Node 22 门槛的再次确认，且作用于全部包。

这一反复的最终落点可以直接在 src/apis/airquality/package.json 中得到验证：当前 9.0.1 版本的engines.node为">=22.0.0"。对使用者的实际影响是：若你的运行环境停留在 Node 18，应谨慎升级到 5.1.1 之后的 6.x 版本；若已使用 Node 22，则可以放心跟进最新版本。

3.4 底层依赖：googleapis-common的升级轨迹

CHANGELOG 中另一条清晰的线索是googleapis-common的版本推进：

• 1.0.1（2025-06-04）与 2.0.0（2025-06-30）：upgrade googleapis-common to 8.0.2-rc（预发布候选版）；
• 2.0.2（2025-08-07）与 3.0.0（2025-09-16）：upgrade googleapis-common to 8.0.0（正式版）；
• 3.0.0 起依赖正式稳定在 8.0.0。

当前 src/apis/airquality/package.json 中googleapis-common的声明为^9.0.0，说明 9.x 系列已将底层公共框架推进到了新的主版本。googleapis-common提供getAPI、createAPIRequest、AuthPlus等核心基础设施（见 src/apis/airquality/index.ts 的导入），它的主版本升级意味着请求执行链路、认证体系或类型定义存在不兼容变更，这也是各版本标注 Breaking Changes 的常见来源之一。

四、从源码验证版本与能力的关系

4.1 版本号与 package.json 的一致性

CHANGELOG 最新条目 9.0.1 与 src/apis/airquality/package.json 中的"version": "9.0.1"完全对应，二者共同确认当前发布状态。该包随主仓库按 release-please 流程（见 release-please-config.json）自动生成 CHANGELOG 与版本号，因此每次合并到主干的 PR 都会同步反映在这里。

4.2 API 能力在 9.x 中的稳定形态

无论版本如何迭代，客户端暴露的调用形态始终保持稳定。以 v1.ts 为例，currentConditions.lookup的典型调用为：

const {google} = require('googleapis'); const airquality = google.airquality('v1'); const auth = new google.auth.GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'], }); const authClient = await auth.getClient(); google.options({auth: authClient}); const res = await airquality.currentConditions.lookup({ requestBody: { location: {latitude: 31.2304, longitude: 121.4737}, universalAqi: true, extraComputations: ['LOCAL_AQI', 'HEALTH_RECOMMENDATIONS'], languageCode: 'zh-CN', }, }); console.log(res.data);

响应结构对应 LookupCurrentConditionsResponse：dateTime、regionCode、indexes、pollutants、healthRecommendations。热力图瓦片接口则通过airquality.mapTypes.heatmapTiles.lookupHeatmapTile调用，需传mapType（枚举含UAQI_RED_GREEN、US_AQI、GBR_DEFRA等 9 种，见 discovery/airquality-v1.json#L190-L217）、zoom（0–16）、x、y四个路径参数，返回HttpBody形式的 PNG 字节数据。这些能力自 0.1.0 首发以来即存在，CHANGELOG 中的历次 API 更新只是对其字段与枚举的增量修正。

4.3 跨版本升级的注意要点

综合 CHANGELOG 与源码，升级时建议关注三点：

1. 运行时环境：9.x 要求 Node >= 22（见 package.json），升级前先确认部署环境的 Node 版本；
2. 破坏性变更来源：标注⚠ BREAKING CHANGES的版本集中在两类——Node 版本门槛提升（1.0.0、2.0.0、6.0.0、7.0.0、8.0.0、9.0.0）与全仓库重新生成（3.0.0、4.0.0、5.0.0、6.0.0、8.0.0），后者建议先阅读对应版本的run the generator提交说明；
3. 与聚合包的关系：如果使用googleapis聚合包，@googleapis/airquality的版本演进是聚合包整体节奏的一部分，Node 22 门槛同样适用于整个聚合包（9.0.0 中 "all packages" 的表述即指此）。

五、如何持续跟进该包的变更

• 直接阅读 src/apis/airquality/CHANGELOG.md，每次发布都会追加新条目，条目按[主版本.次版本.修订号]组织，并附带对应比较链接与提交哈希；
• 关注⚠ BREAKING CHANGES段与Bug Fixes段，前者决定升级的必要评估，后者中的update the API建议尽快跟进以保持字段对齐；
• 若需了解 API 服务端能力的完整定义（字段、枚举、默认值、范围约束），以 discovery/airquality-v1.json 为权威来源；若需了解客户端调用形态，以 src/apis/airquality/v1.ts 中带示例代码的方法注释为准。

结语

@googleapis/airquality的 17 个版本浓缩了 Google 官方 Node.js 客户端生态的典型演进模式：API 侧持续更新、生成器定期重跑、运行时门槛逐步抬高、底层公共库迭代升级。理解 CHANGELOG 背后这四条主线，你就能在读任何 Google API 客户端包的变更日志时快速判断：哪次升级可以无脑跟进，哪次升级必须评估运行环境，哪次升级需要回归测试请求参数。对于 Air Quality 相关项目，当前最稳妥的选择是运行在 Node 22 环境并采用最新 9.0.1 版本。

• 后端