Next-Forge项目环境变量配置指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00729/article/details/148488537

Next-Forge项目环境变量配置指南

next-forge A production-grade boilerplate for modern Next.js apps. 项目地址: https://gitcode.com/gh_mirrors/ne/next-forge

环境变量系统概述

Next-Forge采用了一套可组合的环境变量系统，这套系统允许开发者为每个模块定义并验证类型安全的环境变量，然后将这些变量组合成应用程序的统一环境配置。这种设计既保证了开发时的类型安全，又确保了运行时的变量有效性。

核心特性解析

类型安全验证机制

项目使用@t3-oss/env-nextjs库来实现环境变量的运行时验证和自动补全功能。这个库提供了强大的类型检查能力，确保：

所有环境变量在使用前都经过严格验证
开发时能获得完善的代码提示
避免因变量类型错误导致的运行时问题

模块化环境配置

每个模块都可以在自己的keys.ts文件中定义专属的环境变量。这些变量会被明确分为两类：

server：仅在服务端可用的变量
client：可在客户端使用的变量

这种分类方式既保证了安全性（敏感变量不会泄露到前端），又提供了必要的灵活性。

环境变量文件结构

项目初始化脚本会自动创建多个环境变量模板文件，开发者需要根据实际需求填充这些文件：

应用层配置：
- app/.env.local - 主应用配置
- web/.env.local - Web应用配置
- api/.env.local - API服务配置
功能模块配置：
- packages/database/.env - 数据库连接配置
- packages/cms/.env.local - 内容管理系统配置
- packages/internationalization/.env.local - 国际化相关配置

专业提示：项目正在逐步减少模块级别的环境文件，建议开发者关注后续更新。

验证规则最佳实践

每个模块的keys.ts文件都包含了详尽的环境变量验证规则。这些规则不仅用于运行时验证，也作为开发文档使用。验证规则的设计应遵循以下原则：

尽可能具体明确：如果知道某个供应商密钥以"sec_"开头，就应该设置相应的验证规则
包含必要的长度检查：避免空值导致的运行时错误
考虑格式要求：如URL、邮箱等特殊格式应设置相应验证

示例验证规则：

z.string().min(1).startsWith('sec_')

集成环境变量处理

项目会自动处理来自各种集成的环境变量，例如：

监控工具集成（如Sentry）会自动添加SENTRY_前缀的变量
部署平台（如Vercel）会提供VERCEL_PROJECT_PRODUCTION_URL等实用变量
CI/CD系统注入的构建时变量

这些变量无需手动配置，但开发者应该了解它们的来源和用途。

添加新环境变量步骤

要添加一个新的环境变量，需要完成以下两个步骤：

文件配置：
- 在相关模块的.env.local文件中添加变量定义
- 确保所有相关环境文件都同步更新
类型声明：
- 在对应模块的keys.ts文件中添加变量声明
- 明确指定变量属于server还是client范畴
- 设置适当的验证规则

示例添加过程：

// 在keys.ts中添加
export const keys = createEnv({
  server: {
    NEW_API_KEY: z.string().min(32),
    // 其他服务端变量...
  },
  client: {
    PUBLIC_API_URL: z.string().url(),
    // 其他客户端变量...
  },
})