next.js 中非 `next_public_` 前缀的环境变量无法在客户端访问，若在组件中直接读取私有环境变量（如 mongodb 连接配置），会导致服务端与客户端渲染内容不一致，从而触发 react hydration 错误。

在 Next.js（尤其是 App Router 或 Pages Router）中，环境变量的可见性严格区分服务端与客户端：只有以 NEXT_PUBLIC_ 开头的变量才会被注入到浏览器环境中；其余变量（如 MONGODB_URI、DB_NAME 等）仅限服务端使用（例如 API 路由、getServerSideProps、服务端组件 async 组件逻辑等）。而你在 .env.local 中配置的是 MongoDB 相关变量——这类敏感信息本就不应暴露给前端，但若在客户端组件（如 useEffect、JSX 内联逻辑或客户端渲染的 UI 判断中）错误地引用了它们（例如 process.env.MONGODB_URI），就会导致：

• 服务端渲染时该值为真实字符串（如 “mongodb://…”）；
• 客户端 hydration 时该值为 undefined（因未暴露）；
• React 检测到 DOM 文本不匹配，抛出 Text content does not match server-rendered HTML 错误。

✅ 正确做法如下：

1. 确认变量用途，严格隔离环境变量作用域

   • ✅ 允许客户端访问（如 API 基地址、功能开关）→ 使用 NEXT_PUBLIC_API_BASE_URL
   • ❌ 禁止客户端访问（如数据库连接串、密钥、管理 Token）→ 仅用于服务端逻辑，绝不在 ‘use client’ 组件或浏览器端 JS 中直接读取

2. 检查你的登录/授权逻辑是否误用了私有变量
   例如，以下代码是危险且错误的：

   // ❌ 错误：在客户端组件中读取私有 env 变量
   'use client';
   export default function ProtectedPage() {
     const isAuthorized = process.env.MONGODB_URI !== undefined; // → 服务端为真，客户端为 undefined！
     return isAuthorized ? 
   Welcome
    : ;
   }

   ✅ 正确方式是将权限判断移至服务端：

   

   ChartGen

   AI快速生成专业数据图表

   下载

   // ✅ 正确：服务端组件（默认）中安全使用
   export default async function ProtectedPage() {
     // 此处 process.env.MONGODB_URI 可用（仅服务端执行）
     const isConnected = await checkMongoConnection(); // 自定义服务端校验逻辑
     if (!isConnected) {
       redirect('/login');
     }
     return 
   Welcome — UI Design Zone
   ;
   }

3. 验证 .env.local 是否生效

   • 确保文件位于项目根目录（与 next.config.js 同级）；
   • 文件名必须为 .env.local（注意开头的点，且无其他后缀）；
   • 变量格式为 KEY=VALUE，不能有空格、引号或注释：

     # ❌ 错误
     NEXT_PUBLIC_ENV = "dev"
     # ✅ 正确
     NEXT_PUBLIC_ENV=dev
     MONGODB_URI=mongodb+srv://user:pass@cluster.net/db?retryWrites=true

4. 重启开发服务器
   Next.js 仅在启动时加载 .env.* 文件。修改后务必执行：

   npm run dev   # 或 yarn dev / pnpm dev

⚠️ 特别提醒：

• .env.local 默认被 .gitignore 忽略，这是安全设计，请勿提交到仓库；
• 若需在 CI/CD 中使用环境变量，请通过平台（Vercel、GitHub Actions 等）配置，而非硬编码或上传 .env 文件；
• Hydration 错误本质是 SSR/CSR 不一致，除环境变量外，还需排查 Date.now()、Math.random()、window 对象访问等客户端独有行为是否混入服务端渲染路径。

只要确保授权逻辑完全运行于服务端，并仅通过 NEXT_PUBLIC_* 变量向 UI 传递必要、安全的配置，你就能绕过登录页，立即投入 UI 设计工作。

https://www.php.cn/faq/1986936.html