Cypress 稳定版发布全流程指南：从 develop 分支到 npm dist-tag 的工程化落地手册

Cypress 稳定版发布全流程指南：从 develop 分支到 npm dist-tag 的工程化落地手册

【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress

在 Cypress 这个仓库中，"发布"特指将Cypress 桌面端二进制（binary）与cypressnpm 模块从一个"开发中"状态正式变为用户可下载、可npm install的稳定版本。本指南完整梳理这一发布流程：从权限与凭据准备、CI 上的预发布验证，到本地执行的 24 步发布操作（制作稳定制品、打dev/latestdist-tag、更新下载服务器 manifest、发版打 tag、回填 issue 评论等）。读完本文，你将掌握该仓库的发布骨架（见 guides/release-process.md），并理解每一步背后对应的脚本实现与设计动机。

本文聚焦的主流程针对Cypress binary +cypressnpm 模块；仓库中位于 npm/ 目录下、以@cypress/为命名空间的其余 npm 包不在此流程内——它们在合并进develop后由semantic-release自动发布（详见 CONTRIBUTING.md 的 releases 一节）。

谁可以执行发布

任何开发者都可以在本地构建二进制与 npm 包（见 构建发布制品指南），但只有cypressnpm 组织的成员才能把 Cypress 应用部署到 CDN、并把cypress模块发布到 npm registry。发布脚本假设执行人同时具备两类基础设施权限：可读写 AWS S3（即 Cypress CDN）的 AWS 账户，以及可发布cypress包的 npm 账户权限。

发布前置条件

发布是一系列人工驱动、半自动化的命令组合，执行前必须完成权限、凭据与代码仓库三层准备。

1. AWS SSO 与prodprofile

发布脚本需要把二进制推入 Cypress CDN（S3 bucketcdn.cypress.io），因此要求配置一个 AWS SSO profile，角色为 Team-CypressApp-Prod（在 "App Developer" 分栏中可找到若干必要的配置值）。脚本假定该 profile 名为prod。AWS 配置文件最终应形如：

[profile prod] sso_start_url = <start_url> sso_region = <region> sso_account_id = <account_id> sso_role_name = <role_name> region = <region> cli_pager = <pager>

若你的凭据放在其他 profile 名下，则必须在后续步骤中通过AWS_PROFILE环境变量显式指定（例如export AWS_PROFILE=production）。

2. 环境变量

发布过程中多个阶段需要注入凭据，可事先在 1Password 中获取：

• release-automations阶段需要的 GitHub 凭据：

GITHUB_TOKEN="..." GITHUB_APP_CYPRESS_INSTALLATION_ID= GITHUB_APP_ID= GITHUB_PRIVATE_KEY=

其中cypress-botGitHub App 凭据用于以机器人身份在 issue 上回填"已修复版本"评论。

• 清空 Cloudflare 缓存所需凭据（供第 6 步的prepare-release-artifacts与第 14 步的binary-release使用）：

CF_ZONEID="..." CF_TOKEN="..."

没有 1Password 访问权限时，应找一位执行过部署的团队成员协助。

3. 待贡献的关联仓库

发布过程会向以下仓库发起 PR 或运行其中的命令，需提前在本地检出并准备好：

• cypress-realworld-app（典型用户消费形态的示例工程）
• cypress-documentation（发布版本文档与 changelog）
• cypress-docker-images（Docker 镜像）
• cypress-io/release-automations（批量 issue 评论工具）

4. 发布前：CI 全量验证

正式发布前，develop分支必须已经由 CI 完成跨平台构建与真实项目回归。对develop的每次提交，CI 会自动执行以下工作：

1. 把下一个目标版本号内建到 npm 包中进行构建；
2. 在 CircleCI 上构建 Linux、Mac 与 Windows 三平台的二进制；
3. 将二进制与新 npm 包上传到 AWS S3 bucketcdn.cypress.io下的beta目录；
4. 使用新上传的包与二进制启动各测试项目，而不是从 npm registry 安装，从而在真实项目上回归本次改动。

