企业官网建设流程全解析

OmniRoute 发布检查清单实战指南：从版本号到 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 仓库的发布检查清单（docs/i18n/da/docs/ops/RELEASE_CHECKLIST.md，及英文完整版 docs/ops/RELEASE_CHECKLIST.md）为核心骨架，结合仓库内真实脚本源码，讲解在打 tag、发布新版本之前必须完成的全部校验动作：版本号与 Changelog 同步、OpenAPI 契约核对、Node.js 安全基线、npm 发布产物洁净度，以及check:docs-sync自动化同步守卫。读完本文，你将掌握 OmniRoute 一整套可执行、可验证的发布前操作流，并能对照源码理解每一项检查背后的实现原理。

一、这份清单在做什么：发布前的最终防线

OmniRoute 是一个 MIT 开源的统一 AI 网关项目（package.json 描述为 "Unified AI router"），聚合大量 provider 与模型，同时对外发布 npm 包、Docker 镜像、Electron 桌面端和文档站。由于发布面广，任何一处版本号漂移、文档失同步或残留本地文件泄漏进 npm 包，都会直接影响用户升级体验与包体完整性。

发布检查清单（Release Checklist）就是为此设计的最终防线：在打 tag 或发布新版本之前逐项核对。丹麦语版本清单将其归纳为四大部分：

1. Version and Changelog—— 版本号与变更日志同步；
2. API Docs—— OpenAPI 文档版本契约；
3. Runtime Docs—— 运行时文档与 Node.js 安全基线、发布产物检查；
4. Automated Check—— 自动化同步守卫（npm run check:docs-sync）。

这四部分在仓库中不是孤立的手工清单，而是有真实脚本背书的"可执行检查项"。下文将逐节展开，并给出每项检查对应的源码实现位置。

二、版本号与 Changelog：三处必须一致的版本契约

清单原文要求（"Version and Changelog"）：

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

这条规则之所以是硬性要求，是因为它在仓库里由npm run check:docs-sync以代码强制校验（脚本 scripts/check/check-docs-sync.mjs）：

• 读取 package.json 的version字段，并用 semver 正则校验格式（X.Y.Z或X.Y.Z-prerelease.N）；
• 解析 CHANGELOG.md，要求第一小节必须是## [Unreleased]；
• 过滤出所有 semver 版本小节，要求最新一个小节的版本号与package.json完全相等。

一旦CHANGELOG.md最新版本节与package.json不一致，脚本即输出[docs-sync] FAIL - Latest changelog release (X.Y.Z) differs from package.json (X.Y.Z)并以非零退出码失败。也就是说，版本号不是随便一改就完事，它必须同时驱动 changelog 重构。

英文完整版清单 docs/ops/RELEASE_CHECKLIST.md 进一步补充了实操方式：通过 Claude Code skill/version-bump-cc <patch|minor|major>一次完成package.json、electron/package.json的版本提升、从最近 tag 以来的 git 提交重新生成CHANGELOG.md、并更新 README 徽章。当前仓库版本为3.8.51（见 package.json 与 docs/openapi.yaml）。

三、API 文档：OpenAPI 版本必须与 package.json 严格相等

清单"API Docs"一节要求：

1. 更新docs/openapi.yaml，使其info.version必须等于package.json的版本号；
2. 如果 API 契约发生变化，需要验证端点示例（endpoint examples）。

这里需要留意一个仓库内路径约定：清单中写的是docs/reference/openapi.yaml，而实际仓库根目录的 OpenAPI 定义位于 docs/openapi.yaml（同时 public/openapi.yaml 也有一份用于站点分发），check:docs-sync脚本校验的正是根目录docs/openapi.yaml。以实际仓库为准。

info.version与package.json版本的一致性不是"建议"，而是check:docs-sync的强制检查项：check-docs-sync.mjs 会解析 OpenAPI 文件中的info:块并提取version字段，与package.json的version逐字比对，不一致即 FAIL。当前两份文件均为3.8.51，保持一致。

从源码角度看，OpenAPI 契约的严肃性还体现在一系列专项检查脚本上（见 package.json 的 scripts 区）：

• check:openapi-coverage—— 校验路由覆盖；
• check:openapi-routes—— 校验 OpenAPI 中的路由与实际代码路由一致；
• check:openapi-breaking—— 检测 API 破坏性变更；
• check:openapi-security-tiers—— 校验安全分级。

也就是说，发布前若 API 有改动，除了手工更新info.version，还需要跑完这一组 OpenAPI 专项检查，确保契约、路由、安全分级三者与代码一致。

四、运行时文档与 Node.js 安全基线：发布环境的版本下限

清单"Runtime Docs"一节要求发布前完成五件事：

1. 检查 docs/architecture/ARCHITECTURE.md 是否存在存储/运行时漂移（storage/runtime drift）；
2. 检查 docs/guides/TROUBLESHOOTING.md 是否存在环境变量与运维层面的漂移；
3. 验证发布/运行时 Node.js 版本仍满足受支持的安全下限：
   • >=20.20.2 <21或>=22.22.2 <23（丹麦语清单中的表述），并运行npm run check:node-runtime；
