GitHub Actions中Cypress步骤无法覆盖作业层级环境变量的问题

问题根源 #

Next.js的NEXT_PUBLIC_*前缀环境变量是构建时静态注入的，一旦项目完成构建（比如执行npm run build），这些变量的值就会被固化到生成的静态文件和客户端代码中。你在作业层级设置的staging值会在前期构建阶段被注入，后续Cypress步骤修改变量时，构建产物已经定型，自然不会生效。而echo能输出test只是因为当前步骤的shell环境变量被修改了，但和已构建的Next.js产物无关。

可行解决方案 #

1. 针对测试环境单独构建

在Cypress运行前，重新用test环境变量执行一次构建，确保产物里的NEXT_PUBLIC_APP_ENV是预期值。修改GitHub Actions的.yml配置：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      # 针对test环境重新构建，覆盖之前的staging变量
      - name: Build for test environment
        run: npm run build
        env:
          NEXT_PUBLIC_APP_ENV: test
      - name: Run Cypress tests
        run: npm run cypress:run
        env:
          NEXT_PUBLIC_APP_ENV: test

这样构建和测试阶段用的都是test变量，Cypress测试里就能读到正确的值。

2. 用Cypress自身环境变量替代Next.js注入

如果不想重复构建，可以跳过Next.js的NEXT_PUBLIC_变量注入，直接在Cypress里传递环境变量：

• 修改Cypress配置文件（cypress.config.js），启用环境变量接收：

  const { defineConfig } = require('cypress')
  
  module.exports = defineConfig({
    e2e: {
      env: {
        appEnv: process.env.APP_ENV || 'development'
      }
    }
  })
  

• 在GitHub Actions的Cypress步骤传递变量：

  - name: Run Cypress tests
    run: npm run cypress:run
    env:
      APP_ENV: test
  

• 在Cypress测试代码里用Cypress.env('appEnv')获取值，而不是process.env.NEXT_PUBLIC_APP_ENV。

3. 优化npm run dev的耗时问题

如果必须用dev模式，通过缓存减少重复构建时间：

• 在GitHub Actions中添加缓存步骤，缓存node_modules和.next文件夹：

  - name: Cache dependencies and build artifacts
    uses: actions/cache@v3
    with:
      path: |
        node_modules
        .next/cache
      key: ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}-${{ hashFiles('next.config.js') }}
  

  这样后续构建可以复用缓存，大幅缩短dev模式的启动时间。

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