Next.js 15环境变量初始化失败，咨询正确配置方式

Next.js 15 不再推荐使用 next/env 包初始化环境变量，改用了更简洁的内置机制，同时对客户端可访问的变量有明确规则，以下是具体配置方式：

一、环境文件基础配置 #

依然使用 .env.local、.env.development、.env.production 这类文件存储环境变量，但要记住：

• 客户端可访问的变量必须加 NEXT_PUBLIC_ 前缀，比如 NEXT_PUBLIC_API_URL=https://your-api.com
• 不带前缀的变量仅能在服务端代码（Server Components、API路由、Server Actions）中使用

二、服务端代码访问变量 #

服务端代码里无需额外初始化，直接用 process.env.变量名 访问即可，示例：

// Server Component 或 API 路由文件
export default function ServerSidePage() {
  const secretKey = process.env.API_SECRET_KEY; // 无NEXT_PUBLIC前缀，仅服务端可用
  return <div>服务端密钥：{secretKey}</div>;
}

Next.js 15会自动在服务端加载所有环境变量，不用再调用 next/env 的相关方法。

三、客户端代码访问变量 #

客户端代码（Client Components、客户端钩子等）只能访问带 NEXT_PUBLIC_ 前缀的变量，直接通过 process.env.NEXT_PUBLIC_变量名 访问，示例：

'use client';

export default function ClientSidePage() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  return <div>API地址：{apiUrl}</div>;
}

同样不需要导入 next/env，框架会在构建时自动把这些前缀变量注入客户端代码。

四、常见问题排查 #

如果变量返回 undefined，按以下步骤检查：

• 确认客户端变量加了 NEXT_PUBLIC_ 前缀，服务端变量不用加
• 环境文件放在项目根目录，文件名正确（比如 .env.local 而非 .env）
• 修改环境变量后重启 next dev 开发服务器，开发模式下不会自动重载环境变量
• 检查 .gitignore，确保没有误删需要的环境文件（.env.local 建议忽略，.env.development 若为共享配置可以保留）

五、关于 next/env 的替代 #

之前用 next/env 的 loadEnvConfig 手动加载变量的场景，在Next.js 15里直接删掉相关代码即可。如果是自定义脚本这类特殊场景需要手动加载，可以用Node.js原生的 dotenv 包，但一般框架自动处理足够用。

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