Next.js 15.2.4环境变量返回Undefined问题求助

以下是针对你遇到的问题的排查和解决步骤：

1. 确认.env文件命名与位置 #

Next.js 默认优先加载项目根目录下的 .env.local 文件，而非 .env。如果你的文件是 .env，可以尝试：

• 将 .env 重命名为 .env.local
• 确保文件确实在项目根目录（和 package.json、next.config.js 同级），而非子目录中

2. 检查环境变量命名规则 #

• 若你的代码运行在客户端组件（比如添加了 "use client" 指令），则需要给环境变量加上 NEXT_PUBLIC_ 前缀，例如：

  NEXT_PUBLIC_TURSO_DATABASE_URL=your-url
  NEXT_PUBLIC_TURSO_AUTH_TOKEN=your-token
  

  但数据库操作建议放在服务器组件或API路由中，避免暴露敏感凭证。
• 服务器组件/API路由中无需前缀，直接使用原命名即可。

3. 清除Next.js缓存并重启服务 #

缓存可能导致环境变量未更新，执行以下操作：

• 删除项目根目录下的 .next 文件夹
• 停止本地服务后，重新运行 npm run dev（或对应的启动命令）

4. 验证环境变量是否正确加载 #

在你的数据库初始化代码中添加日志，确认变量是否存在：

import { drizzle } from "drizzle-orm/libsql";
import { createClient } from "@libsql/client";

// 临时添加日志排查
console.log("TURSO_DATABASE_URL:", process.env.TURSO_DATABASE_URL);
console.log("TURSO_AUTH_TOKEN:", process.env.TURSO_AUTH_TOKEN);

const turso = createClient({
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN,
});

export const db = drizzle(turso);

运行服务后查看终端输出，确认变量是否被正确读取。

5. 检查变量值格式 #

• 确保环境变量值不要加引号（无论单引号还是双引号），例如正确格式是 TURSO_DATABASE_URL=libsql://xxx.turso.io，而非 TURSO_DATABASE_URL="libsql://xxx.turso.io"
• 确保等号前后没有空格，避免出现 TURSO_DATABASE_URL= libsql://xxx.turso.io 这种带空格的错误格式

6. 检查Next.js版本与App Router兼容性 #

如果你使用的是Next.js 13+ App Router，确保数据库初始化代码运行在服务器组件中：

• 不要在组件中添加 "use client" 指令（除非必要）
• 若需要在客户端组件中调用数据库操作，通过API路由或Server Actions中转

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