GitLab流水线报错TypeError: cy.login is not a function，本地测试正常

DevOps 小满

2026-6-25

这个问题核心是CI环境下Cypress自定义命令cy.login未被正确加载，本地运行正常说明本地配置逻辑没问题，重点排查CI环境的配置差异，按以下步骤逐一验证：

检查CI工作目录与配置文件路径
确认CI执行Cypress命令时的工作目录和本地一致，若项目中Cypress配置文件（如cypress.config.js或e2e.js）不在根目录，需在CI命令中显式指定配置文件路径，比如：
```
cypress run --config-file ./path/to/cypress.config.js
```
避免因CI工作目录不同导致配置文件找不到。
验证commands.js的导入逻辑
检查e2e.js（或Cypress配置的支持文件）中是否存在import './commands'语句，且路径正确。若项目是TypeScript结构，确认tsconfig.json的路径映射规则在CI环境中正常生效，防止相对路径解析错误。
确保CI依赖安装完整
排查CI的依赖安装命令是否添加了--production这类参数，导致Cypress相关开发依赖未安装。建议CI中使用npm install（无生产参数），并清理旧缓存（GitLab CI可手动触发缓存清理或修改缓存key），保证依赖和本地完全一致。
确认自定义命令定义格式正确
检查commands.js中的cy.login是否用Cypress官方方式定义，格式必须为：
```
Cypress.Commands.add('login', (username, password) => {
  // 你的登录实现逻辑
})
```
不要写成普通函数，否则Cypress无法识别为全局自定义命令。
对齐本地与CI的Cypress版本
检查package.json中Cypress的版本是否锁定，确保CI安装的版本和本地完全一致。不同版本的Cypress对自定义命令的加载逻辑可能有差异（比如旧版本需在plugins目录配置，新版本在support目录导入）。
调试CI的配置加载状态
在CI测试命令前添加调试步骤，比如执行cypress info或cypress config，查看日志中显示的配置文件路径、支持文件路径是否正确。也可以在e2e.js中添加console.log('Commands file loaded')，通过CI日志确认文件是否被执行。