尧图网站建设 
Medusa Cloud 更新日志系统从条目编写到自动化发布的完整指南【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本文基于 Medusa 开源仓库中 Cloud 文档站的更新日志Changelog基础设施深入讲解其文件格式、字段规范、链接处理规则、清单生成流程与横幅图片自动化机制并附带源码级实现证据帮助你快速掌握为 Cloud 产品线新增一条更新日志的标准做法。一、更新日志的定位与数据流向在 Medusa 文档仓库中Cloud 产品的更新日志不是手工维护的单页 Markdown而是一套以日期命名的条目文件 自动生成的清单 页面/API 双出口的结构化体系。其核心链路如下编写条目在 www/apps/cloud/generated/changelog/ 目录下新增一个{YYYY-MM-DD}.mjs文件如 2026-08-10.mjs生成清单运行yarn prep在www/apps/cloud下重新生成 index.mjs该清单被变更日志页面与公开 API 共同消费渲染与消费变更日志页面app/changelog/page.mdx与/cloud/api/changelog公开端点从清单中按需加载条目支持分页、Markdown 导出与链接改写。从源码结构看这套设计刻意将作者可编辑的部分与生成产物分离作者只写YYYY-MM-DD.mjs而index.mjs明确标注为生成文件禁止手工编辑。二、条目文件格式以YYYY-MM-DD.mjs为核心的字段规范每个条目都是一个默认导出的 ES 模块其类型定义位于 www/apps/cloud/utils/changelog.ts 中的ChangelogEntry。以下是一个完整示例来自 README.md/** type {import(../../utils/changelog).ChangelogEntry} */ export default { date: 2026-08-10, title: Build-time and runtime environment variables, summary: Environment variables can be scoped to build time or runtime, and the sidebar is now grouped by project., image: https://res.cloudinary.com/cloud/image/upload/v1/Cloud%20Changelog/august-10-2026.png, content: - You can now do a new thing. Refer to Environment Variables for more details. - Another change that went live on this date., }各字段的语义与约束字段是否必填说明date必填与文件名一致格式为YYYY-MM-DD清单按此排序最新在前title可选页面上作为条目标题的短句推荐 3–8 个词、句子式大小写、句末不加句号缺省时回退为格式化日期content必填Markdown 正文不能包含标题。因为页面会用title渲染标题若正文再写##会导致标题重复出现summary可选一句概括全文。不会渲染在页面上仅供/cloud/api/changelog端点的消费者使用image可选条目横幅图片的 Cloudinary URL。同样不渲染在页面上仅由端点返回不要手写该字段见下文横幅图片自动化实际条目参考 2026-08-24.mjs它演示了summary与content的配合export default { date: 2026-08-24, title: Filter usage by deleted projects, summary: The project filter in Usage settings now includes deleted projects, shown with a Deleted badge and sorted after active ones., image: https://res.cloudinary.com/dza7lstvk/image/upload/v1787559654/Cloud%20Changelog/august-24-2026-6208dd.png, content: - You can now filter usage data by deleted projects in the [Usage settings](https://docs.medusajs.com/cloud/usage). Deleted projects appear in the project dropdown with a **Deleted** badge and are sorted after active projects., }三个容易被忽略的细节content是模板字符串其中任何反引号或${都必须转义否则模板字符串会在解析阶段提前终止或触发插值。锚点来自日期而非标题页面上条目的锚点如#august-10-2026由date推导而来。源码中getChangelogEntryId将日期格式化为August 10, 2026后再小写化、用-替换非字母数字字符因此修改标题不会破坏指向该条目的固定链接。链接的两种写法指向 Cloud 文档其他页面的链接使用根相对路径省略/cloud基础路径与page.mdx后缀例如/environments/custom-domains指向其他文档项目的链接使用完整 URL。根相对链接会在公开端点与页面的 Markdown 版本中被改写为绝对 URL见下文链接改写。三、yarn prep与清单生成index.mjs 从何而来新增或修改条目后需要在www/apps/cloud下运行yarn prep该命令调用 scripts/generate-changelog-manifest.mjs 重新生成 index.mjs。生成逻辑的关键点文件名即日期用正则/^(\d{4}-\d{2}-\d{2})\.mjs$/匹配目录下的条目文件反向字典序排序后最新日期自然排在最前懒加载lazy import清单只保存每个条目的date和一个load: () import(./YYYY-MM-DD.mjs)闭包页面与端点按需加载而不是一次性引入全部条目。注释中明确说明打包器会把每个import()拆分为独立 chunk因此清单体积不随条目数量增长禁止手工编辑生成文件头部写有生成脚本与说明所有手动修改都会在下次yarn prep时被覆盖。当前仓库中已存在 6 个条目2026-08-04 至 2026-08-24清单结构与上述描述完全一致。四、页面与公开端点changelog.ts 的消费逻辑www/apps/cloud/utils/changelog.ts 是条目从作者格式到公开格式的转换层定义了以下核心 APIgetChangelogEntry(date, baseUrl?)按日期加载单个条目不存在时返回null。只 import 目标条目文件。getChangelogPage({ page, limit, baseUrl })分页加载条目默认每页CHANGELOG_PAGE_SIZE 10条上限CHANGELOG_MAX_PAGE_SIZE 50翻页、越界、has_more均由该函数处理且只加载当前页对应的条目文件。getChangelogMarkdown(baseUrl?)为页面的 Markdown 版本一次性加载全部条目按## title_displayDate_content的格式拼接条目间用---分隔。formatChangelogDate将YYYY-MM-DD手工解析为August 10, 2026形式。源码注释强调手工解析而非new Date()是为了避免结果随服务器时区漂移。getChangelogEntryId从日期推导锚点 id。链接改写absolutizeLinkstoPublicEntry在传入baseUrl时会调用absolutizeLinks用正则\]\((\/[^)\s]*)\)匹配 Markdown 中的根相对链接如(/environments/custom-domains)并拼接上基础地址与NEXT_PUBLIC_BASE_PATH前缀改写为绝对 URL。已绝对化的链接、锚点#...与 mailto 链接不受影响。这就是为什么作者在条目里可以放心写简短根相对路径而公开端点与 Markdown 版本仍能指向正确页面。五、横幅图片release-banner 与 Cloudinary 自动化条目顶部的横幅由 www/utils/packages/release-banner 包中的cloud-changelog类型负责渲染并上传至 Cloudinary。其唯一输入是条目的展示日期因此公共 IDpublic ID仅由日期推导——例如August 10, 2026会上传到Cloud Changelog/august-10-2026重复上传会原地覆盖旧图。从 release-banner/src/banners/cloud-changelog/index.ts 可以看到该 banner 定义的publicId与label都来自toPublicId(date)并内置了三种预览输入Aug 17、Sep 30、Dec 1, 2026以验证不同长度日期的药丸pill尺寸。自动化工作流cloud-docs-automation 工作流 会在 AI 助手Claude写完条目后自动执行两步上传横幅到 Cloudinary运行 scripts/set-changelog-image.mjs 将返回的 URL 补写进条目的image字段。set-changelog-image.mjs的文本级编辑逻辑值得注意它只修改content声明之前的头部区域因为content是任意 Markdown 模板字符串用正则定位已有image行则替换、否则在content前插入幂等设计保证同一日期重复运行不会叠加出多个image字段。手动附加横幅若需要手工为条目配图可从仓库根目录执行# CLOUDINARY_URL 必须已设置 BANNER_URL$(node www/utils/packages/release-banner/dist/cli.js upload \ --type cloud-changelog --date August 10, 2026) node www/apps/cloud/scripts/set-changelog-image.mjs \ --date 2026-08-10 --url $BANNER_URL注意没有image的条目完全合法公开端点会为其返回null。六、完整操作清单新增一条更新日志的标准步骤结合以上各环节为 Medusa Cloud 新增一条更新日志的完整流程如下在 www/apps/cloud/generated/changelog/ 下新建{YYYY-MM-DD}.mjs遵循ChangelogEntry类型编写date、title、content可选补充summary内部链接使用省略/cloud与page.mdx后缀的根相对路径content中的反引号与${必须转义且不要写##标题在www/apps/cloud下运行yarn prep重新生成 index.mjs确认新条目已按日期倒序进入清单可选按需为条目附加横幅等待自动化工作流执行或按上文命令手动上传并回填image验证变更日志页面锚点来自date页面与/cloud/api/changelog端点均可正常消费该条目summary与image仅通过端点暴露。这套约定式文件命名 自动清单 懒加载消费 图片自动化的机制将更新日志的维护成本压缩到写一个模块文件这一件事其余全部交给脚本与工作流完成——这也是后续为 Cloud 产品线持续发布变更记录时最值得复用的模式。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Medusa Cloud 更新日志系统：从条目编写到自动化发布的完整指南
Medusa Cloud 更新日志系统从条目编写到自动化发布的完整指南【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa本文基于 Medusa 开源仓库中 Cloud 文档站的更新日志Changelog基础设施深入讲解其文件格式、字段规范、链接处理规则、清单生成流程与横幅图片自动化机制并附带源码级实现证据帮助你快速掌握为 Cloud 产品线新增一条更新日志的标准做法。一、更新日志的定位与数据流向在 Medusa 文档仓库中Cloud 产品的更新日志不是手工维护的单页 Markdown而是一套以日期命名的条目文件 自动生成的清单 页面/API 双出口的结构化体系。其核心链路如下编写条目在 www/apps/cloud/generated/changelog/ 目录下新增一个{YYYY-MM-DD}.mjs文件如 2026-08-10.mjs生成清单运行yarn prep在www/apps/cloud下重新生成 index.mjs该清单被变更日志页面与公开 API 共同消费渲染与消费变更日志页面app/changelog/page.mdx与/cloud/api/changelog公开端点从清单中按需加载条目支持分页、Markdown 导出与链接改写。从源码结构看这套设计刻意将作者可编辑的部分与生成产物分离作者只写YYYY-MM-DD.mjs而index.mjs明确标注为生成文件禁止手工编辑。二、条目文件格式以YYYY-MM-DD.mjs为核心的字段规范每个条目都是一个默认导出的 ES 模块其类型定义位于 www/apps/cloud/utils/changelog.ts 中的ChangelogEntry。以下是一个完整示例来自 README.md/** type {import(../../utils/changelog).ChangelogEntry} */ export default { date: 2026-08-10, title: Build-time and runtime environment variables, summary: Environment variables can be scoped to build time or runtime, and the sidebar is now grouped by project., image: https://res.cloudinary.com/cloud/image/upload/v1/Cloud%20Changelog/august-10-2026.png, content: - You can now do a new thing. Refer to Environment Variables for more details. - Another change that went live on this date., }各字段的语义与约束字段是否必填说明date必填与文件名一致格式为YYYY-MM-DD清单按此排序最新在前title可选页面上作为条目标题的短句推荐 3–8 个词、句子式大小写、句末不加句号缺省时回退为格式化日期content必填Markdown 正文不能包含标题。因为页面会用title渲染标题若正文再写##会导致标题重复出现summary可选一句概括全文。不会渲染在页面上仅供/cloud/api/changelog端点的消费者使用image可选条目横幅图片的 Cloudinary URL。同样不渲染在页面上仅由端点返回不要手写该字段见下文横幅图片自动化实际条目参考 2026-08-24.mjs它演示了summary与content的配合export default { date: 2026-08-24, title: Filter usage by deleted projects, summary: The project filter in Usage settings now includes deleted projects, shown with a Deleted badge and sorted after active ones., image: https://res.cloudinary.com/dza7lstvk/image/upload/v1787559654/Cloud%20Changelog/august-24-2026-6208dd.png, content: - You can now filter usage data by deleted projects in the [Usage settings](https://docs.medusajs.com/cloud/usage). Deleted projects appear in the project dropdown with a **Deleted** badge and are sorted after active projects., }三个容易被忽略的细节content是模板字符串其中任何反引号或${都必须转义否则模板字符串会在解析阶段提前终止或触发插值。锚点来自日期而非标题页面上条目的锚点如#august-10-2026由date推导而来。源码中getChangelogEntryId将日期格式化为August 10, 2026后再小写化、用-替换非字母数字字符因此修改标题不会破坏指向该条目的固定链接。链接的两种写法指向 Cloud 文档其他页面的链接使用根相对路径省略/cloud基础路径与page.mdx后缀例如/environments/custom-domains指向其他文档项目的链接使用完整 URL。根相对链接会在公开端点与页面的 Markdown 版本中被改写为绝对 URL见下文链接改写。三、yarn prep与清单生成index.mjs 从何而来新增或修改条目后需要在www/apps/cloud下运行yarn prep该命令调用 scripts/generate-changelog-manifest.mjs 重新生成 index.mjs。生成逻辑的关键点文件名即日期用正则/^(\d{4}-\d{2}-\d{2})\.mjs$/匹配目录下的条目文件反向字典序排序后最新日期自然排在最前懒加载lazy import清单只保存每个条目的date和一个load: () import(./YYYY-MM-DD.mjs)闭包页面与端点按需加载而不是一次性引入全部条目。注释中明确说明打包器会把每个import()拆分为独立 chunk因此清单体积不随条目数量增长禁止手工编辑生成文件头部写有生成脚本与说明所有手动修改都会在下次yarn prep时被覆盖。当前仓库中已存在 6 个条目2026-08-04 至 2026-08-24清单结构与上述描述完全一致。四、页面与公开端点changelog.ts 的消费逻辑www/apps/cloud/utils/changelog.ts 是条目从作者格式到公开格式的转换层定义了以下核心 APIgetChangelogEntry(date, baseUrl?)按日期加载单个条目不存在时返回null。只 import 目标条目文件。getChangelogPage({ page, limit, baseUrl })分页加载条目默认每页CHANGELOG_PAGE_SIZE 10条上限CHANGELOG_MAX_PAGE_SIZE 50翻页、越界、has_more均由该函数处理且只加载当前页对应的条目文件。getChangelogMarkdown(baseUrl?)为页面的 Markdown 版本一次性加载全部条目按## title_displayDate_content的格式拼接条目间用---分隔。formatChangelogDate将YYYY-MM-DD手工解析为August 10, 2026形式。源码注释强调手工解析而非new Date()是为了避免结果随服务器时区漂移。getChangelogEntryId从日期推导锚点 id。链接改写absolutizeLinkstoPublicEntry在传入baseUrl时会调用absolutizeLinks用正则\]\((\/[^)\s]*)\)匹配 Markdown 中的根相对链接如(/environments/custom-domains)并拼接上基础地址与NEXT_PUBLIC_BASE_PATH前缀改写为绝对 URL。已绝对化的链接、锚点#...与 mailto 链接不受影响。这就是为什么作者在条目里可以放心写简短根相对路径而公开端点与 Markdown 版本仍能指向正确页面。五、横幅图片release-banner 与 Cloudinary 自动化条目顶部的横幅由 www/utils/packages/release-banner 包中的cloud-changelog类型负责渲染并上传至 Cloudinary。其唯一输入是条目的展示日期因此公共 IDpublic ID仅由日期推导——例如August 10, 2026会上传到Cloud Changelog/august-10-2026重复上传会原地覆盖旧图。从 release-banner/src/banners/cloud-changelog/index.ts 可以看到该 banner 定义的publicId与label都来自toPublicId(date)并内置了三种预览输入Aug 17、Sep 30、Dec 1, 2026以验证不同长度日期的药丸pill尺寸。自动化工作流cloud-docs-automation 工作流 会在 AI 助手Claude写完条目后自动执行两步上传横幅到 Cloudinary运行 scripts/set-changelog-image.mjs 将返回的 URL 补写进条目的image字段。set-changelog-image.mjs的文本级编辑逻辑值得注意它只修改content声明之前的头部区域因为content是任意 Markdown 模板字符串用正则定位已有image行则替换、否则在content前插入幂等设计保证同一日期重复运行不会叠加出多个image字段。手动附加横幅若需要手工为条目配图可从仓库根目录执行# CLOUDINARY_URL 必须已设置 BANNER_URL$(node www/utils/packages/release-banner/dist/cli.js upload \ --type cloud-changelog --date August 10, 2026) node www/apps/cloud/scripts/set-changelog-image.mjs \ --date 2026-08-10 --url $BANNER_URL注意没有image的条目完全合法公开端点会为其返回null。六、完整操作清单新增一条更新日志的标准步骤结合以上各环节为 Medusa Cloud 新增一条更新日志的完整流程如下在 www/apps/cloud/generated/changelog/ 下新建{YYYY-MM-DD}.mjs遵循ChangelogEntry类型编写date、title、content可选补充summary内部链接使用省略/cloud与page.mdx后缀的根相对路径content中的反引号与${必须转义且不要写##标题在www/apps/cloud下运行yarn prep重新生成 index.mjs确认新条目已按日期倒序进入清单可选按需为条目附加横幅等待自动化工作流执行或按上文命令手动上传并回填image验证变更日志页面锚点来自date页面与/cloud/api/changelog端点均可正常消费该条目summary与image仅通过端点暴露。这套约定式文件命名 自动清单 懒加载消费 图片自动化的机制将更新日志的维护成本压缩到写一个模块文件这一件事其余全部交给脚本与工作流完成——这也是后续为 Cloud 产品线持续发布变更记录时最值得复用的模式。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考