企业官网建设流程全解析

OmniRoute 发布检查清单实践：版本同步守卫、Node 运行时安全基线与 npm 产物校验

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

在发布新的 OmniRoute 版本（打 tag / 推送 npm 包 / 构建独立部署包）之前，团队需要一套可重复、可自动校验的"发布前检查"流程。本文以仓库中的 发布检查清单 为核心骨架，展开其中的四项发布关卡——版本号与 CHANGELOG 同步、OpenAPI 文档对齐、Node.js 运行时安全版本校验、npm 打包产物纯净性校验——并结合scripts/check/、scripts/build/下的守卫脚本源码，说明每条检查项在代码层面究竟校验了什么、为什么这样设计。读完后，你可以掌握：如何在任何发布分支上运行npm run check:docs-sync等守卫命令，理解其失败条件，并在自己的发布流程中复用同样的"文档-版本-产物"一致性守卫模式。

一、检查清单的定位与总体流程

发布检查清单 的原始定位只有一句话："Use this checklist before tagging or publishing a new OmniRoute release." 即它是打 tag 或发布新版本前的强制前置动作。英文完整版本（docs/ops/RELEASE_CHECKLIST.md）进一步把它组织为"版本与 Changelog → API 文档 → 运行时文档 → 自动化检查"四段式流程，每段都有明确的通过判据。

需要说明的是，仓库中存在多语言镜像副本，例如本文参考的 孟加拉语版本（路径docs/i18n/bn/docs/ops/RELEASE_CHECKLIST.md）。这些镜像不是手工维护的第二份文档，而是被check:docs-sync守卫逐字节对照的镜像文件（下文第四节会展开其校验逻辑）。

清单中列出的全部检查项及对应命令如下，均可在仓库根目录直接执行：

这些命令都注册在根 package.json 的scripts段：

"build:cli": "node --import tsx scripts/build/prepublish.ts", "check:docs-sync": "node scripts/check/check-docs-sync.mjs", "check:node-runtime": "node --import tsx scripts/check/check-supported-node-runtime.ts", "check:pack-artifact": "node --import tsx scripts/build/validate-pack-artifact.ts"

也就是说，清单里的每一条命令背后都是一个真实的仓库脚本，而不是约定俗成的口号——这为下文逐项剖析源码细节提供了基础。

二、版本与 CHANGELOG：三处版本号必须一致

清单的 "Version and Changelog" 小节要求四件事：

1. 在 release 分支上把package.json的版本号（x.y.z）bump 到位；
2. 把CHANGELOG.md中## [Unreleased]下的发布说明移动到带日期的版本段：## [x.y.z] — YYYY-MM-DD；
3. 保持## [Unreleased]作为 changelog 的第一个版本段，用于承接后续工作；
4. 确保CHANGELOG.md中最新的 semver 段与package.json的版本相等。

看当前仓库的 CHANGELOG.md 可以验证这一结构的实际形态：文件以# Changelog开头，紧接着## [Unreleased]，其下按### ✨ New Features等分节罗列即将随下一版本发布的内容，之后才是各历史版本段。

这四条规则不是靠人眼保证的，而是由 scripts/check/check-docs-sync.mjs 在每次提交/CI 中自动执行。其核心校验逻辑可以归纳为：

• semver 合法性：package.json的version必须匹配X.Y.Z或X.Y.Z-prerelease.N（例如3.0.0-rc.1），否则直接报package.json version is not valid semver失败；
• OpenAPI 版本提取：逐行扫描 docs/openapi.yaml，定位info:块内部缩进两格的version:字段（extractOpenApiVersion函数），要求它严格等于package.json版本；
• CHANGELOG 段序校验：用正则/^##\s+\[([^\]]+)\](?:\s+[-—–].*)?$/gm提取所有## [版本]标题，要求：
  • 第一个段必须是Unreleased（CHANGELOG.md first section must be "## [Unreleased]"）；
  • 过滤出的 semver 段中最新一个必须等于package.json版本，否则报Latest changelog release (…) differs from package.json (…)。

因此清单第 4 条"最新 semver 段等于 package.json 版本"实际上是一个机器可判定的断言，npm run check:docs-sync全部通过时会输出[docs-sync] PASS - documentation version sync is consistent.，任何一条不满足则以退出码 1 结束（[docs-sync] FAIL - …）。

三、API 文档：OpenAPI 版本对齐与示例校验

清单的 "API Docs" 小节要求：

1. 更新docs/reference/openapi.yaml中的info.version，使其等于package.json版本；
2. 如果 API 契约有变化，验证端点示例仍然有效。

从源码结构看，守卫脚本实际读取的路径是仓库根目录下的 docs/openapi.yaml，docs/ops/RELEASE_CHECKLIST.md 的 "Documentation" 一节同样把docs/openapi.yaml与package.json版本的一致性列为文档检查项之一，并提到若新功能带有 API，需同步更新docs/reference/API_REFERENCE.md与docs/openapi.yaml。两处版本必须同步，这正是check:docs-sync中OpenAPI version (x) differs from package.json (y)这条失败信息的来源。

