Next.js项目Playwright测试如何正确加载.env.local环境变量

配置不生效的核心问题有三个：

• 裸调用require("dotenv").config()默认只会加载项目根目录下的.env文件，不会自动识别Next.js约定使用的.env.local文件
• 环境变量加载逻辑如果写在配置文件的非顶部位置，会在配置初始化完成后才执行，此时process.env上还没有挂载对应值，use块里拿到的自然是undefined
• Next.js对客户端侧可访问的环境变量有强制前缀要求，非NEXT_PUBLIC_开头的变量不会注入到浏览器运行时，直接在页面上下文读取必然拿到undefined

方案1：手动指定dotenv加载路径（无额外依赖） #

把dotenv加载逻辑放到playwright.config.js的最顶部，明确指定要加载的环境变量文件路径，和Next.js的环境变量加载优先级保持一致：

// 以下代码必须放在playwright.config.js的最顶部，所有其他配置逻辑之前
const dotenv = require('dotenv');
const path = require('path');

// 优先加载.env.local的配置，覆盖.env里的同名变量
dotenv.config({ path: path.resolve(__dirname, '.env.local') });
// 兜底加载.env文件的通用配置
dotenv.config({ path: path.resolve(__dirname, '.env') });

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  // 其余基础配置（testDir、webServer等）
  use: {
    // 显式把需要的环境变量注入到测试上下文
    FOO: process.env.FOO,
    // 注意：客户端页面可访问的变量必须以NEXT_PUBLIC_开头，对应读取process.env.NEXT_PUBLIC_XXX
  },
};

module.exports = config;

测试用例里读取变量分两种场景：

• 注入到use块的变量，通过测试fixture直接获取：

test('读取环境变量示例', async ({ page, FOO }) => {
  console.log(FOO); // 可直接拿到配置的变量值
});

• 测试逻辑里的Node侧代码（比如接口请求、服务端操作），可以直接通过process.env.FOO读取，只要顶部加载逻辑正确就能拿到值。

方案2：通过脚本指定env文件（配置更简洁） #

如果不想在配置文件里写路径逻辑，可以安装dotenv-cli，直接在测试脚本里指定要加载的env文件，不需要手动在config里引入dotenv：

1. 安装依赖：npm i -D dotenv-cli
2. 修改package.json里的测试脚本：

{
  "scripts": {
    "test:e2e": "dotenv -e .env.local -- playwright test"
  }
}

• 变量名严格区分大小写：process.env.foo和process.env.FOO是两个完全不同的值，必须和env文件里定义的变量名完全一致
• 修改env文件后必须重启Playwright测试进程，热更新不会重新加载环境变量
• 不要在page.evaluate这类浏览器执行上下文里直接读非NEXT_PUBLIC_开头的服务端环境变量，这类变量本身不会被Next.js打包到客户端代码里，需要在Node侧读取后作为参数传入
• Monorepo场景下建议先打印path.resolve(__dirname, '.env.local')确认加载路径和env文件实际存放路径一致，避免因为目录层级问题加载失败

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