每个目标操作系统都会启动多个测试项目，结果以 GitHub 状态检查（status checks）回传，用来判断改动是否破坏了 Cypress 的真实使用场景。若第 4 步的发布操作被执行，务必先确认develop上的状态检查全部通过（即存在一个绿色的 CI 基线）。

版本号如何确定

"X.Y.Z"在整份发布流程中指代 Cypress 的下一个目标版本号，其确定逻辑独立封装在 scripts/get-next-version.js，说明文档见 guides/next-version.md。

该脚本按以下优先级决策：

1. 若存在环境变量NEXT_VERSION（如NEXT_VERSION=1.2.3），直接输出该值并退出。发布分支或强制指定某个主版本号时通常会这么做。
2. 否则分析当前分支自上次发布以来的提交，依据语义化提交信息推算版本：
   • 只统计触及packages/*或cli/*的提交，避免npm/子包的提交误触发 CLI/binary 版本递增；
   • 采用angular提交风格：fix:触发 patch 递增，feat:触发 minor 递增，带BREAKING CHANGE:footer 的提交触发 major 递增（实现上通过conventional-recommended-bump对packages、cli两个路径分别计算并取 semver 较大者）；
   • 根 package.json 中硬编码的真实版本会优先于推算结果被采用，而0.0.0-development哨兵版本则会被忽略。

可用node ./scripts/get-next-version.js在本地调试，它会分析当前分支的提交并打印推算结果。

发布新版本的标准操作步骤

下面的 "X.Y.Z" 即上文所述的下一版本号。动身前建议先通知团队：develop分支在发布期间将被锁定。

步骤 1：安装并测试预发布版本

目标版本在 CI 上构建出的是"预发布（pre-release）"产物，先在本地人工验证其可用性：

• 安装新版本：
  • 全局安装：npm install -g <cypress.tgz 路径>
  • 或在项目内安装：npm i -D cypress@file:<cypress.tgz 路径>
• 快速冒烟测试：执行cypress open，进入一个项目跑一条测试，确认一切正常；
• 可选：将新版本安装进既有成熟项目（cypress-realworld-app使用 yarn，是典型消费端形态）后运行测试；
• 可选：进行更彻底的测试，例如拿新版本对 Cypress Cloud 仓库跑回归。

步骤 2：确认 on.cypress.io 链接清单已部署

确保所有对on.cypress.io链接清单（links manifest）的改动都已合入develop并完成部署，否则新版本中相关跳转链接可能失效。

步骤 3：（可选）创建 Release PR

如果本轮有新增的配套发布物，提交一个用于"升版本 + 记 changelog"的 Release PR：

• 若有新的cypress-example-kitchensink版本，则升级 packages/example 的依赖并运行yarn以保持 lockfile 最新；
• 按编写 Cypress Changelog 指南中的 release 小节更新 cli/CHANGELOG.md；
• 若无需改动 changelog、也没有新的 kitchensink 版本，本步可跳过，直接沿用develop上最后一次构建产物。

步骤 4：等待绿色基线并核对预发布版本注释

当develop分支 CI 全绿，且确认cypress-bot已在提交上以注释形式给出darwin-x64、darwin-arm64、linux-x64、linux-arm64、win32-x64五个平台/架构的预发布版本地址后，才可进入发布。让 CI 变绿的实用技巧：

• windows工作流若因超时报错，可仅从最后一个失败步骤重试；
• windows工作流偶发在多次尝试间卡死在失败态，此时整体重启一次该工作流通常能恢复；
• linux-x64工作流若因 flaky 测试失败但 Percy 已 finalize 构建，必须从失败步骤重启；整体重启会触发 Percy 在下一次报 "Build has already been finalized" 错误，届时只能靠推送新提交重来。

步骤 5：登录 AWS SSO

aws sso login --profile <profile_name>

若你的 profile 不叫prod，需export AWS_PROFILE=production（以实际名字为准），让后续步骤使用正确的身份。

步骤 6：运行prepare-release-artifacts制作稳定制品（仅 Mac/Linux）

这是把"最新提交"升级为"稳定发布"的核心一步，由 scripts/prepare-release-artifacts.js 驱动：

yarn prepare-release-artifacts --sha <commit sha> --version <new target version>

脚本执行前先做参数校验：--sha必须是 40 位十六进制 commit SHA，--version必须是X.Y.Z形式的语义版本号（见 prepare-release-artifacts.js）。运行后依次发生：

• 通过node ./scripts/binary.js move-binaries --sha ... --version ...，把对应 commit SHA 的二进制从 S3 的beta目录移动到desktop/<新版本>目录；
• 清空该版本的 Cloudflare 缓存；
• 把预发布的cypress.tgz转换成可直接发布的稳定 npm 包。

move-binaries的底层实现在 scripts/binary/move-binaries.ts：它会列出 S3 上匹配该 commit 的构建路径（格式如beta/binary/3.3.0/darwin-x64/circle-develop-<40位sha>-<build号>/），当同一 commit 对应多条路径时选取 build 号最大（最后构建）的那条，经交互确认后移动到统一的稳定目录。

yarn prepare-release-artifacts --dry-run可预览脚本将要执行的命令而不真正执行（prepare-release-artifacts.js）。另外，在 macOS 上执行需要加前缀COPYFILE_DISABLE=1，避免 OSX 把隐藏文件打进了二进制的.tgz包。

步骤 7：校验 npm 登录状态

npm whoami

未登录则执行npm login。若你还不是 Cypress 包的 maintainer，需请团队成员把你加入组织。

步骤 8：以devtag 发布生成好的 npm 包

用 npm service account 发布第 6 步产出的稳定 tgz，但 tag 仍是dev：

npm publish /tmp/cypress-prod.tgz --tag dev

/tmp/cypress-prod.tgz正是 scripts/create-stable-npm-package.sh 的产物：它从https://cdn.cypress.io/beta/npm/<版本>/linux-x64/develop-<sha>/cypress.tgz（仅支持 linux-x64 的 tgz，见 prepare-release-artifacts.js）下载预发布包，解压后把package/package.json中的buildInfo.stable改写为true，再重新打包——这一步完成"预发布包 → 稳定包"的标记切换。

步骤 9：复核 dist-tags

确认新版本已挂在devtag 下，且latest仍指向上一稳定版本：

npm view cypress dist-tags

示例输出（注意latest保持不变）：

$ npm view cypress dist-tags { latest: '14.5.3', dev: '14.5.4' }

npm view反映最新版本信息可能存在数分钟延迟，属于正常现象。

步骤 10：验证cypress@X.Y.Z

在真实使用形态下再验证一次刚发布的版本：npm install -g cypress@X.Y.Z，随后cypress open进入项目跑冒烟测试；建议再安装进cypress-realworld-app等既有项目执行测试，必要时进行更深入的回归。

步骤 11：处理版本文档与 changelog PR

在cypress-documentation中审查本版本的文档与 changelog PR，若没有则创建一个：

• 把 Release PR 中的本版本 changelog 内容复制进/docs/app/references/changelog.mdx，并把其中的docs.cypress.io链接调整为 host-relative 路径；
• 在版本标题下按_Released MMM DD, YYYY_格式补上发布日期；
• 把发布相关的文档改动合入主 Release PR。

步骤 12：创建新版 Docker 镜像

在cypress-docker-images中为factory/.env的 cypress 版本发起 PR 升级到新版本，并在镜像测试通过后再继续。

步骤 13：将latesttag 指向新版本

npm dist-tag add cypress@X.Y.Z

执行后npm view cypress dist-tags应显示latest与dev均为新版本。

步骤 14：运行binary-release更新下载服务器 manifest

yarn binary-release --version X.Y.Z

该命令对应node ./scripts/binary.js release（见 package.json 中 scripts 定义），其实现位于 scripts/binary/index.js。它会更新下载服务器的 manifest（download.cypress.io/desktop.json），并确保该版本二进制在每个系统都可用：release完成后自动对darwin-x64、darwin-arm64、linux-x64、linux-arm64、win32-x64五个组合逐一发起download.cypress.io/desktop/<version>?platform=...&arch=...的探测请求校验可下载性，同时读取 manifest 校验其中version字段与目标版本一致。若某个平台探测失败，脚本会提示先执行yarn binary-purge --version X.Y.Z清理 Cloudflare 缓存，再用yarn binary-ensure --version X.Y.Z复检。

步骤 15：合入文档与 Docker 镜像 PR

合并第 11 步的文档 PR 与第 12 步的 docker 镜像 PR，Docker 镜像随之发布。

步骤 16：（如需）部署 kitchensink 示例站点

当需要把新版cypress-example-kitchensink部署到example.cypress.io时，按 packages/example/README.md 的 Deployment 章节操作：

yarn workspace @packages/example build

先检查./packages/example/build内容是否正确，再执行：

yarn workspace @packages/example deploy

该命令把cypress-example-kitchensink的改动作为一个 commit 合入gh-pages分支，由其自身 CI 部署上线；最后访问部署站点确认变更生效。

步骤 17：基于版本提交创建 Git tag

从发布了版本号递增的那个 commit 上打 tag：

git checkout develop git pull origin develop git log --pretty=oneline # 复制版本递增 commit 的 sha git tag -a vX.Y.Z -m vX.Y.Z <sha> git push origin vX.Y.Z

步骤 18：创建 GitHub Release

在 GitHub Releases 页面选择刚推送的 tag，补上与历史 Release 风格一致的发布说明。

步骤 19：给已修复 issue 批量评论

从verify-release-readinessCircleCI job 下载releaseData.json构件，然后在cypress-io/release-automations仓库内执行：

npm run do:comment -- --release-data <path_to_releaseData.json>

cypress-bot会据此向每个"本次发布已修复"的 issue 追加版本评论（这也解释了前置条件中为何需要 GitHub App 凭据）。

步骤 20：确认无遗留的stage: pending releaseissue

检查已关闭 issue 中是否还有带stage: pending release标签的残留，确保本轮修复都被正确标记。

步骤 21：通知团队重新开放develop

发布公告由 GitHub bot 自动发送到 releases 频道；如需补充细节，以回复形式追加即可。

步骤 22：清理 changelog 校验开关

若本轮使用了SKIP_RELEASE_CHANGELOG_VALIDATION_FOR_BRANCHES变量绕过 changelog 校验，请按需调整其值或从 CircleCI 中删除，确保后续 PR 恢复常规校验。

步骤 23：回填各测试/示例仓库的依赖版本

检查各cypress-test-*与cypress-example-*仓库：若存在用于回归本版本的x.y.z分支，将其package.json中的 cypress 依赖更新为新发布版本并合入主干；无对应分支的项目可在 Renovate 依赖 issue 中勾选Update dependency cypress to X.Y.Z让其自动建 PR，通过后合入。至少应更新cypress-realworld-app与cypress-example-recipes两个项目。

步骤 24：轮换 npm 凭据

在 CircleCI 的org-npm-credentialscontext 内轮换NPM_TOKEN；若登录时新建过 npm token，请一并删除该临时 token。

至此发布完成。

把发布流程放在一起看：制品仓库与 CDN 布局

把上述步骤串联起来，就能理解 Cypress 发布的制品流动规律：

• npm 包（.tgz）由 cli 构建（命令行工具、类型定义与 Module API），以cypress包名安装进用户项目的node_modules；
• 二进制（.zip）由 packages 目录构建（Electron 应用、ffmpeg及各子包成品），在安装cli或执行cypress install时被拉取到系统缓存；
• CI 期间所有产物先落在 S3 的beta路径下，例如beta/binary/<版本>/<平台>/<develop-sha>/cypress.zip与beta/npm/<版本>/develop-<sha>/cypress.tgz（路径拼装逻辑见 scripts/binary/upload-build-artifact.js）；
• 第 6 步move-binaries把它们迁入desktop/<版本>/（releaseFolder: 'desktop'定义于 scripts/binary/util/upload.js），第 14 步binary-release再保证下载 manifest 与各平台 URL 生效，整个发布链路即告闭环。

需要了解制品如何在本地构建（对应"Anyone can build"部分）时，可阅读构建发布制品指南；相关的自动化单元测试（如move-binaries、制品准备与上传逻辑）可在snapshots目录对应的快照测试中继续追溯。

【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress