企业官网建设流程全解析

• 后端
• 电商

@reactioncommerce/api-plugin-files是 Mailchimp Open Commerce（Reaction API）中的文件管理插件，负责商品、标签、店铺等场景下媒体文件的上传、图片多尺寸派生、GridFS 持久化与后台异步处理。本文以该插件 CHANGELOG.md 中 2.0.0 与 1.1.0 两个版本的变更记录为主线，结合仓库内源码实现，深入解析版本演进背后的工程决策，帮助读者理解该插件"临时存储 → 后台 Worker → GridFS 多尺寸存储 → GraphQL 元数据管理"的完整链路，以及 Node 18 JSON import assertion、opaque ID 兼容处理、sharp 图像库升级等具体改造点。

插件定位与整体架构

从 src/index.js 的register(app)可以看出，该插件通过app.registerPlugin注册，主要声明了以下能力：

• 集合（collections）：MediaRecords，对应 MongoDB 集合cfs.Media.filerecord，并针对metadata.productId、metadata.variantId、metadata.priority、original.remoteURL、original.tempStoreId建立了向后兼容的索引（索引命名与旧的 aldeed:schema-index Meteor 包一致）；
• GraphQL：一组媒体记录的 mutations 与 resolver；
• 后台任务：saveImage/local与saveImage/remote两类清理任务，purgeAfterDays: 7；
• 启动钩子：startup阶段完成文件集合与 Worker 的初始化。

核心的启动逻辑在 startup.js，它在启动时调用setUpFileCollections装配下载管理器、媒体文件集合、远程 URL Worker 与临时文件 Worker，并把collections.Media暴露给 resolver，同时在 Express 上挂载两个路由：

/assets/files → downloadManager.connectHandler（文件下载） /assets/uploads → tempStore.connectHandler（浏览器分块上传）

整个媒体上传流水线可以概括为三个阶段：

1. 临时存储：浏览器通过/assets/uploads将文件分块上传到TempFileStore；
2. 后台 Worker 转储：TempFileStoreWorker监听上传完成的临时文件，将其合并后写入永久 GridFS stores；RemoteUrlWorker则负责将original.remoteURL指向的远程图片拉取入库；
3. 元数据管理：客户端通过 GraphQL mutation 创建/归档/删除/调整MediaRecord元数据，文件实体则由Media集合统一管理。

2.0.0 主要变更：Node 18 升级与 JSON import assertion