对"验证端点示例"这一步，清单给出的判据是"API 契约变更时"才需要人工核对；仓库中 OpenAPI 规范文件同时存在于docs/openapi.yaml与 public/openapi.yaml（后者面向服务暴露），契约变更时应两者一并检查。

四、运行时文档：架构漂移复查与 Node 安全版本基线

"Runtime Docs" 小节包含五步，其中第 3、4 步对应两个可执行守卫：

1. 复查 docs/architecture/ARCHITECTURE.md 是否存在存储/运行时描述漂移；
2. 复查 docs/guides/TROUBLESHOOTING.md 是否存在环境变量与运维描述漂移；
3. 验证发布/运行使用的 Node.js 版本仍满足"受支持的安全 floor"，运行npm run check:node-runtime；
4. 构建 standalone 包后验证 npm 产物（npm run build:cli+npm run check:pack-artifact），确认产物中不含app.__qa_backup、scripts/scratch、package-lock.json等本地残留；
5. 如果源文档有较大变化，同步更新本地化文档。

4.1 check:node-runtime 的底层实现

scripts/check/check-supported-node-runtime.ts 本身只有二十几行：它调用共享模块 src/shared/utils/nodeRuntimeSupport.ts 中的getNodeRuntimeSupport()，若nodeCompatible为false则打印警告信息（含受支持区间与推荐版本）并以退出码 1 结束；若运行在 Bun 上则直接判定为兼容（supported-bun），并输出 "Bun x.y.z (…) satisfies OmniRoute secure runtime policy."。

真正的策略定义在src/shared/utils/nodeRuntimeSupport.ts。该模块按 major 版本维护一张"安全 floor 表"（SECURE_NODE_LINES）：

判定逻辑是：解析当前process.versions.node，找到对应 major 的 floor，比较>= floor才算兼容；major ≥ 27 记为unreleased-major（不支持的未发布主线）。失败时getNodeRuntimeWarning()会区分两种提示："below the patched minimum v22.22.2 for this LTS line"（低于该 LTS 线的已修补下限）与"outside the supported LTS lines"（不在受支持主线内）。

关于版本区间，这里需要指出一个文档与代码的时点差异：docs/ops/RELEASE_CHECKLIST.md 中 "Runtime Docs" 小节写的是>=20.20.2 <21或>=22.22.2 <23，而当前仓库的 package.jsonengines字段为>=22.22.2 <23 || >=24.0.0 <27，与nodeRuntimeSupport.ts中的SUPPORTED_NODE_RANGE（">=22.22.2 <23 || >=24.0.0 <27"）及推荐版本24.14.1完全对齐。清单文档中的旧写法反映的是较早时点的策略；以当前仓库实际内容为准：Node.js 22.22.2+（22.x LTS）、24.0.0+（24.x LTS）、25.0.0+ 或 26.0.0+ 均可通过守卫，Bun 1.1+ 亦被接受。这个模块的注释也说明了它被刻意写成纯 ESM，以便bin/运行时入口、src/路由处理器与scripts/仓库脚本三方复用同一份策略，避免"检查脚本"和"运行时守卫"各自为政产生漂移。

4.2 check:pack-artifact：产物纯净性的白名单机制

npm run build:cli由 scripts/build/prepublish.ts 执行，产出发布用的独立包；随后npm run check:pack-artifact由 scripts/build/validate-pack-artifact.ts 执行。它的实现方式是：跑一次npm pack --dry-run --json --ignore-scripts拿到将要打入 tarball 的完整文件列表，然后做四类断言：

1. 意外文件（黑名单/白名单差集）：findUnexpectedArtifactPaths依据pack-artifact-policy.ts中的PACK_ARTIFACT_ALLOWED_EXACT_PATHS（精确路径白名单）与PACK_ARTIFACT_ALLOWED_PATH_PREFIXES（前缀白名单）计算差集——任何不在白名单内的文件都会让检查失败。清单中点名的app.__qa_backup、scripts/scratch、package-lock.json就属于典型的"不应出现在 npm 产物里的本地残留"，正是这条断言拦截的对象；
2. 缺失必需文件：findMissingArtifactPaths对照PACK_ARTIFACT_REQUIRED_PATHS，确保运行必需文件（如dist/下的运行时文件）真的在产物里；若dist/缺失，脚本会先自动补跑npm run build:cli再校验；
3. 测试文件泄漏：findLeakedTestArtifactPaths专门禁止*.test.*/__tests__泄漏进产物——宽泛的files前缀（如open-sse/、src/lib/）容易把测试文件一起带出去，所以必须在真实 pack 列表上显式禁止；
4. MCP 闭包完整性：MCP 服务器从发布的 TypeScript 源码直接运行，computeMcpClosure会算出所有可达源文件并确认它们全部被打进产物，否则发布后--mcp模式会 404。

脚本还支持--policy-only快路径：跳过构建与必需文件检查，只对照真实 pack 列表做源侧策略检查，用于在 PR 快车道上廉价地捕获源侧回归。完整模式下还会做构建溯源（provenance）校验：读取dist/BUILD_SHA，通过 git 祖先探测确认该构建确实来自发布线（OMNIROUTE_RELEASE_REF，默认origin/main），杜绝"用 feature 分支的旧构建冒充发布产物"的事故。

