@googleapis/script 模块版本演进全解析：从 0.1.0 到 16.0.1 的变更记录解读

本文围绕 google-api-nodejs-client 仓库中 @googleapis/script 子包自带的 CHANGELOG.md 展开，逐层解读这份变更记录背后的技术脉络：API 同步更新与生成器驱动更新这两类变更的真实含义、Node 最低版本要求从 12 一路升级到 22 的 breaking changes 演进、googleapis-common 依赖的迭代路径，并对照 v1.ts 等源码还原 script API 的资源结构。读完本文，你将能读懂任何一份 Google API 客户端子包的 CHANGELOG，并理解版本号背后对应的代码事实。

CHANGELOG 在仓库中的定位与价值

google-api-nodejs-client 是一个 monorepo 形态的仓库：每一个 Google API 都在 src/apis 下拥有独立子目录，并发布为独立的 npm 包。script 子包对应 Google Apps Script API（"Manages and executes Google Apps Script projects"，见 src/apis/script/README.md），其包名为 @googleapis/script，当前版本为 16.0.1（见 src/apis/script/package.json）。

每个子包目录内都维护一份独立的 CHANGELOG.md，它是该包从最初发布至今全部变更的权威记录。这份文档的价值在于：

• 版本回溯：完整记录了 0.1.0（2021 年）到 16.0.1（2026 年 9 月）共三十余个版本的发布时间与变更内容；
• 升级预警：所有破坏性变更（⚠ BREAKING CHANGES）都被明确标注，是判断"能否直接升级"的第一手依据；
• 变更归因：每条记录都附有对应的 GitHub commit 与 issue 编号，可追踪到具体提交；
• 依赖与运行环境信号：Node 版本要求、googleapis-common 依赖版本的变化都清晰可见，与 package.json 中的 engines、dependencies 字段一一对应。

版本演进全景：从 0.1.0 到 16.0.1 的里程碑

梳理整份 CHANGELOG，可以将演进历程划分为几个阶段：

阶段	版本区间	时间跨度	核心特征
早期迭代	0.1.0 → 0.4.3	2021-03 至 2022-09	0.x 阶段，以 API 同步与基础能力补充为主
独立包稳定期	1.0.0 → 3.2.0	2022-10 至 2024-01	升到 1.0，要求 Node 12，API 持续更新
频繁 breaking 期	4.0.0 → 8.0.1	2024-02 至 2025-08	多次"update the API"带来 breaking changes，升级 Node 18
Node 22 全面迁移	9.0.0 → 16.0.1	2025-09 至 2026-09	全仓库统一迁至 Node 22，生成器高频重跑

值得注意的里程碑：

• 0.3.0（2021-09-14）：随全仓库新增 workload identity federation 认证支持（issue #2517），这是 0.x 阶段少数直接与认证能力相关的功能项；
• 1.0.0（2022-10-28）：由"run the generator"触发，标注为 breaking change——"submodules now require Node 12"，子包首次明确最低 Node 版本要求；
• 6.0.0 / 7.0.0（2025 年中）：升级到 Node 18，同月 8.0.0 的 **script:** update the API 再次声明 breaking changes；
• 12.1.1（2026-09-09）：短暂"add back support for node 18"；
• 13.0.0 / 14.0.0 / 15.0.0 / 16.0.0（2026-09）：连续四个版本围绕 "Update apiary to minimum Node version of 22"（issue #4011 / #4020）展开，最终将最低 Node 版本锁定为 22，这一状态在 package.json 的 "engines": {"node": ">=22.0.0"} 中得到确认。

两类核心变更：API 同步更新与生成器驱动更新

通读 CHANGELOG 会发现，绝大多数条目属于两类重复模式，理解它们能让你一眼读懂任何一条记录。

第一类：**script:** update the API

这是出现频率最高的条目类型，例如：

• 16.0.1（2026-09-23）：**script:** update the API
• 8.0.0（2025-07-08）：**script:** update the API（标注 breaking changes）
• 5.0.0 / 4.0.0（2024-05-02 / 2024-02-02）：**script:** update the API

其含义是：Google 后端 API 的 discovery 文档（REST 描述）发生变化后，客户端通过重新生成代码来同步。这类变更通常意味着请求/响应 schema 或接口定义被刷新。从源码看，仓库根目录的 discovery/script-v1.json 保存了 discovery 文档快照，而 src/apis/script/v1.ts 则是据此生成的 TypeScript 客户端实现（文件头标注 THIS FILE IS AUTO-GENERATED）。