4. 在构建独立包后校验 npm 发布产物：
   • npm run build:cli
   • npm run check:pack-artifact
   • 确认没有app.__qa_backup、scripts/scratch、package-lock.json等本地残留文件混入包内；
5. 如果源文档发生重大变更，更新本地化文档。

4.1 Node.js 安全基线的真实定义

丹麦语清单中给出的 Node.js 范围（>=20.20.2 <21或>=22.22.2 <23）是文档翻译时点的快照，仓库当前的实际策略以单一事实源src/shared/utils/nodeRuntimeSupport.ts 为准：

export const SECURE_NODE_LINES = Object.freeze([ Object.freeze({ major: 22, minor: 22, patch: 2 }), Object.freeze({ major: 24, minor: 0, patch: 0 }), Object.freeze({ major: 25, minor: 0, patch: 0 }), Object.freeze({ major: 26, minor: 0, patch: 0 }), ]); export const RECOMMENDED_NODE_VERSION = "24.14.1"; export const SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27";

该策略同时写入了 package.json 的engines字段："node": ">=22.22.2 <23 || >=24.0.0 <27"。从源码看，版本判断逻辑为：解析当前 Node 主版本 → 在SECURE_NODE_LINES中查找对应主版本的安全下限→ 当前版本低于该下限则判定为below-security-floor（不支持）并输出警告。也就是说，每个受支持的 LTS 主版本线都有自己的补丁安全下限，低于下限即被拒绝，这正是"secure floor"（安全下限）的含义。

npm run check:node-runtime对应脚本 scripts/check/check-supported-node-runtime.ts，它调用上面的策略模块：不兼容时打印警告并以退出码 1 失败；兼容时输出类似Node.js v24.x satisfies OmniRoute secure runtime policy的成功信息，且额外支持 Bun 运行时判定（Bun 1.1+也视为满足策略）。

4.2 npm 发布产物校验：不让本地残留泄漏进包里

清单要求构建独立包后执行：

npm run build:cli npm run check:pack-artifact

• build:cli对应 scripts/build/prepublish.ts，负责打包发布前所需的 CLI 独立产物；
• check:pack-artifact对应 scripts/build/validate-pack-artifact.ts，它通过 scripts/build/pack-artifact-policy.ts 中定义的允许路径白名单（PACK_ARTIFACT_ALLOWED_EXACT_PATHS、PACK_ARTIFACT_ALLOWED_PATH_PREFIXES）和必需路径清单（PACK_ARTIFACT_REQUIRED_PATHS）对发布产物做双向检查：
  • 检查是否存在不应出现的意外路径（如app.__qa_backup、scripts/scratch、package-lock.json等本地残留）；
  • 检查必需的产物路径是否齐全。

除此之外，validate-pack-artifact.ts还会调用buildProvenance.ts校验构建出处（build provenance），并借助mcpPublishedFilesClosure.ts检查 MCP 文件闭包是否存在泄漏的测试产物（findLeakedTestArtifactPaths）与缺失的闭包路径。这套机制从"白名单 + 必需清单 + 出处校验"三个维度保证了 npm 包只包含应该发布的内容。

英文完整版清单还补充了单项命令npm run build:release（组合了rm -rf .build dist清理、next build生成中间产物、assembleStandalone汇总独立产物、写入dist/BUILD_SHA哨兵），并强调发布部署不要分别跑npm run build和npm run build:cli，而应使用一条build:release完成干净重建 + 哨兵写入（部署前还需确认dist/BUILD_SHA等于git rev-parse --short HEAD）。

五、自动化同步检查：check:docs-sync 与 CI 集成

清单"Automated Check"一节要求在开 PR 前本地运行同步守卫：

npm run check:docs-sync

并且 CI 也会在.github/workflows/ci.yml的 lint job 中运行此检查。这个守卫就是 scripts/check/check-docs-sync.mjs，它实际上是一个文档版本同步的总闸门，除前文提到的三处版本契约外，还承担两类 i18n 镜像校验：

1. 严格镜像（llm.txt）：docs/i18n/<locale>/llm.txt必须与根目录 llm.txt 逐字节一致（该文件不做翻译，因此要求完全相同）；
2. 翻译镜像（CHANGELOG.md）：各语言 docs/i18n 目录下的CHANGELOG.md允许翻译，但必须包含根 CHANGELOG.md 中全部版本小节且顺序一致，且正文行数与源文件的偏差不得超过 25%——防止翻译版长期未同步导致内容枯竭。

此外，脚本还内置了"防回归"机制：禁止已被替代的遗留文档重新出现（例如docs/CLI-TOOLS.md一旦重新出现即 FAIL，必须以docs/reference/CLI-TOOLS.md为唯一事实源）。

