使用Zod在Next.js中验证环境变量时遇无效报错求助

问题详情 #

使用Zod库验证环境变量时，持续收到「环境变量无效」的报错，已卡一整天。相关信息如下：

报错截图 #

验证代码 #

import { z } from 'zod'

const envSchema = z.object({
  SUPABASE_URL: z.string().url(),
  SUPABASE_KEY: z.string().min(1),
})

const envParsed = envSchema.safeParse(process.env)

if (envParsed.success === false) {
  console.error('❌ Invalid environment variables', envParsed.error.format())

  throw new Error('Invalid environment variables.')
}

export const env = envParsed.data

环境变量配置 #

已在.env.local文件中定义相关变量：

排查与解决方案 #

1. 确认环境变量是否被正确加载 #

Zod验证的是process.env，如果.env.local未被加载，process.env中就不会有对应变量，直接导致验证失败：

• 若使用Next.js，.env.local会自动加载；若为其他框架/原生Node.js，需手动配置dotenv：
  1. 安装依赖：npm install dotenv --save-dev
  2. 在验证代码最顶部添加：

     import dotenv from 'dotenv'
     dotenv.config({ path: '.env.local' })
     

• 构建阶段验证时（比如Next.js的env.mjs），需确保构建流程能读取到.env.local的变量。

2. 检查环境变量格式 #

从报错看，SUPABASE_URL触发了「invalid url」验证失败，常见原因：

• 变量值前后有空格：比如.env.local中写SUPABASE_URL= https://xxx.supabase.co（注意开头空格），需删除前后空格。
• URL格式错误：比如遗漏http/https前缀、拼写错误（如htpps）。

3. 打印变量确认加载状态 #

在验证代码前添加打印，确认变量是否真的被加载：

console.log('已加载的环境变量:', {
  SUPABASE_URL: process.env.SUPABASE_URL,
  SUPABASE_KEY: process.env.SUPABASE_KEY
})

若打印结果为undefined，回到步骤1解决加载问题；若有值，再检查值的格式是否符合Zod规则。

4. 调整Zod验证规则（可选） #

如果SUPABASE_URL是特殊格式（比如本地开发的非标准URL），可放宽验证规则：

// 仅验证为字符串
SUPABASE_URL: z.string(),
// 或自定义验证逻辑
SUPABASE_URL: z.string().refine(val => val.startsWith('https://') || val.startsWith('http://'), {
  message: 'SUPABASE_URL必须以http/https开头'
})

内容的提问来源于stack exchange，提问作者patrick-ts