0Pricing
TypeScript Academy · 课时

环境变量类型与配置

校验并为环境变量指定类型；使用 NEXT_PUBLIC 暴露安全的客户端变量；集中管理服务器端和客户端配置。

环境变量类型与配置 是 CoddyKit 上的免费 TypeScript Academy 课时。 这是第 3 节课，共 3 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 3 节课。

简介

目标：集中管理经过验证的环境变量，并保持类型同步。您将使用 zod 解析 process.env，导出带类型的env对象，并只向客户端暴露 NEXT_PUBLIC_*。

  • 运行时验证
  • 服务器端与客户端的暴露范围
  • 单一事实来源

模式与解析器

分别为服务器端和客户端创建模式。在启动期间遇到无效配置时立即失败。

// app/lib/env.ts
import { z } from "zod"

const serverSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
  API_SECRET: z.string().min(1)
})

const clientSchema = z.object({
  NEXT_PUBLIC_API_BASE: z.string().url()
})

function parseEnv<T extends z.ZodTypeAny>(schema: T, source: Record<string, unknown>) {
  const r = schema.safeParse(source)
  if (!r.success) {
    console.error(r.error.format())
    throw new Error("Invalid environment variables")
  }
  return r.data as z.infer<T>
}

export const serverEnv = parseEnv(serverSchema, process.env)
export const clientEnv = parseEnv(clientSchema, process.env)

服务器端使用

服务器文件（路由处理程序、服务器组件）可以从 serverEnv 访问机密信息。绝不要将这些信息暴露给客户端。

// app/api/users/route.ts
import { NextResponse } from "next/server"
import { serverEnv } from "@/app/lib/env"

export async function GET() {
  // Safe to read secrets on the server
  const db = serverEnv.DATABASE_URL
  return NextResponse.json({ ok: true, dbConfigured: Boolean(db) })
}

客户端使用

客户端组件只能导入 clientEnv，其中包含 NEXT_PUBLIC_* 变量。机密信息绝不会发送到浏览器。

"use client"
import { clientEnv } from "@/app/lib/env"

export default function ApiBaseNotice() {
  return <small>API base: {clientEnv.NEXT_PUBLIC_API_BASE}</small>
}

环境类型声明

环境类型声明可以改善 process.env 的 DX，但不会在运行时进行验证——请继续保留 zod 检查。

// env.d.ts (optional hints; runtime validation still required)
/// <reference types="node" />

declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "test" | "production"
    DATABASE_URL?: string
    API_SECRET?: string
    NEXT_PUBLIC_API_BASE?: string
  }
}

最佳实践

最佳实践：

  • 绝不要在客户端文件中读取机密信息。
  • 在启动时验证一次；在非生产环境中快速终止，以便及时发现问题。
  • 将 env 访问集中到一个小型模块中，以保持一致性并便于测试。

env 类型检查

快速检查：环境变量类型声明与暴露的安全模式是什么？

回顾

回顾：使用 zod 解析 process.env，导出带类型的 serverEnv/clientEnv，并依靠 NEXT_PUBLIC_* 安全地向客户端暴露变量。

常见问题解答

「环境变量类型与配置」课时是免费的吗？

是的 — 「环境变量类型与配置」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 3 节课。

「环境变量类型与配置」这节课中我会学到什么？

校验并为环境变量指定类型；使用 NEXT_PUBLIC 暴露安全的客户端变量；集中管理服务器端和客户端配置。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 3 节。

「环境变量类型与配置」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. App Router 类型；服务器组件与客户端组件
  2. 数据获取与操作类型
  3. 环境变量类型与配置
← 返回 TypeScript Academy