Skip to Content

快速开始

前置要求

  • Node.js: 22+
  • pnpm: 10.4+
  • PostgreSQL: 14+
  • Git: 最新稳定版

初始化项目

# 克隆仓库 git clone <repository-url> cd procure # 安装依赖 pnpm install # 设置环境变量 cp .env.example .env # 编辑 .env 文件,填入实际值 # 初始化数据库 pnpm db:generate pnpm db:push # 启动开发服务器 pnpm dev

访问:


环境变量管理

概述

项目中各应用独立管理环境变量:

  • Web 应用:使用 @t3-oss/env-nextjs 提供类型安全的环境变量验证
  • DB 包:使用 dotenv 直接加载环境变量
  • API 应用:直接使用 process.env 读取环境变量

配置结构

packages/db/ └── .env # 数据库环境变量值(使用 dotenv) apps/admin/ ├── env.ts # Admin 应用环境变量配置(@t3-oss/env-nextjs) └── .env # Admin 应用环境变量值 apps/api/ └── .env # API 应用环境变量值(直接使用 process.env)

使用方式

Admin 应用 (Next.js)

import { env } from "@/env"; // ✅ 服务端:可访问所有变量 export default function ServerPage() { const nodeEnv = env.NODE_ENV; const appUrl = env.NEXT_PUBLIC_APP_URL; return <div>...</div>; } // ✅ 客户端:只能访问 NEXT_PUBLIC_ 前缀的变量 "use client"; export function ClientComponent() { // ❌ 这会导致编译错误 // const nodeEnv = env.NODE_ENV; // ✅ 正确:客户端变量必须有 NEXT_PUBLIC_ 前缀 const appUrl = env.NEXT_PUBLIC_APP_URL; return <div>{appUrl}</div>; }

API 应用 (NestJS)

// 直接使用 process.env @Injectable() export class AppService { constructor() { const port = process.env.PORT || 3001; // 根据需要访问其他环境变量 } }

数据库包

// 数据库包直接使用 process.env const connectionString = process.env.DATABASE_URL;

添加新环境变量

1. 编辑配置文件

根据应用类型,编辑对应的配置文件:

Admin 应用 (apps/admin/env.ts):

export const env = createEnv({ server: { NODE_ENV: z.enum(["development", "production", "test"]).default("development"), // 添加新的服务端变量 STRIPE_SECRET_KEY: z.string().min(1).startsWith("sk_"), }, client: { NEXT_PUBLIC_APP_URL: z.string().url(), // 添加新的客户端变量 NEXT_PUBLIC_STRIPE_KEY: z.string().min(1).startsWith("pk_"), }, runtimeEnv: { NODE_ENV: process.env.NODE_ENV, STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY, NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_STRIPE_KEY: process.env.NEXT_PUBLIC_STRIPE_KEY, }, });

数据库包 (packages/db/.env):

  • 直接在 .env 文件中添加变量
  • 在代码中使用 process.env.YOUR_VAR 访问

API 应用:直接在 .env 文件中添加,在代码中使用 process.env.YOUR_VAR

2. 更新环境变量文件

在对应应用目录的 .env.env.example 中添加变量:

# apps/admin/.env.example # Payment Processing STRIPE_SECRET_KEY="sk_test_..." NEXT_PUBLIC_STRIPE_KEY="pk_test_..."

3. 添加实际值

# apps/admin/.env STRIPE_SECRET_KEY="sk_test_actual_key" NEXT_PUBLIC_STRIPE_KEY="pk_test_actual_key"

当前配置的环境变量

数据库包 (packages/db/.env):

变量名类型默认值说明
DATABASE_URLstring (URL)-PostgreSQL 连接字符串
NODE_ENVenumdevelopment运行环境

Admin 应用 (apps/admin/.env):

变量名类型默认值说明
NODE_ENVenumdevelopment运行环境
NEXT_PUBLIC_APP_URLstring (URL)-Admin 应用公开 URL

API 应用 (apps/api/.env):

变量名类型默认值说明
PORTnumber3001API 服务端口
HOSTstringlocalhostAPI 服务主机

优势

类型安全

TypeScript 在编译时捕获错误,提供自动补全

运行时验证

Zod schema 在应用启动时验证所有环境变量

防止泄露

Client/Server 分离,防止服务端密钥泄露到客户端

早期发现

缺失或无效的变量会导致构建失败(fail-fast)