这也解释了为什么丹麦语清单第 5 步要求"如果源文档发生重大变更，需要更新本地化文档"——因为check:docs-sync会强制所有语言镜像保持同步，任何源文档改动如果不同步更新 docs/i18n 下的镜像文件，CI 会直接红掉。

六、完整发布流程：从质量门禁到打 tag 部署

丹麦语清单聚焦在版本/文档/运行时三块核心校验上，而英文完整版 docs/ops/RELEASE_CHECKLIST.md 给出了整个发布生命周期的全貌，两者属于同一清单体系。结合两者，一个完整版本发布大致经过以下阶段：

1. 发布前准备：所有目标 PR 合入release/vX.Y.0分支、CI 在该分支全绿、代码中无TODO(release)标记（grep -r "TODO(release)" src/ open-sse/）、Docker 基础镜像保持最新；
2. 版本与 Changelog：/version-bump-cc <patch|minor|major>或手工完成版本提升与 changelog 整理（第二节）；
3. 代码质量门禁：npm run lint（0 错误）、npm run typecheck:core、npm run typecheck:noimplicit:core（严格模式）、npm run check:cycles（无循环依赖）、npm run check:any-budget:t11、npm run check:route-validation:t06、npm run check:node-runtime（第四节）；
4. 测试矩阵：npm run test:unit、npm run test:vitest（MCP server、autoCombo、cache）、npm run test:coverage（覆盖率门禁 60/60/60/60，即 statements/lines/functions/branches 均不低于 60%）、npm run test:integration、npm run test:combo:matrix（19 种公开路由策略的确定性选择验证）、按需的test:e2e、test:protocols:e2e、test:ecosystem；
5. Husky 钩子：pre-commit 自动跑lint-staged+check-docs-sync+check:any-budget:t11；pre-push 跑快速门禁。任何钩子失败都应修复底层问题，不得用--no-verify绕过；
6. 文档与 i18n：npm run check:docs-all（docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links 的总入口）、npm run i18n:check（翻译状态与源文档同步）、npm run i18n:check-ui-coverage（42 个语言环境的 UI 覆盖率不低于 80% 下限）、npm run i18n:sync-ui:dry（无缺失 key）；若英文源文档有变，需运行npm run i18n:run重新翻译；
7. 数据库迁移：src/lib/db/migrations/新增迁移必须幂等、包在事务中、编号无断层；在全新安装与既有安装上分别验证；
8. 构建与产物校验：npm run build:release→npm run check:pack-artifact→ 确认dist/BUILD_SHA与 HEAD 一致、dist/server.js存在；
9. 打 tag 与发布：/generate-release-cc或手工git tag -a vX.Y.Z -m "Release vX.Y.Z"→git push origin vX.Y.Z→gh release create vX.Y.Z --notes-from-tag，并附上 Electron 安装包（如已构建）；
10. 部署与冒烟：按目标选择/deploy-vps-local-cc、/deploy-vps-akamai-cc或/deploy-vps-both-cc；部署后打开/dashboard/health核对版本字符串、对一个已知 provider 发起/v1/chat/completions请求、确认/api/monitoring/health返回CLOSED熔断状态、确认 MCP 传输（/mcpHTTP 与/mcp-sseSSE）可用；
11. 发布后：/capture-release-evidences-cc采集新功能的 WebP 截图/录屏并附到发布说明，更新社区公告，为下一版本开启 milestone。

回滚预案

英文清单定义了发布后发现严重问题的三层回滚策略：

# 1. 标记为非最新版本 gh release edit vX.Y.Z --prerelease # 2. 仅在尚未被用户采用时删除 tag git tag -d vX.Y.Z && git push --delete origin vX.Y.Z # 3. 或者：在 release 分支上出 hotfix，发补丁版本 vX.Y.(Z+1)

同时强调：Docker 侧永远不要重写版本 tag，回滚是把latest重新指向上一个良好 digest。

硬规则（Hard Rules）

清单以一组不可协商的硬规则收尾，这些规则同时是仓库 CI/钩子强制执行的：

• 永不直接向main提交；
• 永不对main或release/*分支使用git push --force；
• 永不用--no-verify跳过 Husky 钩子；
• 永不提交密钥、凭据或.env文件；
• 覆盖率必须始终 ≥ 60/60/60/60；
• 修改src/、open-sse/、electron/或bin/下生产代码时，必须同步包含或更新测试。

七、小结：清单 + 脚本 = 可执行的发布契约

OmniRoute 的发布检查清单并非停留在文档层面，而是与仓库脚本深度绑定：版本契约由 check-docs-sync.mjs 强制校验，Node.js 安全基线由 nodeRuntimeSupport.ts 单一事实源定义、由 check-supported-node-runtime.ts 执行，发布产物洁净度由 validate-pack-artifact.ts 以白名单 + 必需清单双向把关。对贡献者而言，发布前只需要做到"文档跟着代码走、版本跟着 changelog 走、产物跟着白名单走"，即可让本地npm run check:docs-sync与 CI 全绿，确保一次正确、可审计、可回滚的发布。

【免费下载链接】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