如何在 Next.js 中安全配置 T3 Env 环境变量？

为什么需要专门的环境变量解决方案？ 在 Next.js 应用开发中，环境变量管理一直是个棘手问题。传统的 .env 文件方式存在诸多痛点： 类型安全问题：环境变量没有类型检查，容易在运行时出错 验证缺失：无法确保必需的环境变量都已正确配置 客户端/服务端混淆：可能意外将敏感变量暴露到客户端 团队协作困难：新成员不知道需要配置哪些环境变量 T3 Env 正是为了解决这些问题而生，它提供了类型安全的环境变量管理方案。 flowchart TD A[".env<br>.env.local<br>…"] --> B["src/env.js<br>createEnv({…})"] B --> C{Zod Schema<br>校验层} C -->|server variables| D["服务端代码<br>getStaticProps / API Routes …"] C -->|client variables| E["客户端代码<br>浏览器 Bundle"] C -->|shared variables| F["两端共享<br>NODE_ENV …"] C -->|非法/缺失| G["运行时抛错<br>构建失败"] style B fill:#FFE082 style C fill:#81C784 style G fill:#EF5350,color:#fff 核心特性 1. 类型安全的环境变量 import { createEnv } from "@t3-oss/env-nextjs"; import { z } from "zod"; const env = createEnv({ server: { DATABASE_URL: z.string().url(), API_SECRET: z.string().min(1), }, client: { NEXT_PUBLIC_API_URL: z.string().url(), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, API_SECRET: process.env.API_SECRET, NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL, }, }); 2. 运行时验证 库在应用启动时会自动验证所有环境变量，如果缺少必需变量或类型不匹配，会立即抛出清晰错误，而不是在运行时神秘崩溃。 3. 客户端/服务端自动隔离 通过明确的配置区分，确保服务端敏感变量不会意外泄漏到客户端。 配置指南 基础安装与配置 npm install @t3-oss/env-nextjs zod 注意：T3 Env 提供了多个包， 如 @t3-oss/env-nextjs 和 @t3-oss/env-core，分别用于 Next.js 和普通 Node.js 项目。