Cypress项目process.env变量读取为undefined问题咨询

核心问题本质是Cypress 存在 Node 服务端、浏览器客户端两个独立运行上下文，.env 文件默认不会被自动加载到浏览器侧，Project A 能正常运行是配置巧合生效，Project B 触发了 Cypress 环境变量的加载规则限制。 #

根因拆解 #

• Cypress 本身没有内置 .env 文件自动解析能力，process.env 在 Node 上下文（cypress 配置文件、plugins 脚本执行环境）和浏览器上下文（测试用例、support 支持文件、自定义命令执行环境）是完全隔离的两套对象：
  1. 配置文件、plugins 里的 process.env 是 Node 原生对象，只要正确加载 dotenv 就能读到 .env 里的变量
  2. 测试代码、自定义命令里的 process 是 Cypress 做的浏览器端 polyfill，默认只会注入系统环境变量中带 CYPRESS_ 前缀的变量，不会自动读取项目下 .env 文件的内容
• 两个项目依赖、.env 配置一致但表现不同，99% 概率是 Project A 的 cypress 配置文件中提前写了 dotenv 加载+变量透传逻辑，Project B 复制项目时遗漏了该段配置，仅同步了依赖和 .env 文件。
• 你在 Project B 自定义命令外层、回调里直接读取 process.env.apiKey，代码执行在浏览器上下文，本身就拿不到未经过透传的 .env 变量。

修复步骤 #

1. 在 cypress 配置文件顶部显式加载 .env
   打开项目下的 cypress.config.js（老版本对应 cypress/plugins/index.js），在最顶部添加 dotenv 加载逻辑，显式指定 .env 路径避免工作目录导致的加载失败：

   const path = require('path')
   require('dotenv').config({ path: path.resolve(__dirname, '.env') })
   const { defineConfig } = require('cypress')
   
   module.exports = defineConfig({
     e2e: {
       setupNodeEvents(on, config) {
         // 将Node侧读取到的环境变量透传给浏览器侧Cypress.env
         config.env.apiKey = process.env.apiKey
         config.env.authToken = process.env.authToken
         return config
       },
       // 其余原有配置保持不变
     }
   })
   

2. 测试代码统一用 Cypress.env() 读取变量，不要直接用 process.env
   浏览器侧的自定义命令、测试用例里不要依赖 process.env 读取自定义变量，统一用 Cypress 提供的 env 方法读取：

   Cypress.Commands.add('createBoard', (name) => {
     cy
       .request('POST', 'boards', { 
         name, 
         key: Cypress.env('apiKey'), 
         token: Cypress.env('authToken') 
       })
       .then(({ body }) => {
         Cypress.env('boards').push(body)
       })
   })
   

3. 快速校验是否加载成功
   启动 Cypress 后，在测试用例里加一句 cy.log(Cypress.env()) 打全量环境变量，确认 apiKey、authToken 存在即可。

额外注意：如果不想写透传逻辑，也可以直接把 .env 里的变量名改成带 CYPRESS_ 前缀，比如 CYPRESS_apiKey=MY_KEY，Cypress 会自动把这类变量注入到浏览器侧的 Cypress.env('apiKey') 中，但这种方式不适合存敏感信息，不推荐生产环境使用。

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