英文文档
构建您的仓库

使用环境变量

了解如何在 Turborepo 中配置和使用环境变量，包括任务哈希、环境模式和 .env 文件处理。

环境变量输入是应用程序的重要组成部分，您需要在 Turborepo 配置中考虑它们。

在 Turborepo 中使用环境变量时有三个重要问题：

未能在配置中考虑环境变量可能导致使用错误配置发布应用程序。这可能导致严重问题，如将预览部署发布到生产环境。

Turborepo 还使用系统环境变量来配置自己的行为。下面，您将找到有关任务运行时环境变量以及它们如何影响任务哈希的信息。

将环境变量添加到任务哈希

Turborepo 需要了解您的环境变量以考虑应用程序行为的变化。为此，请在 turbo.json 文件中使用 env 和 globalEnv 键。

{
  "globalEnv": ["IMPORTANT_GLOBAL_VARIABLE"],
  "tasks": {
    "build": {
      "env": ["MY_API_URL", "MY_API_KEY"]
    }
  }
}
  • globalEnv：此列表中任何环境变量值的更改都将更改所有任务的哈希。
  • env：包括影响任务的环境变量值的更改，允许更好的粒度。例如，当 API_KEY 的值更改时，lint 任务可能不需要错过缓存，但 build 任务可能应该。

Turborepo 支持环境变量的通配符，因此您可以轻松考虑具有给定前缀的所有环境变量。访问 env 的 API 参考了解更多信息。

示例

以下是一些常见的环境变量配置示例：

{
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "env": ["API_*", "DATABASE_URL", "NEXT_PUBLIC_*"]
    },
    "test": {
      "env": ["TEST_*"]
    },
    "lint": {
      "env": []
    }
  }
}

在此示例中：

  • NODE_ENV 和 CI 影响所有任务
  • build 任务受以 API_ 开头的变量、DATABASE_URL 和以 NEXT_PUBLIC_ 开头的变量影响
  • test 任务仅受以 TEST_ 开头的变量影响
  • lint 任务不受任何特定环境变量影响

环境模式

Turborepo 有三种环境模式，用于确定如何处理环境变量：

strict 模式（推荐）

在 strict 模式下，Turborepo 只会将您在 env 和 globalEnv 中明确列出的环境变量传递给任务。这是最安全的模式，因为它确保您的任务只能访问您明确允许的环境变量。

{
  "experimentalEnvMode": "strict",
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "env": ["API_URL", "API_KEY"]
    }
  }
}

loose 模式

在 loose 模式下，Turborepo 会传递所有环境变量，但只有在 env 和 globalEnv 中列出的变量会影响任务哈希。

{
  "experimentalEnvMode": "loose",
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "env": ["API_URL", "API_KEY"]
    }
  }
}

infer 模式（默认）

这是默认模式，Turborepo 会尝试推断您的框架使用的环境变量。这种模式在大多数情况下都能正常工作，但可能不如 strict 模式安全。

处理 .env 文件

Turborepo 会自动检测和处理常见的 .env 文件模式：

  • .env
  • .env.local
  • .env.production
  • .env.development
  • .env.test

框架特定的 .env 文件

不同的框架有不同的 .env 文件约定：

.env
.env.local
.env.development
.env.production
.env.test

.env 文件优先级

环境变量的优先级顺序（从高到低）：

  1. 系统环境变量
  2. .env.local
  3. .env.{NODE_ENV}（例如 .env.production）
  4. .env

示例 .env 配置

# 全局变量
NODE_ENV=development
DATABASE_URL=postgresql://localhost:5432/mydb

# API 配置
API_URL=https://api.example.com
API_KEY=your-api-key

# 公共变量（Next.js）
NEXT_PUBLIC_APP_NAME=My App
NEXT_PUBLIC_VERSION=1.0.0

# 本地开发覆盖
API_URL=http://localhost:3001
DATABASE_URL=postgresql://localhost:5432/mydb_dev

最佳实践

1. 使用 strict 模式

为了最大的安全性和可预测性，建议使用 strict 模式：

{
  "experimentalEnvMode": "strict",
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "env": ["API_*", "NEXT_PUBLIC_*", "DATABASE_URL"]
    }
  }
}

2. 使用通配符

利用通配符来简化配置：

{
  "tasks": {
    "build": {
      "env": [
        "NEXT_PUBLIC_*",
        "REACT_APP_*",
        "VITE_*",
        "API_*"
      ]
    }
  }
}

3. 按任务分组环境变量

不同的任务可能需要不同的环境变量：

{
  "tasks": {
    "build": {
      "env": ["API_*", "DATABASE_URL", "NEXT_PUBLIC_*"]
    },
    "test": {
      "env": ["TEST_*", "DATABASE_TEST_URL"]
    },
    "lint": {
      "env": []
    },
    "dev": {
      "env": ["*"]
    }
  }
}

4. 文档化环境变量

在项目中创建 .env.example 文件来文档化所需的环境变量：

# 数据库配置
DATABASE_URL=postgresql://username:password@localhost:5432/database

# API 配置
API_URL=https://api.example.com
API_KEY=your-api-key-here

# 应用配置
NEXT_PUBLIC_APP_NAME=My Application
NEXT_PUBLIC_VERSION=1.0.0

# 可选配置
REDIS_URL=redis://localhost:6379
SMTP_HOST=smtp.example.com

故障排除

常见问题

  1. 任务缓存未按预期工作
    • 确保所有影响任务输出的环境变量都在 env 或 globalEnv 中列出
  2. 环境变量在任务中不可用
    • 在 strict 模式下，确保变量在 env 或 globalEnv 中列出
    • 检查 .env 文件是否正确加载
  3. 不同环境下的行为不一致
    • 验证所有环境都有正确的 .env 文件
    • 确保环境变量在所有部署环境中正确设置

调试环境变量

您可以使用以下命令来调试环境变量：

# 查看 Turborepo 检测到的环境变量
turbo run build --dry-run

# 查看特定任务的环境变量
turbo run build --dry-run --filter=web

下一步

现在您已经了解了如何在 Turborepo 中配置环境变量，您可以继续学习其他高级主题，如远程缓存和CI/CD 集成。

开发应用程序

了解如何在 Turborepo 中开发应用程序，包括配置开发任务、使用终端 UI、监视模式等。

构建 CI

了解如何在持续集成管道中使用 Turborepo 来加速构建、代码检查、测试和其他任务。