next.js 中仅以 next_public_ 开头的环境变量才能在客户端安全访问；若 mongodb 变量未加此前缀，会导致服务端与客户端渲染不一致，引发 hydration 错误并跳转登录页。
在 Next.js 项目中（尤其是 App Router 或 Pages Router 的 SSR/SSG 场景），环境变量的可见性严格遵循命名约定：只有以 NEXTPUBLIC 为前缀的变量才会被注入到浏览器端 JavaScript 中。你提到的 .env.local 文件中存放的是 MongoDB 相关环境变量（如 MONGODB_URI, MONGODB_DB_NAME），但这类敏感后端配置本就不应暴露在前端代码中——一旦错误地将其直接用于客户端逻辑（例如在组件或 useEffect 中读取 process.env.MONGODB_URI），Next.js 会因服务端渲染（SSR）时该值为 undefined，而客户端 hydration 时尝试读取却得到 undefined（或空字符串），导致 DOM 内容不匹配，最终触发经典的 React Hydration 错误：
Error: Text content does not match server-rendered HTML.
更关键的是，这种误用还可能绕过认证逻辑——比如你本想通过环境变量控制某页面是否“免登录”，却在客户端 JS 中直接判断 if (process.env.NEXT_PUBLIC_ALLOW_DESIGN_MODE)，而该变量因未正确声明始终为 undefined，致使授权逻辑失效，强制跳转至登录页。
✅ 正确做法如下：
-
区分环境变量用途：
- ✅ 前端可读（如 API base URL、功能开关）→ 必须以 NEXT_PUBLIC_ 开头，例如：
# .env.local NEXT_PUBLIC_API_BASE_URL=https://api.example.com NEXT_PUBLIC_DESIGN_MODE=true
- ❌ 后端专用（如数据库连接串、密钥）→ 禁止加 NEXT_PUBLIC_ 前缀，仅限服务端使用（如 getServerSideProps, API routes, server actions, lib/db.ts）：
# .env.local —— 此类变量对浏览器完全不可见 MONGODB_URI=mongodb://... MONGODB_DB_NAME=myapp
- ✅ 前端可读（如 API base URL、功能开关）→ 必须以 NEXT_PUBLIC_ 开头，例如：
-
验证变量是否生效：
在页面组件中打印测试（仅用于调试，上线前移除）：// app/page.tsx 或 pages/index.tsx export default function Home() { console.log('Frontend env:', { publicVar: process.env.NEXT_PUBLIC_DESIGN_MODE, privateVar: process.env.MONGODB_URI, // → undefined in browser! }); return <div>UI Design Mode: {process.env.NEXT_PUBLIC_DESIGN_MODE}</div>; } -
解决 Hydration 错误：
若已误将非公共变量用于客户端渲染，请立即修正，并确保 UI 分支逻辑不依赖服务端专属变量。对于需要“跳过登录”的设计模式，推荐统一使用公共开关：// 使用安全的公共变量控制路由行为 import { redirect } from 'next/navigation'; export default function ProtectedPage() { const isDesignMode = process.env.NEXT_PUBLIC_DESIGN_MODE === 'true'; if (!isDesignMode && !isAuthenticated()) { redirect('/login'); } return <DesignCanvas />; }
⚠️ 注意事项：
- .env.local 默认已被 .gitignore 排除，无需额外操作；
- 修改 .env.local 后必须重启开发服务器（next dev）才能生效；
- 不要将 NEXT_PUBLIC_ 前缀加在敏感信息上（如 NEXT_PUBLIC_MONGODB_URI），这会严重泄露数据库凭证；
- 若需在客户端调用后端 API，请通过 /api/* 路由中转，而非直连数据库。
总结：Hydration 错误往往是环境变量误用的表象，根源在于前后端执行上下文差异。严格遵守 NEXT_PUBLIC_ 命名规范，明确变量作用域，是保障 Next.js 应用稳定渲染与安全性的基础前提。
