Bitbucket中同时运行Percy与Cypress报错及初始化问题求助

问题现象 #

• Bitbucket环境下直接运行Cypress可正常执行，执行percy exec -- cypress命令时抛出错误：
  
• 当前使用的bitbucket-pipelines.yml配置如下，不清楚Percy的正确初始化方式：
  

修复步骤 #

1. 补全依赖安装 #

必须同时安装Percy CLI和Cypress对应的Percy依赖，不要全局安装CLI，直接装到项目开发依赖中，避免CI环境下路径、权限不匹配问题：

npm install -D @percy/cli @percy/cypress

同时确认Cypress的支持文件（一般路径为cypress/support/e2e.js或cypress/support/commands.js）中已经引入Percy命令：

import '@percy/cypress'

2. 配置Percy鉴权环境变量 #

不要把Percy的token硬编码在配置文件中，去Bitbucket对应仓库的配置页添加安全变量：

• 进入仓库 > Repository settings > Pipelines > Repository variables
• 新增变量，名称为PERCY_TOKEN，值填写对应Percy项目的写入token，勾选Secure选项避免日志泄露

3. 修正pipeline配置 #

推荐使用Cypress官方预装了浏览器的镜像作为运行环境，避免缺浏览器依赖、系统库缺失的问题，参考配置如下：

# 选择和你本地Cypress版本兼容的cypress/browsers镜像tag即可
image: cypress/browsers:node-18.16.0-chrome-114.0.5735.133-1-ff-114.0.2-edge-114.0.1823.51-1

pipelines:
  default:
    - step:
        name: E2E Test with Percy
        caches:
          - node
          - cypress
        script:
          # 用npm ci按照lockfile严格安装依赖，比npm install稳定性更高
          - npm ci
          # 用npx调用项目本地安装的percy cli，避免全局命令找不到的问题
          - npx percy exec -- cypress run --browser chrome

如果有自定义的Cypress运行参数（比如指定spec路径、配置文件路径），直接追加在cypress run命令后即可。

4. 常见报错排查 #

• 提示percy: command not found：确认@percy/cli已经安装到项目devDependencies，调用时加npx前缀解决路径问题
• 提示PERCY_TOKEN相关错误：检查环境变量是否配置在当前pipeline生效的范围内，Secure变量不要配置在fork的PR触发流程中（Bitbucket默认不会给fork的PR传递安全变量）
• 浏览器启动失败、缺少系统依赖：不要用纯Node基础镜像，替换为上文提到的cypress/browsers官方镜像
• 提示cy.percySnapshot is not a function：回到步骤1检查Cypress支持文件是否正确引入了@percy/cypress

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