快速开始
前置要求
- 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 应用:http://localhost:3000
- API 服务:http://localhost:3001
- 文档站点:http://localhost:3003
环境变量管理
概述
项目中各应用独立管理环境变量:
- 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_URL | string (URL) | - | PostgreSQL 连接字符串 |
NODE_ENV | enum | development | 运行环境 |
Admin 应用 (apps/admin/.env):
| 变量名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
NODE_ENV | enum | development | 运行环境 |
NEXT_PUBLIC_APP_URL | string (URL) | - | Admin 应用公开 URL |
API 应用 (apps/api/.env):
| 变量名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
PORT | number | 3001 | API 服务端口 |
HOST | string | localhost | API 服务主机 |
优势
类型安全
TypeScript 在编译时捕获错误,提供自动补全
运行时验证
Zod schema 在应用启动时验证所有环境变量
防止泄露
Client/Server 分离,防止服务端密钥泄露到客户端
早期发现
缺失或无效的变量会导致构建失败(fail-fast)