企业官网建设流程全解析

OmniRoute 发布清单实操指南：版本号升级、变更日志与发布前自动化检查全流程

【免费下载链接】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 仓库的 RELEASE_CHECKLIST.md（英文主版见 docs/ops/RELEASE_CHECKLIST.md）为主线，梳理每次打 tag 或发布新版本前必须完成的版本管理、API 文档同步、运行时文档审查与自动化检查步骤。读完你可以掌握 OmniRoute 从 bump 版本号到提交 PR 的标准化发布流程，并理解每条清单背后的仓库实现依据。

版本与变更日志管理

发布的第一步永远是"定版本、理日志"。清单要求按顺序执行以下动作：

1. 在 release 分支中升级package.json的版本号，格式为x.y.z语义化版本；
2. 将CHANGELOG.md中## [Unreleased]之下的发布说明，迁移到一个带日期的章节，即## [x.y.z] — YYYY-MM-DD；
3. 保持## [Unreleased]作为变更日志的第一个章节，供下一轮迭代继续累积；
4. 确保CHANGELOG.md中最新的 semver 章节号与package.json的 version 字段完全一致。

在仓库中可以验证这套约定的实际落点：根 package.json 当前版本为3.8.51，CHANGELOG.md 首部即为## [Unreleased]章节，随后才是已发布的版本记录。若你在 release 分支上git log生成提交列表，需要人工复核提交信息并按功能归类，因为变更日志的可读性直接影响下游使用者与搜索引擎对版本差异的理解。

API 文档同步

版本号变更并非只在package.json一处生效，API 契约也必须对齐：

1. 更新docs/openapi.yaml：其中info.version必须等于package.json的版本号；
2. 若 API 契约（端点、参数、响应结构）在本轮发生了变更，需逐一校验 openapi 文档中的端点示例仍然可用。

仓库根目录下存在 docs/openapi.yaml，它是公开的 API 描述文件（根目录另有 public/openapi.yaml 供前端侧引用）。发布时若两者都涉及版本信息，应一并核对。实践建议：将"版本号已同步"与"端点示例可跑通"作为两项独立勾选，避免只改字段、漏验契约。

运行时文档审查

每次发布还要排查运行时事实与文档是否漂移：

1. 审查 docs/architecture/ARCHITECTURE.md，确认其中对存储层与运行时的描述没有过时；
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. 若英文源文档改动较大，同步更新本地化（i18n）文档。

关于 Node 版本门槛，仓库实现比清单更精确：src/shared/utils/nodeRuntimeSupport.ts 中定义了SUPPORTED_NODE_RANGE = ">=22.22.2 <23 || >=24.0.0 <27"，SECURE_NODE_LINES列出了 22.22.2、24.0.0、25.0.0、26.0.0 四个安全基线，且该模块被运行时 CLI 入口（bin/）、Next.js 路由处理器（src/）与仓库脚本（scripts/）共用。根 package.json 的engines字段与之一致。也就是说，随着版本演进，清单中的下限已从 20.x 时代升级到当前以 22.22.2+ / 24.0.0+ 为准，发布时以npm run check:node-runtime的实际校验结果为准即可。

npm run check:pack-artifact对应 scripts/build/validate-pack-artifact.ts，它扫描打包目录中是否混入本地残留文件——这正是"干净产物"检查的实现载体。

发布前的自动化同步检查

在打开 PR 之前，必须在本地运行文档同步守卫：

npm run check:docs-sync

该命令对应 scripts/check/check-docs-sync.mjs。它的核心职责是校验 i18n 翻译文档树与英文源文档一一对应、无漂移——这正是本文所引用的docs/i18n/it/docs/ops/RELEASE_CHECKLIST.md这类翻译文件存在的意义。此外，CI 的 lint job 也会在 .github/workflows/ci.yml 中再次运行同一检查，形成"本地先行、CI 兜底"的双保险。提交时它还会被 Husky 的 pre-commit 钩子自动触发（见 .husky/pre-commit），所以即使忘了手动执行，提交阶段也会被拦截提醒。

纵深：完整发布流程的关键关卡

除上述四步外，英文主版清单还细化了从"发布前"到"回滚"的完整关卡，可作为深度执行的参考：

• 发布前：确认目标 PR 全部合入release/vX.Y.0、CI 在 release 分支上全绿、代码中无TODO(release)残留，并确认 Docker 基础镜像已更新；
• 代码质量：npm run lint零错误、typecheck:core与typecheck:noimplicit:core干净、check:cycles无循环依赖、check:any-budget:t11与check:route-validation:t06在预算内、check:node-runtime通过；这些命令全部登记在根 package.json 的 scripts 中；
• 测试矩阵：test:unit、test:vitest、test:coverage（门槛 60/60/60/60，即 statements/lines/functions/branches 四维覆盖）、test:integration、test:combo:matrix、test:e2e、test:protocols:e2e、test:ecosystem等按改动面执行，其中 package.json 中test:coverage通过 c8 以--check-coverage --statements 60 --lines 60 --functions 60 --branches 60强制执行门槛；
• Husky 钩子：pre-commit 运行 lint-staged、docs-sync 与预算检查；pre-push 运行确定性快门（check:any-budget:t11与check:tracked-artifacts）。钩子失败必须修复根因，禁止--no-verify绕过；
• Conventional Commits：所有发布提交必须符合type(scope): subject格式，类型限于feat/fix/refactor/docs/test/chore/perf/style/ci，破坏性变更需附加BREAKING CHANGE:脚注或在 scope 后加!；
• 构建布局：仓库使用三套输出目录——src/（TypeScript/TSX 源码，入库）、.build/（next build 中间产物，gitignore）、dist/（可发布的 npm 包，由assembleStandalone汇总，gitignore）。发布部署统一走npm run build:release（先清空.build与dist，再 next build、组装 standalone、写入dist/BUILD_SHA），不要拆成npm run build+npm run build:cli两段执行；
• 工件校验：dist/BUILD_SHA必须等于git rev-parse --short HEAD，check:pack-artifact无残留，dist/server.js存在；
• 打标签与发布：通过/generate-release-ccskill 创建并推送vX.Y.Ztag、打开带 changelog 正文的 Release；或手工执行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；
• 部署与冒烟：部署 skill 采用轻量 rsync 流程（不打 npm pack、不全局安装）；部署后打开/dashboard/health核对版本字符串、对已知 provider 发一次/v1/chat/completions请求、确认/api/monitoring/health的熔断器为CLOSED、并验证 MCP 传输端点响应；
• 回滚与硬规则：发布异常时先gh release edit vX.Y.Z --prerelease标记非最新；未广泛采纳时可删除 tag；否则在 release 分支上打 patch 热修。硬规则包括：禁止直接提交main、禁止强推main/release/*、禁止跳过 Husky、禁止提交密钥与.env、覆盖率始终 ≥60/60/60/60、改动src/、open-sse/、electron/、bin/必须同步更新测试。

小结

OmniRoute 的发布清单把"版本号—变更日志—API 文档—运行时事实—产物干净度"串成一条可验证的流水线：本地npm run check:docs-sync与 Husky 钩子保证提交即合规，CI 的 lint job 再次兜底；而 Node 运行时门槛、打包残留扫描、覆盖率四维门槛则分别在 src/shared/utils/nodeRuntimeSupport.ts、scripts/build/validate-pack-artifact.ts 与 package.json 的test:coverage配置中落地。对任何准备为 OmniRoute 提发布 PR 的贡献者而言，照此清单逐项勾选即可获得一条"开箱即绿"的发布路径。

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