CHANGELOG 的 2.0.0 "Major Changes" 记录了一条关键改动——PR [#6740] 将 Node 版本升级到 18，并引入了assert { type: "json" }语法。这在源码中有直接对应：

import pkg from "../package.json" assert { type: "json" }; import policies from "./policies.json" assert { type: "json" };

参见 src/index.js。这是 ECMAScript Modules（ESM）规范中 JSON 模块导入的标准写法，用于显式声明导入的 JSON 资源，取代此前 CommonJS 环境下依赖createRequire才能读取 JSON 的做法。值得一提的是，项目中仍保留了兼容手段——setUpFileCollections.js 顶部通过createRequire(import.meta.url)加载file-collections与file-collections-sa-gridfs等 CJS 依赖，说明该插件在 ESM 改造中采用"新代码用 import assertion、存量 CJS 依赖用 createRequire"的渐进式策略。

同时，package.json 中"type": "module"与"engines": { "node": ">=14.18.1" }并存：engines声明了运行下限，而 CHANGELOG 明确 2.0.0 起以 Node 18 为目标版本完成验证。对于部署方，这意味着升级到 2.0.0 后应确保 Node 运行时支持 JSON import assertion（Node 18+ 默认启用，无需 flag）。

2.0.0 次要变更：解码前先校验 opaque ID，普通 ID 直接透传

2.0.0 的 "Minor Changes" 记录了一项对 GraphQL 入参处理的重要优化——PR [#6744]："checks for encodedId before calling decode. Normal-id pass through"。

此前 resolver 层对mediaRecordId、shopId等入参一律执行 opaque ID 解码，即使客户端传入的已经是内部普通 ID，也会被误解码导致错误。2.0.0 之后，resolver 统一改为"先判断、再解码、否则透传"的模式。以 resolvers/Mutation/deleteMediaRecord.js 为例：

const mediaRecord = await context.mutations.deleteMediaRecord(context, { mediaRecordId: isOpaqueId(opaqueMediaRecordId) ? decodeMediaRecordOpaqueId(opaqueMediaRecordId) : opaqueMediaRecordId, shopId: isOpaqueId(opaqueShopId) ? decodeShopOpaqueId(opaqueShopId) : opaqueShopId });

相同的模式还应用于 archiveMediaRecord.js 与 updateMediaRecordPriority.js。ID 命名空间定义集中在 src/xforms/id.js，覆盖三个命名空间：

createMediaRecordresolver 还额外对mediaRecordInput.metadata.productId、variantId分别做 opaque 判断与解码（见 resolvers/Mutation/createMediaRecord.js），防止客户端混用两种 ID 格式导致查询不到记录。这一改动对 GraphQL 客户端（尤其是直接透传数据库内部 ID 的管理后台）是明显的兼容性修复。

1.1.0 变更：sharp 图像处理库 0.29 → 0.30

1.1.0 的变更（PR [#6706]）是升级图像处理依赖sharp从 0.29 到 0.30。sharp 是媒体文件流水线中真正的图片处理引擎，它承担了setUpFileCollections中所有图片的尺寸缩放、裁剪与格式转换工作。

在 setUpFileCollections.js 中，插件为每张图片定义了 5 种派生规格：

每种规格通过buildGFS生成独立的GridFSStore实例（setUpFileCollections.js），其transformWrite使用 sharp 的.resize({ fit, withoutEnlargement: true }).toFormat(...)构建变换流，同时更新文件记录的 type 与 extension。需要特别说明的是，withoutEnlargement: true保证小图不会被放大，cover模式下的small/thumbnail会裁剪为正方形并输出 PNG，与inside模式的 JPG 形成不同的内容策略。

升级到 sharp 0.30 的意义在于：0.30 是基于 libvips 8.12 的重构版本，在图像解码、内存管理与元数据处理上均有改进，同时保持 API 兼容。对插件使用者而言，升级后图片处理行为基本无感，但部署镜像中的原生依赖需要随之更新（本插件在 package.json 中声明"sharp": "^0.30.7"）。

版本联动：三个核心依赖同步升级

2.0.0 的 "Patch Changes" 记录了三个底层依赖的联动升级，它们共同构成文件能力的基石：

• @reactioncommerce/file-collections@0.10.0：提供FileRecord、MongoFileCollection、TempFileStore、RemoteUrlWorker、TempFileStoreWorker、FileDownloadManager等核心类；
• @reactioncommerce/file-collections-sa-gridfs@0.2.0：提供 GridFS 存储实现GridFSStore；
• @reactioncommerce/api-utils@2.0.0：提供encodeOpaqueId/decodeOpaqueIdForNamespace/isOpaqueId等 ID 工具函数与 Schema 加载工具。

在 setUpFileCollections.js 中可以看到这些包的配合方式：TempFileStore仅接受type以image/开头的上传请求（setUpFileCollections.js）；MongoFileCollection("Media")将多个规格的 GridFS stores 与临时存储组合成一个集合；FileDownloadManager为/assets/files提供下载服务，并设置了长达一年的Cache-Control: public, max-age=31536000缓存头（setUpFileCollections.js）。

后台任务：saveImage/local 与 saveImage/remote

媒体从"临时/远程"到"永久存储"的转换全部走后台任务队列，这也是backgroundJobs中注册saveImage/*清理任务的背景。

任务创建：util/createSaveImageJob.js 根据isRemote决定任务类型为saveImage/remote或saveImage/local，并设置priority: "normal"、最多重试 5 次、每次等待 5 秒且采用指数退避（backoff: "exponential"）的重试策略。当RemoteUrlWorker与TempFileStoreWorker发现新的文件记录时，会分别通过onNewRemoteFileRecord/onNewTempFileRecord回调触发该任务（setUpFileCollections.js）。

任务执行：两个 Worker 分别定义在 jobs/saveRemoteImages.js 与 jobs/saveTempImages.js，统一采用 3 秒轮询间隔、10 分钟超时（workTimeout），成功调用job.done、失败调用job.fail并携带错误信息。

需要留意的一个实现细节是：setUpFileCollections.js 中两个 Worker 的启动被if (config.NODE_ENV !== "test")包裹，注释明确指出 Worker 依赖.watchAPI（需要 MongoDB replica set 与合适的 read/write concern），而 Jest 集成测试使用的内存 Mongo 服务器不满足该条件，因此在测试环境下会跳过 Worker 启动。这是部署到生产环境时值得关注的运维前提——单节点 MongoDB 无法支撑该能力。

面向客户端的 GraphQL 能力

插件对外暴露了 4 个 mutation（定义见 schemas/schema.graphql）：

各 mutation 的入参与响应类型（MediaRecordInput、MediaRecordInfoInput、MediaRecordMetadataInput及对应的 Payload 类型）都在 schema 中完整定义。实现层的几个要点：

• 权限校验：每个 mutation 都调用context.validatePermissions，权限策略在 policies.json 中声明——reaction:groups:media-managers组的用户拥有对reaction:legacy:mediaRecords资源的create:media权限，以及对reaction:legacy:mediaRecords:*的delete:media/update:media权限；
• 数据校验：MediaRecord使用 simpl-schema 定义（simpleSchemas.js），其中original包含name、size、type、updatedAt、uploadedAt，以及可选的remoteURL与tempStoreId；
• 事件广播：插入、更新、删除后分别通过appEvents.emit("afterMediaInsert" | "afterMediaUpdate" | "afterMediaRemove")发布事件，便于其他插件订阅联动。

跨插件协作：文件能力如何被其他模块复用

files插件的媒体能力并不孤立。在 apps/reaction/plugins.json 中可以看到它作为 Reaction API 应用的内置插件被注册。其他插件可以直接依赖collections.Media与collections.MediaRecords——例如 packages/api-plugin-tags/src/mutations/setTagHeroMedia.js 在为标签设置 Hero 媒体时，会直接向MediaRecords插入文档，并依据FileRecord.downloadEndpointPrefix（即/assets/files）拼出处理完成后的图片 URL：

heroMediaUrl = `${FileRecord.downloadEndpointPrefix}/${Media.name}/${insertedId}/large/${fileRecord.original.name}`;

这一 URL 拼接约定与插件中定义的 5 种图片规格直接对应——即/assets/files/Media/{mediaRecordId}/large/原文件名可访问large规格派生图。同时该实现也提示读者：如果文件插件未注册，依赖它的模块会抛出 "Cannot add media if the files plugin isn't registered" 错误（见同一文件第 28 行），体现了插件化架构中模块间的显式依赖关系。

版本演进总结与升级要点

综合 CHANGELOG 与源码，可将 api-plugin-files 近两个版本的演进归纳如下：

对正在使用该插件或计划在 Reaction API 中接入媒体能力的开发者，以下几点值得在升级与部署时重点核对：

1. 运行时版本：2.0.0 起面向 Node 18，请确保运行环境满足 JSON import assertion 的支持要求；
2. ID 格式：2.0.0 之后客户端可以混用 opaque ID 与普通内部 ID，但如果仍基于旧版 API 开发，建议统一使用 opaque ID 并保证与xforms/id.js中命名空间一致；
3. 存储架构：媒体转储依赖 MongoDB replica set 的 change stream（.watch），单节点部署无法启用 Worker；
4. 原生依赖：sharp 0.30 涉及 libvips 原生库更新，Docker 镜像需同步重建而非仅更新 npm 包；
5. 存储规格：所有上传图片都会派生 5 种规格并存入独立的 GridFS stores（前缀cfs_gridfs.，chunkSize 为 1MB），需评估存储与流量成本。

通过 CHANGELOG.md 与 README.md（项目采用 GPL-3.0 协议与 Developer Certificate of Origin 贡献规范），配合本仓库中 src/setUpFileCollections.js 等核心实现，开发者可以在不引入额外依赖的情况下，完整复现这套"临时上传 + 后台派生 + GridFS 持久化 + GraphQL 元数据管理"的电商媒体文件方案。

• 后端
• 电商