企业官网建设流程全解析

类型安全问题：环境变量没有类型检查，容易在运行时出错

验证缺失：无法确保必需的环境变量都已正确配置

客户端/服务端混淆：可能意外将敏感变量暴露到客户端

团队协作困难：新成员不知道需要配置哪些环境变量

T3 Env 正是为了解决这些问题而生，它提供了类型安全的环境变量管理方案。

server variables

client variables

shared variables

非法/缺失

.env

.env.local

…

src/env.js

createEnv({…})

Zod Schema

校验层

服务端代码

getStaticProps / API Routes …

客户端代码

浏览器 Bundle

两端共享

NODE_ENV …

运行时抛错

构建失败

核心特性

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 项目。

创建 env.js 文件：

import { createEnv } from "@t3-oss/env-nextjs";

import { z } from "zod";

export const env = createEnv({

server: {

// 服务端专用环境变量

DATABASE_URL: z.string().url(),

GITHUB_CLIENT_SECRET: z.string().min(1),

NODE_ENV: z.enum(["development", "test", "production"]),

},

client: {

// 客户端可访问的环境变量

NEXT_PUBLIC_API_BASE_URL: z.string().url(),

NEXT_PUBLIC_APP_VERSION: z.string().min(1),

},

// 运行时环境变量映射

runtimeEnv: {

DATABASE_URL: process.env.DATABASE_URL,

GITHUB_CLIENT_SECRET: process.env.GITHUB_CLIENT_SECRET,

NODE_ENV: process.env.NODE_ENV,

NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,

NEXT_PUBLIC_APP_VERSION: process.env.NEXT_PUBLIC_APP_VERSION,

},

// 跳过某些环境变量的验证（可选）

skipValidation: !!process.env.SKIP_ENV_VALIDATION,

});

高级验证场景

const env = createEnv({

server: {

// 复杂验证规则

PORT: z.string().regex(/^\d+$/).transform(Number),

FEATURE_FLAGS: z.string().transform((str) => str.split(',')),

MAX_UPLOAD_SIZE: z.string().default('10').transform(Number),

// 条件验证

DATABASE_URL: z.string().url().optional(),

DATABASE_HOST: z.string().min(1).optional(),

}).refine(

(data) => data.DATABASE_URL || data.DATABASE_HOST,

"Either DATABASE_URL or DATABASE_HOST must be provided"

),

});

实际应用

API 路由中的使用

// pages/api/users.ts

import { env } from "../../env";

import { NextApiRequest, NextApiResponse } from "next";

export default async function handler(

req: NextApiRequest,

res: NextApiResponse

) {

// 类型安全的环境变量访问

const databaseUrl = env.DATABASE_URL;

const apiSecret = env.API_SECRET;

// 业务逻辑...

res.status(200).json({ success: true });

}

客户端组件中的使用

// components/UserProfile.tsx

import { env } from "../env";

export function UserProfile() {

// 只能访问客户端环境变量

const apiUrl = env.NEXT_PUBLIC_API_BASE_URL;

return (

<div>

<p>API Base URL: {apiUrl}</p>

</div>

);

}

与 Next.js 配置集成

// next.config.js

const { env } = require("./env");

/** @type {import('next').NextConfig} */

const nextConfig = {

env: {

CUSTOM_KEY: "value",

},

publicRuntimeConfig: {

apiUrl: env.NEXT_PUBLIC_API_BASE_URL,

},

};

module.exports = nextConfig;

真实案例

create-t3-app

create-t3-app 是一个快速构建全栈 TypeScript 应用的脚手架，集成了 Next.js、tRPC、Prisma、Tailwind CSS 等现代工具。它以“强类型、可扩展、开发体验优先”为核心理念，帮助开发者快速搭建高质量的 Web 应用。

nahida-template

我搭建的 nahida-template，就用到了 @t3-oss/env-core。nahida-template 是基于 Elysia.js、Next.js 16 和 TypeScript 的现代全栈单仓模板，提供高性能与端到端类型安全支持。欢迎 star 和提建议。

import { createEnv } from "@t3-oss/env-core"

import { z } from "zod"

export const env = createEnv({

shared: {

NODE_ENV: z

.enum(["development", "production", "test"])

.default("development"),

PORT: z.number().default(3001),

},

/**

* Specify your server-side environment variables schema here. This way you can ensure the app

* isn't built with invalid env vars.

*/

server: {

NODE_ENV: z

.enum(["development", "test", "production"])

.default("development"),

DATABASE_URL: z.string().url(),

BETTER_AUTH_SECRET: z.string(),

BETTER_AUTH_URL: z.string().url(),

GITHUB_CLIENT_ID: z.string(),

GITHUB_CLIENT_SECRET: z.string(),

},

/**

* You can't destruct `process.env` as a regular object in the Next.js edge runtimes (e.g.

* middlewares) or client-side so we need to destruct manually.

*/

runtimeEnv: {

NODE_ENV: process.env.NODE_ENV,

DATABASE_URL: process.env.DATABASE_URL,

BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,

BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,

GITHUB_CLIENT_ID: process.env.GITHUB_CLIENT_ID,

GITHUB_CLIENT_SECRET: process.env.GITHUB_CLIENT_SECRET,

// NEXT_PUBLIC_CLIENTVAR: process.env.NEXT_PUBLIC_CLIENTVAR,

},

/**

* Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially

* useful for Docker builds.

*/

skipValidation: !!process.env.SKIP_ENV_VALIDATION,

/**

* Makes it so that empty strings are treated as undefined. `SOME_VAR: z.string()` and

* `SOME_VAR=''` will throw an error.

*/

emptyStringAsUndefined: true,

})

性能与安全考量

性能

环境变量验证只在启动时进行一次

支持设置 skipValidation: true 跳过运行时验证

使用环境变量缓存避免重复初始化

安全最佳实践

永远不要将敏感信息提交到版本控制

使用不同的密钥用于开发、测试和生产环境

定期轮换密钥和密码

使用密钥管理服务（如 AWS Secrets Manager）

总结