Next.js应用无法读取.env值：VercelPostgres连接字符串缺失排查

可能的原因 #

• .env文件位置错误或命名不符合框架要求（比如用了.env.dev而非框架默认的.env/.env.local）
• 环境变量名拼写错误，必须严格为POSTGRES_URL（大小写敏感）
• 本地开发服务器未重启，导致新添加的环境变量未被加载
• Vercel控制台未配置对应环境变量，或配置后未重新部署
• 代码中读取环境变量的场景错误（比如在客户端组件中读取服务器环境变量）

本地环境修复步骤 #

• 检查.env文件：确保文件位于项目根目录，文件名正确（多数框架默认加载根目录的.env或.env.local），变量名严格为POSTGRES_URL，值为完整的连接字符串（无需额外加引号）
• 重启开发服务器：修改.env文件后，必须重启框架的开发服务（比如Next.js的npm run dev需要停止后重新启动），否则新变量不会被加载
• 验证变量读取：在服务器端代码的最上方添加console.log(process.env.POSTGRES_URL)，启动服务后查看控制台输出。如果输出为undefined，说明框架未读取到变量，需检查框架的环境变量配置规则
• 确保代码调用场景正确：使用@vercel/postgres时，必须在服务器组件、API路由或Server Action中调用，禁止在客户端组件中直接使用（客户端无法访问服务器环境变量），示例代码：

  import { sql } from '@vercel/postgres';
  
  // 仅在服务器端执行
  async function fetchData() {
    const { rows } = await sql`SELECT * FROM your_table`;
    return rows;
  }
  

Vercel环境修复步骤 #

• 配置环境变量：登录Vercel控制台，进入项目的Settings > Environment Variables，添加POSTGRES_URL变量，值复制自Vercel Postgres数据库详情页的连接字符串
• 选择环境范围：根据需求勾选Production/Development/Preview，确保对应环境能读取到变量
• 重新部署项目：环境变量修改后，必须在Vercel的Deployments页面触发重新部署，否则新变量不会生效
• 检查集成状态：如果是通过Vercel官方集成添加的Postgres，系统会自动注入POSTGRES_URL，若未自动注入，需手动添加变量

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