已在.env.local定义环境变量，为何校验仍失败？

问题场景 #

在.env.local文件中定义了STRIPE_SECRET_KEY变量，但在lib/utils.ts中执行以下校验代码时始终抛出错误：

if (!process.env.STRIPE_SECRET_KEY) {
  throw new Error("Error");
}

尽管变量已正确定义，且校验前打印能成功输出密钥，但最终仍触发错误。尝试过引入dotenv指定.env.local路径，问题依旧。使用版本为Next.js v15.0.3-canary.2。

排查与解决方法 #

• 检查系统环境变量是否覆盖本地配置
  Next.js环境变量加载优先级中，系统环境变量会覆盖.env.local中的变量。在终端执行对应命令确认：

  • Linux/macOS: echo $STRIPE_SECRET_KEY
  • Windows: echo %STRIPE_SECRET_KEY%
    若系统层面存在同名变量，删除或重命名后重启服务。

• 确认代码运行环境
  服务器端代码无需给变量加NEXT_PUBLIC_前缀，但如果这段校验逻辑被客户端组件调用，客户端环境无法访问未加前缀的服务器变量，会触发错误。将校验逻辑迁移到纯服务器端文件（如API路由、服务器组件）中。

• 清理Next.js缓存并重启
  预览版可能存在缓存异常，执行以下命令彻底清理后重启开发服务：

  rm -rf .next node_modules/.cache
  npm run dev
  

• 移除手动dotenv调用
  Next.js会自动加载.env.local等环境文件，手动调用dotenv.config()可能干扰内置加载逻辑，删除相关代码让框架自行处理。

• 校验.env.local格式
  确保变量定义无多余空格、引号，格式如下：

  STRIPE_SECRET_KEY=your_stripe_secret_key
  

补充说明 #

Next.js v15预览版在环境变量加载时机上可能存在调整，部分场景下变量注入滞后，导致代码执行时变量尚未完全初始化，但打印时已加载完成。遵循官方加载规则、避免自定义加载逻辑是最稳妥的解决方案。

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