企业官网建设流程全解析

Mongoose 版本发布全流程指南：从测试、CHANGELOG 到 npm 与官网自动部署

【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose

导读

本文基于 mongoose 仓库根目录的 release-items.md 发布清单，系统梳理 mongoose 从代码冻结到 npm 上线、再到官网文档更新的完整发布流程。你将掌握 9.x 主线版本与 8.x 遗留分支（legacy release）各自的发布节奏、GitHub Release 触发 npm 自动发布的底层机制，以及大版本（major release）切换时需要同步处理的文档与分支事项，并了解如何用仓库内真实存在的脚本命令（npm run docs:prepare:publish:stable、npm publish等）落地每一步操作。

一、发布前置：质量门槛与 CI 测试矩阵

mongoose 发布流程的第一步是确保测试全部通过（release-items.md 第 1 条）。这不是一句空话，仓库通过 GitHub Actions 配置了多维度测试矩阵来把关。

从 .github/workflows/test.yml 可以看到，push与pull_request到master时，只要涉及lib/**、test/**、index.js、package.json等核心路径变更，就会触发如下测试组合：

• Node.js 版本：20、22、24（与 package.json 中engines.node >= 20.19.0的要求对应）；
• MongoDB 版本：6.0.15、7.0.12、8.2.0；
• 操作系统：ubuntu-22.04、ubuntu-24.04；
• 其中一组ubuntu-22.04 + MongoDB 6.0.15 + Node 22会额外收集覆盖率（npm run test-coverage:ci，即c8报告）。

对应到本地，可用以下命令复现部分验证：

# 完整测试（默认跳过加密相关测试） npm test # CI 精简模式：最小 reporter + 10s 超时 npm run test:ci # 副本集模式测试（事务相关功能需要） npm run test-rs:ci # 类型测试（tstyche） npm run test:types # 加密相关测试（需先执行 setup-test-encryption） npm run test-encryption:ci # 代码规范检查 npm run lint npm run lint-ts

此外，发布前还建议执行npm run docs:test（等价于npm run docs:generate），确保文档站点能正常生成——这一点与后面“更新官网”环节直接相关。

二、版本号与 CHANGELOG 管理

测试通过后，进入发布流程的第 2、3 步：更新package.json与锁文件的版本号，并更新CHANGELOG.md。

2.1 版本号

当前仓库 package.json 的版本为9.9.5，这也是本文写作时 9.x 主线的示例版本。发布时需将该字段（以及锁文件中的对应版本）改为新版本号，例如9.9.6。语义化版本号在 mongoose 中遵循常规惯例：major.minor.patch，大版本变更通常意味着破坏性 API 调整（对应migrating_to_x.md迁移指南）。

2.2 CHANGELOG 格式

从 CHANGELOG.md 开头可以看到真实条目结构（以9.9.5 / 2026-09-04为例）：

9.9.5 / 2026-09-04 ================== * fix(query): pass schema through when casting a nested $expr comparison #16496 rajanpanth * fix(projection): build the dotted path correctly in isPathSelectedInclusive #16495 rajanpanth * fix(document): replace {MODEL} in custom cast error messages from document validation #16480 #8300 AbinMadathil-Celigo * types(model): add missing properties to listSearchIndexes() return type #16486 lazerg

写入新版本条目时需要遵守的约定（release-items.md 第 3 条）：

• 每条变更以*开头，注明所属模块，例如fix(query)、fix(document)、perf(model)、docs、types(model)；
• 必须附带 GitHub Issue/PR 编号（如#16496），方便检索与回溯；
• 如该修复由社区贡献者完成，附上其 GitHub 用户名链接（如[rajanpanth](https://github.com/rajanpanth)）；
• 从 CHANGELOG 可见 9.x 与 8.x 条目是并列维护的（如8.24.4 / 2026-08-21），每个发布分支各写各的条目。

三、提交与打 Tag：发布动作落地

CHANGELOG 与版本号更新完成后，进入第 4、5 步——提交并打标签：

git commit -a -m 'release x.x.x' git tag x.x.x

其中x.x.x替换为实际版本号，例如9.9.6。git tag的标签名与版本号保持一致，后续 GitHub Release 与 npm 发布的版本识别都依赖它。

紧接着的npm run release脚本（定义在 package.json）把收尾动作脚本化：

"release": "git pull && git push origin master --tags && npm publish"

即：拉取最新远端状态 → 推送 master 分支及全部 tags → 发布到 npm。对于遗留分支，仓库还提供了对应的专用脚本：

"release-5x": "git pull origin 5.x && git push origin 5.x && git push origin 5.x --tags && npm publish --tag 5x" "release-6x": "git pull origin 6.x && git push origin 6.x && git push origin 6.x --tags && npm publish --tag 6x" "publish-7x": "npm publish --tag 7x"

注意遗留分支发布时使用npm publish --tag 5x/6x/7x这类非 latest 的 dist-tag，避免老版本覆盖 npm 上的最新标签。

四、GitHub Release 与 npm 自动发布

发布流程第 6 步明确指出：在 GitHub 上创建新 Release 后，8.x 与 9.x 会自动部署到 npm。这一自动化由 .github/workflows/publish.yml 实现，其关键配置如下：

name: Publish Package to npmjs on: release: types: [published] # 监听 GitHub Release 的 published 事件 workflow_dispatch: # 也支持在 Actions 页面手动触发 jobs: publish: runs-on: ubuntu-latest permissions: contents: read id-token: write # 用于 npm provenance（来源证明） steps: - uses: actions/checkout@v7.0.1 - uses: actions/setup-node@v7.0.0 with: node-version: '24.x' registry-url: 'https://registry.npmjs.org' - run: npm install - run: npm publish --provenance --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

从中可以提炼几个与发布直接相关的要点：

• 触发时机：release: published，即在 GitHub 上正式发布（而非 draft）Release 时才执行；
• 发布方式：npm publish --provenance --access public，--provenance表示启用 npm 的软件来源证明（与工作流中的id-token: write权限配合），--access public声明公开包；
• 凭据管理：通过 GitHub Actions Secrets 中的NPM_TOKEN注入 npm 认证，不暴露明文 token；
• Node 版本：CI 发布环境固定使用 Node 24.x。

因此，日常发布的主路径是：本地打 tag → 推送到 GitHub → 在 GitHub Releases 页面基于该 tag 创建 Release → Actions 自动完成 npm 发布。npm run release脚本中的npm publish则可视为兜底/手动方案。

五、更新官网文档（updating the website）

发布流程第 7 步要求同步更新官网 mongoosejs.com。仓库通过一系列docs:*npm 脚本管理文档构建，核心命令在 package.json 中：

5.1 9.x 主线（stable）

按 release-items.md 的步骤执行：

# 0. 切换到 master 分支 git checkout master # 1. 执行发布构建（完成后会自动切到 gh-pages 分支） npm run docs:prepare:publish:stable # 2. 提交并推送 gh-pages 分支 git commit -a -m 'chore: website 9.x.x' git push origin gh-pages

docs:prepare:publish:stable的实际定义是：

"docs:prepare:publish:stable": "git checkout gh-pages && git merge master && env GENERATE_SEARCH=true npm run docs:generate"

即：切到gh-pages分支 → 把master合并进来 → 以开启搜索索引生成（GENERATE_SEARCH=true）的方式执行docs:generate（底层是 scripts/website.js 的node ./scripts/website.js）。gh-pages分支即官网静态站点的发布载体，推送后由 GitHub Pages 对外提供服务。

5.2 8.x 遗留分支（legacy）

# 0. 切换到 8.x 分支 git checkout 8.x # 1. 执行 8.x 发布构建（完成后会自动切到 gh-pages 分支） npm run docs:prepare:publish:8x # 2. 提交并推送 git commit -a -m 'chore: website 8.x.x' git push origin gh-pages

docs:prepare:publish:8x的定义为：

"docs:prepare:publish:8x": "env DOCS_DEPLOY=true npm run docs:generate && git checkout gh-pages && rm -rf ./docs/8.x && mv ./tmp ./docs/8.x"

可以看到，8.x 文档会作为多版本文档站点中的一个子目录（docs/8.x）发布到gh-pages，而不是覆盖当前 stable 文档；9.x 的 stable 构建则直接更新站点根文档。这正是 mongoosejs.com 能同时提供多个大版本文档的实现方式。

5.3 本地预览与链接检查

发布前可用以下脚本本地验证文档：

# 生成文档 npm run docs:generate # 本地静态服务预览 npm run docs:view # 启动本地服务后检查死链（跳过广告与历史版本目录） npm run docs:check-links

另外 .github/workflows/documentation.yml 会在 PR 与 master push 时自动跑npm run lint-md（markdownlint）与npm run docs:generate的生成冒烟测试，进一步保证官网构建可复现。

六、大版本（Major Release）的专项流程

当发布的是破坏性大版本（如 8.x → 9.x）时，release-items.md 的 “major releases” 一节给出了 4 项额外工作，每一项都能在当前仓库中找到对应产物：

1. 编写迁移指南：创建docs/migrating_to_x.md。仓库中已存在 docs/migrating_to_5.md、docs/migrating_to_6.md、docs/migrating_to_7.md、docs/migrating_to_8.md、docs/migrating_to_9.md，说明历史上每个大版本都配套了独立的迁移文档；
2. 更新站点默认版本：修改docs/js/search.js中的默认版本常量。当前该文件第 5 行为const defaultVersion = '9.x';，发布新大版本时应将其指向新版本（如10.x），同时其下方代码会根据 URL 路径（/docs/(\d+\.x)）自动切换到对应版本的搜索索引；
3. 为上一大版本创建遗留分支：例如9.x，供后续 legacy release 使用；
4. 调整上一大版本分支的发布工作流：修改该分支（如9.x）上的publish.yml，使其发布到非 latest 的 npm dist-tag（如9x），避免覆盖最新版本标签。这一点与 package.json 中现存的release-5x/release-6x/publish-7x脚本的--tag用法一脉相承。

七、发布收尾：公告与遗留分支合并

发布流程的最后几步（第 8～10 条）是典型的开源项目宣发与收尾动作：

• 在 Twitter/X 上发布 CHANGELOG 链接（官方账号 @mongoosejs）；
• 在 mongoosejsteam 的 Slack 频道公告；
• 如果本次是遗留版本（legacy release），需要把变更git merge回master主分支，保证主线的历史完整、修复不丢失。

从 CHANGELOG.md 中 8.x 条目标注的(8.x backport)字样可以看出，遗留分支的修复通常来自主线代码的回迁（backport），因此发布后再合并回 master 属于双向同步，确保两条版本线最终一致。

八、发布流程速查表与注意事项

综合全文，一次完整的 9.x 主线发布可浓缩为以下清单：

注意事项：

• 遗留分支（如 8.x）的官网发布使用npm run docs:prepare:publish:8x，产物进入gh-pages的docs/8.x子目录，与 stable 版本互不覆盖；
• 遗留分支的 npm 发布务必使用非 latest 的 dist-tag（如8x、9x），避免污染最新版标签；
• 大版本发布前务必完成迁移文档、搜索默认版本、遗留分支与发布工作流四项配套工作，缺一不可；
• 整个流程的自动化依据均可在仓库中核实：发布触发见 .github/workflows/publish.yml，文档构建见 package.json 的docs:*脚本与 scripts/website.js，默认版本常量见 docs/js/search.js，历史版本条目见 CHANGELOG.md。

【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose