企业官网建设流程全解析

• 后端

src/apis/merchantapi/CHANGELOG.md记录了 Google Merchant Center API 的 Node.js 客户端子包@googleapis/merchantapi自 2024 年 7 月发布 0.1.0 以来两年间的完整版本历史。这份文档不仅是发布流水账，更承载着关键的破坏性变更（Node 运行时版本提升、googleapis-common依赖升级、服务端 API 结构调整）与维护策略信息。本文以该 CHANGELOG 为主体，结合仓库中 package.json、index.ts 与各版本 TypeScript 源码，帮你快速定位每次升级的风险点、确认当前运行环境是否满足要求，并读懂 Google 官方对 merchantapi 子包"维护模式"的定位。

一、版本脉络总览：两年 40+ 次发布的节奏与规律

对照 CHANGELOG 可梳理出@googleapis/merchantapi的完整发布轨迹（时间按发行顺序排列）：

两个值得注意的现象：

1. CHANGELOG 内版本顺序并非严格按发布时间排列。例如 12.0.0（2025-09-16）在文件里位于 8.0.0（2025-08-29）之前，而 11.0.0（2025-08-04）又排在 1.0.0（2025-08-07）之后。这是 release-please 自动生成 CHANGELOG 时的分组/排序行为，阅读时建议以"发布日期"列为准。
2. 破坏性变更集中在两个维度：服务端 API 定义变化（表现为update the API并触发 BREAKING 标记）与运行时/依赖约束变化（Node 版本、googleapis-common版本）。

二、破坏性变更深度解读：Node 版本门槛的两次跃迁

这是 CHANGELOG 中最值得升级前关注的部分，因为它是环境级约束，直接影响 CI 与部署流水线。

2.1 第一次跃迁：Node 18（2025 年 5 月）

• 6.0.0（2025-05-29）首次标记upgrade to node 18，并在 7.0.0（2025-06-30）以682fbb8落地。
• 这意味着 Node 16 及以下环境在升级到 6.0.0+ 时即被官方排除。

2.2 第二次跃迁：Node 22（2026 年 9 月）

• 21.1.0 先做了依赖侧准备（upgrade dependencies in generated packages to Node 22），随后 21.1.1 一度"add back support for node 18"作为临时回退。
• 22.0.0 / 23.0.0 / 24.0.0（2026-09-09～10）正式将最低版本提升至 Node 22，对应 issue #4011。
• 25.0.0（2026-09-14）再次重申：Update apiary to minimum Node version of 22 again - all packages（#4020），说明这是一次覆盖所有子包的统一行动，而不是 merchantapi 单个包的独立决定。

2.3 如何核对当前环境的 Node 版本要求

升级到 25.x 后，可直接查看 src/apis/merchantapi/package.json 中的声明：

{ "name": "@googleapis/merchantapi", "version": "25.2.1", "engines": { "node": ">=22.0.0" } }

仓库当前状态与 CHANGELOG 顶部版本（25.2.1）完全一致：engines.node为>=22.0.0。升级前提：本机或容器镜像中的 Node 主版本必须 ≥ 22，否则应在升级前先完成 Node 运行时迁移。

三、依赖链演进：googleapis-common 的三次升级

merchantapi 的所有生成代码都构建在googleapis-common之上（createAPIRequest、AuthPlus、GoogleConfigurable等均来自该包）。CHANGELOG 记录了它的三次关键变动：

当前仓库 src/apis/merchantapi/package.json 中依赖声明为"googleapis-common": "^9.0.0"，说明在 CHANGELOG 记录的 8.0.x 之后，官方又推进到了 9.x 大版本。由于这是共享底层库，升级 merchantapi 时若同时升级 googleapis-common，应整体回归验证：认证客户端（OAuth2/JWT/Compute）初始化、请求拦截器与错误处理行为都可能受其影响。

四、从 CHANGELOG 反推发布机制：生成器驱动的自动化流水线

CHANGELOG 中大量条目标注为run the generator（#3716、#3721、#3769、#3795、#3814、#3831、#3861、#3920、#3955、#3992）或regenerate index files。从源码结构可以还原这套机制的产物：

1. Discovery 文档：仓库 discovery 目录存放了 26 份 merchantapi 的 JSON 描述文件（如 merchantapi-accounts_v1.json、merchantapi-products_v1.json、merchantapi-reports_v1.json），每个文件对应一个 API 版本；
2. 生成代码：src/apis/merchantapi 下的accounts_v1.ts、products_v1.ts等 26 个 TypeScript 文件由生成器产出（文件头明确标注THIS FILE IS AUTO-GENERATED），"run the generator" 即指重新拉取 Discovery 文档并重跑生成；
3. 索引文件：index.ts 中的VERSIONS对象将 26 个版本逐一注册，merchantapi()工厂函数通过getAPI('merchantapi', versionOrOptions, VERSIONS, this)按版本号返回对应的Merchantapi类实例，同时导出AuthPlus与全部 26 个版本命名空间；
4. 发布配置：release-please-config.json 中"src/apis/merchantapi": {}表明该目录是一个独立的 release-please 发布单元，这就是 CHANGELOG 中"独立版本号 + 独立 compare 链接"的来源。

