如何在Cypress中以编程方式访问ci-build-id？

能不能直接获取ci-build-id？ #

Cypress没有提供直接访问ci-build-id的官方API，但可以通过两种间接方式拿到：

1. 解析命令行启动参数 #

因为ci-build-id是通过cypress run --ci-build-id <你的ID>传入的，你可以在setupNodeEvents里解析process.argv提取这个值：

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const argv = process.argv;
      const ciBuildIdIndex = argv.indexOf('--ci-build-id');
      const ciBuildId = ciBuildIdIndex !== -1 ? argv[ciBuildIdIndex + 1] : null;

      // 把ID挂到config.env里，方便后续测试或钩子调用
      config.env.ciBuildId = ciBuildId;

      if (ciBuildId) {
        // 这里就可以用这个ID做你需要的单次触发逻辑了
        console.log(`当前Build ID: ${ciBuildId}`);
      }

      return config;
    },
  },
});

2. 读取Cypress自动设置的环境变量 #

当用cypress run --record录制测试时，部分CI环境下Cypress会自动把ci-build-id写入CYPRESS_CI_BUILD_ID环境变量，直接读就行：

const ciBuildId = process.env.CYPRESS_CI_BUILD_ID || null;

注意：这个变量不是所有场景都有，本地录制或者部分CI平台可能不会自动设置，所以要加兜底。

替代方案：不依赖ci-build-id的实现 #

如果不想纠结ci-build-id的获取，完全可以自己搞一个全局Build标识，确保并行/重跑时保持一致：

1. 复用CI平台自带的Build ID #

几乎所有主流CI工具都有自己的Build ID环境变量，直接兼容读取就行：

// cypress.config.ts
import { defineConfig } from 'cypress';
import fs from 'fs';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      let buildId;
      // 适配不同CI平台
      if (process.env.GITHUB_RUN_ID) {
        buildId = process.env.GITHUB_RUN_ID;
      } else if (process.env.CI_PIPELINE_ID) {
        buildId = process.env.CI_PIPELINE_ID;
      } else if (process.env.BUILD_ID) {
        buildId = process.env.BUILD_ID;
      } else {
        // 本地环境生成临时ID
        buildId = `local-build-${Date.now()}`;
      }

      config.env.globalBuildId = buildId;

      // 用文件锁确保同一Build只触发一次事件
      const lockFile = `.build-${buildId}.lock`;
      if (!fs.existsSync(lockFile)) {
        fs.writeFileSync(lockFile, '');
        // 这里放你的单次事件逻辑
        console.log(`触发Build级事件，ID: ${buildId}`);
        
        // 测试跑完后清理锁文件
        on('after:run', () => {
          fs.existsSync(lockFile) && fs.unlinkSync(lockFile);
        });
      }

      return config;
    },
  },
});

2. 自定义生成UUID作为Build ID #

如果没有CI环境变量，启动Cypress前先生成一个UUID，通过环境变量传给所有进程：

// package.json 脚本
"scripts": {
  "cy:run": "export CYPRESS_GLOBAL_BUILD_ID=$(uuidgen) && cypress run --record"
}

然后在插件里读取：

const buildId = process.env.CYPRESS_GLOBAL_BUILD_ID;

单次事件触发的额外思路 #

除了文件锁，还可以用Redis这类外部缓存，以Build ID为key标记是否已执行；或者干脆把单次事件放到CI流程的前置步骤里，不用在Cypress中处理。

内容的提问来源于stack exchange，提问作者Zaista