五、自动化检查：docs-sync 守卫与 CI 集成

清单最后一节 "Automated Check" 要求在开 PR 前本地先跑：

npm run check:docs-sync

并说明 CI 也会运行该检查。核对 scripts/check/check-docs-sync.mjs 的完整检查面，可以发现它实际比"三个版本号一致"覆盖得更多：

1. package.json版本：必须是合法 semver；
2. docs/openapi.yaml的info.version：必须与package.json相等；
3. CHANGELOG.md结构：首段必须是## [Unreleased]，且最新 semver 段必须等于package.json版本；
4. i18n 镜像一致性：
   • llm.txt 的各语言镜像（docs/i18n/<locale>/llm.txt）必须是逐字节精确拷贝（去首行标题、归一化换行后比较）——因为它是面向 LLM 的机器可读文件，不允许翻译；
   • 各语言CHANGELOG.md镜像则采用宽松校验：必须包含根 CHANGELOG 的所有## [X.Y.Z]版本段（允许标题被翻译成各语言，如 "Security" → "Segurança"），且正文行数与源文档偏差不得超过 25%（防止翻译版本严重过期或缺失）。镜像文件本身还必须具备 i18n 镜像分隔线---（语言导航条与正文之间的分隔符）；
5. 反回归断言：已被取代的旧文档路径（如docs/CLI-TOOLS.md→ 现以docs/reference/CLI-TOOLS.md为唯一事实来源）若"复活"即失败。

任何一项失败都会打印[docs-sync] FAIL - …并以退出码 1 结束；全部通过则输出[docs-sync] PASS - documentation version sync is consistent.。

在 CI 侧，该守卫由 .github/workflows/ci.yml 中的docs-sync-strict作业执行（作业内运行的是超集命令npm run check:docs-all，覆盖 docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links），并且被下游聚合作业显式依赖（needs列表中可见docs-sync-strict），其结果会写入 GitHub Step Summary。清单原文将其描述为"CI 在 ci.yml 的 lint 作业中运行该检查"，属于同一守卫在不同作业编排中的挂载点描述；从当前工作流文件看，check:docs-sync的严格形态由docs-sync-strict专职作业承担。

六、可复制的发布前操作序列

把清单与守卫脚本串起来，一个可复制的发布前检查序列如下（在仓库根目录执行）：

# 1. bump package.json 版本，把 CHANGELOG.md 的 [Unreleased] 内容 # 移到 "## [x.y.z] — YYYY-MM-DD" 段，并保留 Unreleased 段在最前 # 2. 同步 docs/openapi.yaml 的 info.version 为同一版本号 # 3. 文档-版本一致性守卫（本地先跑，CI 也会跑） npm run check:docs-sync # 4. Node.js 运行时安全基线（要求 22.22.2+ / 24.0.0+ / 25+ / 26+ 或 Bun 1.1+） npm run check:node-runtime # 5. 构建 standalone 包并校验 npm 产物 npm run build:cli npm run check:pack-artifact # 确认产物无 app.__qa_backup / scripts/scratch / package-lock.json 等残留

若第 3 步失败，按[docs-sync] FAIL - …的具体信息定位：版本号不一致（对齐package.json、CHANGELOG.md、docs/openapi.yaml三处）、CHANGELOG 首段不是Unreleased、或某个docs/i18n/<locale>/镜像与源文档漂移（更新对应镜像或重跑翻译同步流程）；若第 4 步失败，按提示切换 Node 版本（推荐 24.14.1）或升级至各 LTS 线的 patched minimum 之上；若第 5 步失败，按输出的意外/缺失文件清单收紧package.json的files配置或清理本地残留。

七、这套守卫模式的设计要点

从仓库实现可以提炼出三点值得借鉴的设计：

• 单一事实来源 + 机器断言：版本号只允许以package.json为准，OpenAPI 与 CHANGELOG 的一致性不做人工承诺，而是由check-docs-sync.mjs在每个提交钩子与 CI 上断言，失败即阻断；
• 共享策略模块：Node 运行时安全基线集中在src/shared/utils/nodeRuntimeSupport.ts，被 CLI 入口、路由处理器、检查脚本三方复用，避免"检查脚本认为支持、运行时却拒绝"的漂移；
• 白名单化的产物审计：npm 产物校验以"精确路径 + 前缀白名单 + 必需文件 + 泄漏黑名单 + 溯源指纹"组合判定，把"产物里能出现什么"变成可静态审计的清单，而非依赖npm pack的默认忽略规则。

以上命令与判据均以当前仓库的 package.json、scripts/check/check-docs-sync.mjs、src/shared/utils/nodeRuntimeSupport.ts、scripts/build/validate-pack-artifact.ts 为准；完整的发布前置项（质量门、测试矩阵、Electron、部署与回滚流程）可继续参阅 docs/ops/RELEASE_CHECKLIST.md。

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute