环境变量

您可以为资源定义环境变量，这些变量将在您的应用程序中可用。

预览部署可以拥有不同的环境变量，例如您可以将其用作暂存环境来测试您的应用程序。

普通视图与开发者视图

Coolify 提供了两种管理环境变量的方式：普通视图和开发者视图。您可以使用环境变量区域顶部的按钮在这两种视图之间切换。

普通视图

默认视图将每个环境变量显示为独立的表单卡片。每张卡片包含可编辑的键和值字段，以及用于配置 Build Variable（构建变量）、Multiline（多行）和 Literal（字面量）等选项的复选框。

当您需要根据特定选项配置单个变量，或处理多行值和锁定密钥时，此视图最为合适。

开发者视图

开发者视图提供了一个纯文本编辑器，所有环境变量均以 .env 文件格式显示（KEY=VALUE，每行一个）。这对于批量编辑或从现有的 .env 文件粘贴变量非常有用。

保存时，Coolify 会解析文本并相应地创建、更新或删除变量。文本编辑器中变量的顺序将被保留。

以 # 开头的行被视为注释，在保存时会被忽略。

限制

锁定密钥 显示为 KEY=(Locked Secret, delete and add again to change)，无法在开发者视图中编辑。您必须删除并重新添加它们。
多行变量 显示为 KEY=(Multiline environment variable, edit in normal view)，必须在普通视图中编辑。

构建时与运行时变量

每个环境变量都有两个独立的标志来控制其何时可用：Build Variable（构建变量）和 Runtime Variable（运行时变量）。默认情况下两者均启用，因此新变量在两个阶段都可用，除非您更改此设置。

配置	构建阶段	运行中的容器
构建 + 运行（默认）	可用	可用
仅构建	可用	不可用
仅运行	不可用	可用

您可以在普通视图中独立切换这些复选框。

构建变量

构建变量在镜像构建过程中注入。对于 Dockerfile 部署，它们作为 ARG 指令添加。对于 Docker Compose 和 Nixpacks/Buildpack 部署，它们通过 --env-file 传递。

构建时变量存储在一个独立的文件（/artifacts/build-time.env）中，该文件位于 Docker 构建上下文之外，因此不会包含在最终镜像中。

运行时变量

运行时变量在运行中的容器内可用。构建完成后，Coolify 会写入一个 .env 文件，其中包含所有启用运行时的变量，Docker Compose 会在容器启动时通过 env_file 指令加载该文件。

如果您仅在运行时需要一个变量（例如，应用程序启动时读取的 API 密钥），请禁用 Build Variable 以使其完全脱离构建阶段。

默认情况下，构建变量作为 --build-arg 值传递。这些值会被记录在镜像元数据中——任何有权访问该镜像的人都可以查看它们。对于私有仓库令牌或 API 密钥等敏感值，您可以在应用程序的环境变量设置中启用 Use Docker Build Secrets（使用 Docker 构建密钥）。这将使用 Docker BuildKit（需要 Docker 18.09+）将密钥临时挂载到构建步骤中，而不是将其嵌入镜像层，从而确保它们在最终镜像中不留痕迹。

启用后，Coolify 会自动重写您 Dockerfile 中的 RUN 指令以使用 --mount=type=secret ——您无需手动修改 Dockerfile。对于 Docker Compose 构建，Coolify 会直接在 compose 文件中添加原生的 secrets: 部分。

启用后，Coolify 将执行以下操作：

通过 --secret id=KEY,env=KEY 传递构建变量，而不是 --build-arg。
如果缺少，会自动向您的 Dockerfile 添加 # syntax=docker/dockerfile:1 指令。
向每个 RUN 指令注入 --mount=type=secret，使密钥在该步骤中作为环境变量可用。
密钥绝不会被嵌入镜像层，也不会出现在 docker history 中。

对于 Docker Compose 构建，Coolify 会直接在 compose 文件中添加原生的 secrets: 部分。

	构建参数（默认）	构建密钥
Docker 标志	`--build-arg KEY=value`	`--secret id=KEY,env=KEY`
在 `docker history` 中可见	是	否
存储在镜像层中	是	否
需要 BuildKit	否	是（Docker 18.09+）

构建缓存

Coolify 会根据所有密钥值生成一个 COOLIFY_BUILD_SECRETS_HASH。当您的密钥未更改时，Docker 构建缓存将被保留；当密钥更改时，缓存将自动失效。

如果构建服务器上不可用 BuildKit，即使启用了此设置，Coolify 也会回退到传统的 --build-arg 行为。

多行变量

在普通视图中勾选 Multiline（多行）复选框，可保留变量值中的换行符和特殊字符。当您的值跨越多行时（例如：）请启用此选项：

SSH 私钥
TLS/SSL 证书
多行配置文件或脚本

部署时，多行值会被单引号包裹，从而防止任何 Shell 解析。在 Docker 构建期间，多行构建变量通过 ARG KEY 传递（不带内联值赋值），以避免破坏 Dockerfile 语法——实际值会通过 --build-arg 单独提供。

多行变量只能在普通视图中编辑。在开发者视图中，它们显示为 KEY=(Multiline environment variable, edit in normal view)。

字面量变量

在普通视图中勾选 Literal（字面量）复选框可防止变量插值。默认情况下，Coolify 会展开您值内部的 $OTHER_VAR 等引用。启用 Literal 会将整个值视为纯文本——美元符号和其他 Shell 特殊字符将按原样保留。

当您的值包含不应被解释为变量引用的 $ 字符时，请使用此选项：

包含 $ 的密码（例如 P@ss$word123）
正则表达式模式（例如 ^user\d+$）
模板语法或字面量 Shell 表达式

当 Multiline 已启用时，Literal 复选框将隐藏，因为多行值始终被视为字面量。

共享变量

您可以设置三种类型的共享变量：

基于团队
基于项目
基于环境（生产、暂存等）

您可以在各自的页面上设置共享变量。

然后您可以在任何地方使用这些变量。例如：您将 NODE_ENV 定义为 production。

基于团队

您可以在 Team 页面上设置它们，并使用 {{team.NODE_ENV}} 调用。请勿将 "team" 替换为您的实际团队名称。

基于项目

您可以在 Projects 页面（齿轮图标下）设置它们，并使用 {{project.NODE_ENV}} 调用。请勿将 "project" 替换为您的实际项目名称。

基于环境

您可以在 Environments 页面（选择 Project）的齿轮图标下设置它们，并使用 {{environment.NODE_ENV}} 调用。请勿将 "environment" 替换为您的实际环境名称。

在 Docker Compose 中使用环境变量和共享变量

在 Coolify 中，您可以按照 Docker Compose 知识库中的详细说明轻松配置这些变量。

预定义变量

Coolify 为您预定义了一些变量，以便您在应用程序或服务中使用。您只需向应用程序或服务添加如下环境变量即可。

# 例如，您可以在应用程序中使用此变量
MY_VARIABLE=$SOURCE_COMMIT
# 您将在应用程序中将源代码的提交哈希作为环境变量 MY_VARIABLE 获取

应用程序变量

`COOLIFY_FQDN`

应用程序的完全限定域名。

`COOLIFY_URL`

应用程序的 URL。

`COOLIFY_BRANCH`

源代码的分支名称。

`COOLIFY_RESOURCE_UUID`

Coolify 生成的唯一资源标识符。

`COOLIFY_CONTAINER_NAME`

Coolify 生成的容器名称。

`SOURCE_COMMIT`

源代码的提交哈希。