dotenvx 在 Monorepo 环境中的最佳实践

背景介绍

dotenvx 是一个强大的环境变量管理工具，它可以帮助开发者安全地管理和使用环境变量。在现代前端开发中，Monorepo（多包仓库）架构越来越流行，特别是在使用 Turbo 或 Nx 等构建工具的项目中。然而，在这种架构下，环境变量的管理会面临一些独特的挑战。

Monorepo 中的环境变量管理挑战

在 Monorepo 项目中，通常会遇到以下环境变量管理问题：

1. 多层级环境变量：项目可能包含全局环境变量和特定应用的环境变量
2. 加载顺序问题：需要确保环境变量按照正确的顺序加载
3. 类型安全：在使用 TypeScript 时，需要确保环境变量的类型安全
4. 构建时环境变量注入：在构建过程中需要正确注入环境变量

dotenvx 的解决方案

1. 基本配置方法

对于简单的 Monorepo 项目，可以通过指定 --env-file 参数来明确指定环境变量文件的路径：

"scripts": {
  "build": "dotenvx run --env-file=packages/config/.env -- turbo build"
}

这种方法适用于环境变量集中管理的情况。

2. 多环境文件支持

对于需要同时使用全局和局部环境变量的场景，dotenvx 提供了更灵活的解决方案：

"scripts": {
  "build": "dotenvx run --env-file=packages/config/.env --env-file=apps/web/.env -- turbo build"
}

这种方式允许同时加载多个环境变量文件，并按照指定的顺序进行合并。

3. 与 Turbo 的深度集成

当使用 Turbo 构建工具时，可以充分利用其环境变量管理功能：

"globalEnv": [
  "DOTENV_KEY",
  "NODE_ENV"
],
"pipeline": {
  "build": {
    "dependsOn": ["^build"],
    "dotEnv": [".env"],
    "env": [
      "APP_SPECIFIC_VAR",
      "PUBLIC_CLIENT_VAR"
    ]
  }
}

这种配置方式可以实现环境变量的分层管理。

4. 类型安全集成

在与 TypeScript 项目结合使用时，推荐使用类型安全的环境变量库：

import { createEnv } from "@t3-oss/env-nextjs";
import { vercel } from "@t3-oss/env-core/presets";
import { z } from "zod";
import { nextEnv } from "@your-project/env-config";

export const env = createEnv({
  extends: [nextEnv, vercel],
  client: {
    NEXT_PUBLIC_CLIENT_VAR: z.string(),
  },
  server: {
    SERVER_ONLY_VAR: z.string(),
  },
  runtimeEnv: {
    SERVER_ONLY_VAR: process.env.SERVER_ONLY_VAR,
    NEXT_PUBLIC_CLIENT_VAR: process.env.NEXT_PUBLIC_CLIENT_VAR,
  },
});

这种方式可以确保环境变量的类型安全，并提供良好的开发体验。

最新功能进展

dotenvx 团队正在为 Monorepo 场景开发更强大的工具支持：

1. dotenvx ls：列出 Monorepo 中所有的环境变量文件
2. dotenvx encrypt [directory]：针对特定项目目录加密环境变量文件
3. 多环境密钥管理：支持管理多个 .env.keys 文件，便于团队协作

这些新功能将显著提升在 Monorepo 中管理环境变量的体验。

最佳实践建议

1. 分层管理：将环境变量分为全局和局部两个层级
2. 明确加载顺序：确保关键环境变量不会被意外覆盖
3. 类型安全：使用类型系统来验证环境变量
4. 加密敏感信息：对所有敏感环境变量进行加密处理
5. 文档化：为团队维护清晰的环境变量使用文档

通过遵循这些实践，可以在 Monorepo 项目中实现高效、安全的环境变量管理。