discovery 驱动的更新可能在任何 minor/patch 版本中出现（如 16.0.1 只是 Bug Fixes），但当 API 结构发生变化（如新增/删除字段、改变方法签名）时，版本会直接跳到下一个 major 并标注 breaking changes——这正是 4.0.0、5.0.0、7.0.0、8.0.0 的由来。

第二类：run the generator

另一类高频条目是 run the generator，例如 12.0.0（2026-08-03，issue #3955）、11.0.0（2025-10-15，issue #3814）、10.0.0（2025-09-30，issue #3795）、3.0.0 / 2.0.0（2023，issue #3260）。与"update the API"不同，这类条目往往不针对某个具体 API 的功能变化，而是全仓库性的生成器工具升级或生成策略调整：

• 生成器模板（见 src/generator 目录）本身的改动；
• 全包统一的运行环境升级，如 1.0.0 的 Node 12、6.0.0/7.0.0 的 Node 18、13.0.0–16.0.0 的 Node 22 升级均由生成器统一执行；
• 依赖升级被批量带入，如 upgrade googleapis-common to 8.0.0（issue #3731）出现在 8.0.0、8.0.1、9.0.0 等多个版本的 Bug Fixes 中。

"run the generator"版本同样可能被标记为 breaking changes（3.0.0、2.0.0、13.0.0、15.0.0 均是），原因通常是全包范围内生成产物发生了变化。

Breaking Changes 深度解读：Node 版本要求的演进

这份 CHANGELOG 最值得研究的线索，是 ⚠ BREAKING CHANGES 中 Node 最低版本要求的两次大跃迁。

从 Node 12 到 Node 18

• 1.0.0（2022-10-28）："submodules now require Node 12"，0.x 升级到 1.0.0 的门槛；
• 6.0.0（2025-05-29）与 7.0.0（2025-06-30）："upgrade to node 18"，同月 7.0.0 还叠加了 **script:** update the API 的 breaking changes。

从 Node 18 到 Node 22

2026 年 9 月，全仓库围绕 Node 22 展开了一轮密集的版本操作（issue #4011 / #4020），script 包留下了完整的"试错记录"：

• 12.1.1（2026-09-09）：add back support for node 18——短暂回退；
• 13.0.0 / 14.0.0 / 15.0.0（2026-09-10 前后）：反复声明 "Update apiary to minimum Node version of 22"，伴随 upgrade dependencies in generated packages to Node 22；
• 16.0.0（2026-09-14）："Update apiary to minimum Node version of 22 again - all packages"（issue #4020），全包统一；
• 16.0.1（2026-09-23）：API 同步更新，成为当前版本。

最终落点非常明确：当前 src/apis/script/package.json 声明 "engines": {"node": ">=22.0.0"}。如果你的运行环境是 Node 20 或更早版本，就不能直接安装使用当前版本的 @googleapis/script，需要锁定 12.x 或更早的版本——这就是阅读 CHANGELOG 时最需要关注的信息。

依赖与构建工具链的演进

googleapis-common：从 v5 到 ^9.0.0

@googleapis/script 是薄封装，核心请求逻辑都委托给 googleapis-common 包（在 index.ts 中通过 getAPI、createAPIRequest 等函数复用其实现）。CHANGELOG 记录了它的完整升级路径：

• 2021（0.2.0/0.3.0）：升级至 v5（issue #2497）；
• 2023（3.0.1/3.0.3）：升级至 v7（issue #9491ec1 对应条目）；
• 2025（8.0.0/8.0.1/9.0.0）：升级至 8.0.0（issue #3731），随后出现 8.0.2-rc（7.0.0/6.0.1 的 deps 修复）；
• 当前：package.json 中 googleapis-common 已升级到 ^9.0.0。

这一依赖是客户端底层 HTTP 传输与认证逻辑的承载者，它的升级通常带来内部基础设施改进而非 API 表面变化，因此多出现在 Bug Fixes 或伴随 breaking release 一并发布。

构建工具：webpack 4 → 5

0.3.0（2021-09-14）中记录了一次全仓库性的构建链升级："upgrade webpack from 4 to 5"（issue #2524）。这解释了 package.json 中 webpack / webpack-cli / ts-loader / null-loader 等 devDependencies 与 webpack script 的由来——子包需要支持通过 webpack 进行打包使用（仓库中另有 src/apis/script/webpack.config.js）。

从变更记录反推源码结构：script v1 资源图谱

CHANGELOG 只记录"改了什么"，而 v1.ts 展现了"现在长什么样"。对照阅读，可以还原 @googleapis/script v1 客户端的完整资源结构。

入口与版本分发

index.ts 定义了 VERSIONS 映射和 script() 工厂函数：

export const VERSIONS = {
  v1: script_v1.Script,
};

export function script(version: 'v1'): script_v1.Script;
export function script(options: script_v1.Options): script_v1.Script;
// 内部通过 getAPI<T>('script', versionOrOptions, VERSIONS, this) 完成分发

同时导出 script_v1 命名空间、auth（AuthPlus 实例）以及 googleapis-common 的类型与接口。

顶层 Script 类与五个资源类

v1.ts 中的 Script 类在构造时挂载三个资源对象，而 Projects 下还嵌套两个子资源：

资源类	定义位置	方法	作用
Resource$Processes	v1.ts	list、listScriptProcesses	列出用户或指定脚本的执行进程
Resource$Projects	v1.ts	create、get、getContent、getMetrics、updateContent	脚本项目的创建与元数据/内容/指标管理
Resource$Projects$Deployments	v1.ts	create、delete、get、list、update	部署（deployment）的完整生命周期
Resource$Projects$Versions	v1.ts	create、get、list	版本（不可变快照）管理
Resource$Scripts	v1.ts	run	通过 Apps Script API 执行脚本函数

核心方法示例：scripts.run

run 是 @googleapis/script 最常用的方法（定义于 v1.ts），对应 POST /v1/scripts/{scriptId}:run。源码中的示例注释给出了标准调用范式：

const {google} = require('googleapis');
const script = google.script('v1');

async function main() {
  const auth = new google.auth.GoogleAuth({
    scopes: [
      'https://www.googleapis.com/auth/drive',
      'https://www.googleapis.com/auth/spreadsheets',
      // ... 根据脚本实际使用的服务追加 scope
    ],
  });
  const authClient = await auth.getClient();
  google.options({auth: authClient});

  const res = await script.scripts.run({
    scriptId: 'PLACEHOLDER_SCRIPT_ID', // 部署 ID 或脚本 ID
    requestBody: {
      function: 'myFunction',   // 函数名，不含括号与参数
      parameters: ['arg1', 42], // 仅限 string/number/array/object/boolean 等原始类型
      devMode: false,           // true 时按最近保存版本执行（需为脚本所有者）
    },
  });
  console.log(res.data);
}

返回体是 Schema$Operation（见 v1.ts），其 done 字段为 false 表示执行尚未完成；执行成功时 response 内含返回值，脚本抛异常时 error.details 中携带单个 ExecutionError 对象（v1.ts），包含 errorMessage、errorType 与堆栈元素列表。

其他资源方法也遵循同一模式，例如 processes.list（v1.ts）支持 pageSize（默认 50）、pageToken 以及 userProcessFilter.* 系列过滤参数；projects.versions.create（v1.ts）用于对当前代码生成不可变版本，为后续部署提供 versionNumber。

版本节奏与发布机制

从 CHANGELOG 可以清晰观察到仓库的发布机制：

• 语义化版本：update the API 或 run the generator 若改变 API 表面或运行环境要求，则 bump major（如 4.0.0、8.0.0、16.0.0）；仅修复或小幅同步则 bump minor/patch（如 16.0.1、12.1.0）；
• release-please 驱动：仓库根目录存在 release-please-config.json，每个子包的 CHANGELOG 均由该工具自动维护，这解释了为何所有条目都带有 commit hash 与 PR/issue 链接、为何格式高度统一；
• 全仓库联动：Node 版本、googleapis-common 依赖等属于全局性变更，会在同一时间段内出现在所有子包的 CHANGELOG 中，script 包的 13.0.0–16.0.0 密集发布即是例证。

如何高效使用这份 CHANGELOG

面对一份结构化的变更记录，建议按以下路径使用：

1. 先看最近的 major 版本：任何 ⚠ BREAKING CHANGES 都是升级前必须评估的项——对 script 包来说，当前重点是 Node 22 要求；
2. 对照 engines 字段确认运行环境：以 src/apis/script/package.json 为准，Node 版本不满足时锁定旧版本；
3. 区分两类变更：**script:** update the API 关注 API 表面变化，run the generator 更多是生成策略与全局升级；
4. 结合源码验证：方法签名、schema 字段的最终形态以 v1.ts 为准，CHANGELOG 只提供变更线索；
5. 追溯提交：通过条目附带的 commit hash 与 issue 编号，可以在仓库提交历史中找到对应的完整 diff。

理解这份 CHANGELOG，也就理解了 @googleapis/script 乃至整个 google-api-nodejs-client 生态的演进逻辑：API 变化由 discovery 文档驱动、工具链与运行环境由生成器统一推进，而语义化版本与自动化的发布流水线，则把这一切变化以可追溯、可评估的方式交付给开发者。