Next.js 14（App Router）服务端与客户端组件如何正确访问私有环境变量？

1. 访问私有环境变量的正确方式 #

私有环境变量（不带NEXT_PUBLIC_前缀）仅能在服务端环境中访问，Next.js不会将这类变量打包到客户端代码中，以此避免敏感信息泄露。支持访问的服务端场景包括：

• 服务端组件（App Router默认组件均为服务端组件，未添加'use client'指令的组件）
• API路由（app/api/目录下的路由文件）
• Server Actions
• Middleware（middleware.ts文件）

示例：服务端组件中正确获取私有变量

// app/page.tsx（默认是服务端组件，无'use client'指令）
export default function Home() {
  console.log(process.env.SECRET_KEY); // 服务端运行时可正常读取
  return <h1>Hello World</h1>;
}

示例：API路由中使用私有变量

// app/api/secret/route.ts
export async function GET() {
  const secret = process.env.SECRET_KEY;
  return new Response(`Secret value: ${secret}`);
}

2. 让SECRET_KEY在服务端正常可用的注意事项 #

Next.js 14内置了dotenv支持，无需额外安装dotenv包，出现undefined通常是以下细节问题导致，无需特殊配置，只需逐一排查：

• 确认.env.local文件放在项目根目录（与next.config.js、package.json同级）
• 检查变量名拼写完全一致（比如是否误写为SECRET_KEYS而非SECRET_KEY）
• 变量值不要添加多余空格或引号：正确写法是SECRET_KEY=mySecret，避免SECRET_KEY= "mySecret"或SECRET_KEY='mySecret'格式
• 修改.env.local后必须完全重启开发服务器：关闭当前运行的npm run dev进程，再重新启动，热重载不会加载新的环境变量
• 确认组件未被标记为客户端组件：如果组件顶部添加了'use client'指令，会转为客户端组件，无法访问私有变量

内容的提问来源于stack exchange，提问作者Santiago Gómez de la Torre