因此，当 CHANGELOG 出现**merchantapi:** update the API时，实质是上游 Merchant API 的 Discovery 文档发生变更后生成的代码被同步更新。这类变更虽然多数是新增字段/方法，但 Google 服务端也可能重命名参数或调整响应结构，因此被标记为 BREAKING—— 升级后建议对涉及的具体 API 调用做一次契约级回归（例如用createAPIRequest响应中的 Schema 类型做编译期校验）。

五、典型方法级佐证：以 products_v1 为例

要验证某次update the API具体带来了什么，可直接阅读对应版本的生成源码。以 products_v1.ts 为例：

• accounts.products.list的请求 URL 为{rootUrl}/products/v1/{+parent}/products，方法为 GET，requiredParams: ['parent']；pageSize最大值为 1000、未指定时默认返回 25 条，分页通过pageToken延续；
• Schema$ProductInput展示了产品标识符的编码规则：资源名格式为accounts/{account}/productInputs/{productinput}，其中{productinput}段的推荐格式是content_language~feed_label~offer_id的unpadded base64url 编码（例如ZW5-VVN-c2t1LzEyMw），若offer_id包含/、%、~等特殊字符则必须使用编码格式；
• 每次请求的根地址由options.rootUrl || 'https://merchantapi.googleapis.com/'决定，最终经createAPIRequest执行。

同样，accounts_v1.ts 中accounts.createAndConfigure的 JSDoc 示例展示了标准调用范式：先通过google.auth.GoogleAuth获取https://www.googleapis.com/auth/content权限的 auth client，再用google.options({auth: authClient})全局绑定后调用。这些示例中的 scopes 与请求体结构若在升级后发生变化，通常就会以 BREAKING 条目出现在 CHANGELOG 中。

六、升级实操指南

6.1 确认当前版本

$ npm ls @googleapis/merchantapi

或读取 package.json 中version字段（当前为 25.2.1）。

6.2 升级到最新版

$ npm install @googleapis/merchantapi@latest

6.3 升级前检查清单

1. Node 版本：运行node -v，确认 ≥ 22（对应 25.x 的engines要求）；
2. googleapis-common：确认与@googleapis/merchantapi@25.x的^9.0.0依赖约束兼容，必要时一并升级；
3. 认证方式：项目若使用google.auth.GoogleAuth或AuthPlus（见 index.ts 的导出），升级底层依赖后重新验证凭据加载路径；
4. API 契约回归：对accounts、products、reports、promotions、inventories等高频资源做一次真实调用，比对请求/响应结构；
5. 浏览 CHANGELOG 原文：逐条阅读 src/apis/merchantapi/CHANGELOG.md 中最近 2～3 个大版本（当前即 23.0.0 → 25.2.1 区间）的 BREAKING 标记，确认无遗漏风险。

6.4 按需选择 API 版本

通过 index.ts 可知该子包同时提供 26 个版本（accounts_v1、accounts_v1beta、conversions_v1、conversions_v1beta、datasources_v1、datasources_v1beta、inventories_v1、inventories_v1beta、issueresolution_v1、issueresolution_v1beta、lfp_v1、lfp_v1beta、loyaltycustomers_v1、notifications_v1、notifications_v1beta、ordertracking_v1、ordertracking_v1beta、products_v1、products_v1beta、promotions_v1、promotions_v1beta、quota_v1、quota_v1beta、reports_v1、reports_v1beta、reviews_v1beta），均可用google.merchantapi('版本名')或merchantapi({version})方式获取实例：

const {google} = require('googleapis'); const merchantapi = google.merchantapi('products_v1'); const res = await merchantapi.accounts.products.list({ parent: 'accounts/123', pageSize: 100, });

七、维护模式声明：新项目请考虑替代库

CHANGELOG 之外，src/apis/merchantapi/README.md 明确声明：本库（@googleapis/merchantapi）处于维护模式（maintenance mode），会继续供已有应用使用，但新项目或现代化改造中的存量项目，Google 官方建议改用@google-shopping/accounts库，理由是后者更快、更易用、维护更积极。安装命令为：

$ npm install @googleapis/merchantapi # 现有维护模式库 # 或面向新项目： $ npm install @google-shopping/accounts # 官方推荐替代库

决策建议：若项目已在生产环境稳定运行且不希望引入迁移成本，可继续锁定@googleapis/merchantapi并按上文清单随版本升级；若正在新建服务或重构，优先评估迁移到官方推荐库。

八、总结

@googleapis/merchantapi的 CHANGELOG 完整记录了该子包从 0.1.0（2024-07）到 25.2.1（2026-10）的演进史，其核心风险信号集中在三处：Node 运行时门槛（18 → 22）、googleapis-common 底层依赖升级（8.0.x → 9.0.0）以及由 Discovery 文档驱动的 API 契约变更（大量 BREAKING 标记）。结合仓库内的 package.json、index.ts、26 份生成源码与 discovery 目录中的 26 份 API 描述，开发者可以在升级前完成环境核验、契约回归与版本选择，将"破坏性变更"对线上服务的影响降到最低。

• 后端