Cypress 发布产物构建指南：npm 包与 Electron 二进制的构建、打包与发布流程

Cypress 发布产物构建指南npm 包与 Electron 二进制的构建、打包与发布流程【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress本篇围绕 Cypress 仓库中的构建指南 building-release-artifacts.md 展开讲清 Cypress 发布产物的两大组成——npm 包与二进制压缩包——各自如何构建、打包与验证。读完你能掌握yarn lerna run build-cli、yarn binary-build、yarn binary-package、yarn binary-zip等命令的完整用法与适用平台限制并能结合 scripts/binary/build.ts、scripts/binary/zip.js 等源码理解产物内部的组装过程。发布产物的整体结构Cypress 的cypressnpm 包由两部分组成二者必须保持同一版本号npm 包.tgz由 cli 目录构建包含命令行工具cypress、TypeScript 类型定义和 Module API最终用户通过 npm/Yarn/pnpm 将其安装到项目的node_modules目录。二进制.zip由 packages 目录构建包含 Electron 应用、ffmpeg以及 packages 子目录中各包的构建产物frontend-shared、reporter、web-config不单独打包进去同时包含上述所有包的生产依赖在cli安装时或执行cypress install时被下载到系统缓存目录生产环境下若本地未缓存会从 Cypress CDN 拉取。该指南覆盖了这两种产物的构建方式并额外提供了打包、冒烟测试、上传与缓存清理等配套流程。构建 npm 包指南原文特别提示以下两步在 CI 中已自动化按正式发布流程见 release-process.md走时不需要你手动执行。构建一个 npm 包只需要两步递增根 package.json 中的version运行yarn lerna run build-cli。这两步实际完成的工作构建cypressnpm 包将代码转译为 ES5以兼容常见的 Node 版本结果输出到 cli/build 目录。从源码看build-cli脚本定义在 cli/package.json 中build: rollup -c, postbuild: yarn make-bin-executable yarn sync-build-dist yarn prepare-package-json yarn bundle-ct-frameworks, build-cli: rollup -c yarn postbuild,即先用 cli/rollup.config.mjs 完成 Rollup 打包随后依次执行 bin 可执行化处理、产物同步、package.json 准备cli/scripts/prepare-package-json.ts与组件测试框架的框架打包cli/scripts/bundle-ct-frameworks.ts保证 npm 包内容完整可发布。构建二进制同样地二进制的构建步骤在 CI 中已自动化。npm 包必须有同版本的二进制与之对应生产环境下若本地未缓存会从 CDN 检索。本地构建的入口命令见根 package.json 的scripts命令作用脚本定义yarn binary-build构建二进制cross-env NODE_OPTIONS--max_old_space_size8192 node ./scripts/binary.js buildyarn binary-package打包electron 打包二进制cross-env NODE_OPTIONS--max_old_space_size8192 node ./scripts/binary.js packageyarn binary-zip将构建好的二进制压缩为 zipnode ./scripts/binary.js zipyarn binary-smoke-test对构建产物做冒烟测试node ./scripts/binary.js smokeyarn binary-deploybuild → zip → upload 一条龙node ./scripts/binary.js deployyarn binary-purge清理某版本各平台的 CDN 缓存node ./scripts/binary.js purge-version注意binary-build与binary-package都通过cross-env注入了NODE_OPTIONS--max_old_space_size8192因为构建过程内存占用较高。平台选择可以在 Linux 上构建 Cypress 二进制与 CI 相同的方式——在yarn docker容器内运行yarn binary-build和yarn binary-package。仓库根目录提供了 docker-compose.yml 支撑该容器环境。macOS 本地构建需要在钥匙串中拥有代码签名证书按 Apple 官方代码签名指南申请。另外由于公证notarization需要 Apple Developer Program 账号本地构建时通常应设置SKIP_NOTARIZATION1跳过公证。CI 中的代码签名细节见 code-signing.md。构建阶段内部做了什么源码级解读yarn binary-build最终调用 scripts/binary/index.js 中deploy.build再进入 scripts/binary/build.ts 的buildCypressApp。其流程与源码注释高度对应禁止交叉构建if (platform ! os.platform())直接抛错Attempting to cross-build, which is not supported——这正是指南要求在哪个平台构建哪个平台产物、或用 docker 构建 Linux 版的底层原因见 scripts/binary/build.ts#L77-L80清理与符号链接删除TMP_BUILD_DIR、build/与packages/electron/dist并将build符号链接到系统临时目录下的cypress-build/platform/build路径常量定义在 scripts/binary/meta.ts 的TMP_BUILD_DIR、buildRootDir构建各子包把目标version写回根package.json保证 V8 快照与版本正确然后并发执行yarn lerna run build与yarn lerna run build-prod并发度为min(4, os.availableParallelism())拷贝到 distpackages.copyAllToDist把各包产物拷贝进 dist 目录并拷贝 patches 目录过滤掉.dev.patch因为生产安装只会应用生产补丁同时拷贝yarn.lock保证安装一致性精简生产依赖剔除devDependencies、lint-staged等字段后写入 dist 的package.jsonpostinstall只保留patch-package再执行yarn --production瘦身用del删除各依赖包中的测试目录如pixelmatch/test、exif-parser/test等、.ts源文件与开发用补丁写入运行时入口生成 dist 的index.jsrequire(./packages/server/index.js)与包含electronVersion/electronNodeVersion的package.json构建后自验证testDistVersion在 dist 目录执行node index.js --version并与目标版本比对testStaticAssets校验静态资源任何不一致都会让构建失败。yarn binary-package则调用packageElectronAppscripts/binary/build.ts#L237移除node_modules/.bin、开发用 Electron 应用目录等打包后无用的内容通过electron-builder以publish: never、asar: false配置进行应用打包注释说明因 electron-builder 不会拷贝packages/*/node_modules中的嵌套目录故不使用 asarWindows 路径长度防护checkMaxPathLength按默认缓存位置 260 字符上限检查 dist 内所有相对路径超限即报错要求提升hoist或删除文件scripts/binary/build.ts#L45-L70macOS GateKeeper 校验当platform darwin且未跳过签名时用spctl -a -vvvv验证应用签名失败即抛 Verifying App via GateKeeper failedscripts/binary/build.ts#L309-L326最后用du -d 1统计各包大小并做性能追踪便于控制 Test Runner 体积。各平台产物目录约定由 scripts/binary/meta.ts 统一管理macOS 为build/macM1 为build/mac-arm64下的Cypress.appLinux 为build/linux-unpackedarm64 为linux-arm64-unpackedWindows 为build/win-unpacked见meta.buildDir实现。冒烟测试构建完成后建议跑yarn binary-smoke-test。对应 scripts/binary/index.js 的smoke方法在无显示环境下自动启动 xvfbxvfb.isNeeded()然后执行testExecutableVersion——调用构建产物的可执行文件加--versionLinux 沙箱环境会追加--no-sandbox断言输出与构建版本一致再对应用目录执行 scripts/binary/smoke.js 的冒烟测试。打包压缩二进制yarn binary-zip的调用链是deploy.zip→meta.zipDir(platform)取待压缩目录 →zip.ditto(zipDir, zipPath)。scripts/binary/zip.js 按平台分派三种压缩工具平台工具命令要点Linuxzipcd 父目录 zip -r9 dest Cypress先renameFolder确保顶层目录名为CypressmacOSdittoditto -c -k --sequesterRsrc --keepParent src dest保留资源分叉并保留顶层目录Windows7-Zip7z a dest src整个目录含顶层Cypress/压入其中 Linux 与 Windows 路径在压缩后会执行checkZipSizescripts/binary/zip.js#L70-L84const MAX_ALLOWED_SIZE_MB os.platform() win32 ? 295 : 256zip 超过 256MBWindows 295MB直接抛错。源码注释特别叮嘱修改这个上限前先查清是什么导致了二进制体积增长并在 PR 中说明。发布流水线与 CDN 校验yarn binary-deploy走完整管线scripts/binary/index.js#L417-L435build→zip→upload。upload将 zip 上传到 S3 的指定路径upload.getFullUploadPath随后通过 scripts/binary/util/upload.js 清理该版本的 Cloudflare 缓存。发布完成后还有两级 CDN 校验release流程清单校验checkManifest拉取download.cypress.io/desktop.json确认manifest.version与发布版本一致下载校验checkDownloads对 5 个平台/架构组合linux-x64、linux-arm64、darwin-x64、darwin-arm64、win32-x64逐一HEAD请求确认二进制存在若有缺失提示用yarn binary-purge --version v清理 Cloudflare 缓存后再用yarn binary-ensure --version v复查见 scripts/binary/index.js#L177-L242。实用技巧指南 Tips 原文加速打包设置V8_SNAPSHOT_DISABLE_MINIFY1可缩短二进制打包耗时。从源码看该开关在 V8 快照工具的 tooling/v8-snapshot/src/setup/config.ts#L95 中被读取const minify !process.env.V8_SNAPSHOT_DISABLE_MINIFY env prod即跳过生产环境对快照的压缩步骤以换取速度M1 芯片在 M1 Mac 上打包后若要实际运行该二进制需要设置RESET_ADHOC_SIGNATURE1来重置临时adhoc签名。小结Cypress 的发布产物由 npm 包与二进制 zip 双轨构成npm 包只需递增版本并执行yarn lerna run build-cli产出进入cli/build二进制则通过yarn binary-build构建 dist 并做版本/静态资源自验证、yarn binary-packageelectron-builder 打包、平台签名与 GateKeeper 校验、yarn binary-zip平台化压缩并做体积上限检查三步完成再配合binary-deploy、binary-smoke-test与 CDN 清单/下载校验形成完整闭环。所有环节在 CI 中已自动化本地执行时按本文命令即可复现平台限制不支持交叉构建、macOS 需签名证书、Linux 可走 docker是实操中最需要留意的约束。【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考