Docker Compose .env 环境变量配置教程

在使用 Docker Compose 部署项目时，我们经常会遇到需要修改端口、数据库密码、时区以及其他环境变量的情况。

如果直接把所有配置写在 Compose 文件中，每次修改都需要编辑整个配置文件，不仅操作繁琐，还容易出现配置错误。

Docker Compose 提供了 .env 环境变量文件，可以将部分配置信息单独保存，在部署时自动读取。

本文介绍 Docker Compose 环境变量的基本用法，并通过一个简单的 Nginx 项目演示如何配置 .env、验证变量以及排查常见问题。

1. Docker Compose 的 .env 文件是什么？

.env 是用于保存环境变量的配置文件。

在 Docker Compose 项目中，可以通过 .env 集中管理端口、时区、部署环境等参数。

例如：

WEB_PORT=8080
TZ=Asia/Shanghai
APP_MODE=production

然后在 compose.yaml 中引用这些变量。

这样以后需要修改端口时，只需要调整 .env，而不必反复编辑 Compose 文件。

需要注意，.env 中的变量主要用于 Compose 配置解析，并不代表这些变量会自动传入容器内部。

如果应用需要读取某个环境变量，还需要通过 environment 或 env_file 等方式配置。

2. 准备搭建环境

本次使用 Linux 云服务器进行演示，推荐使用 Debian 或 Ubuntu 系统。

建议提前准备：

Linux 云服务器
Docker Engine
Docker Compose V2
SSH 连接工具

如果还没有服务器，可以根据实际项目规模选择莱卡云 Linux 云服务器。

本次演示仅运行一个轻量级 Nginx 容器，普通入门配置通常即可满足要求。

查看官网购买链接： https://www.lcayun.com

如果尚未安装 Docker，可以参考：

安装教程： 服务器上安装docker和docker-compose教程

安装完成以后，执行以下命令检查环境：

docker --version
docker compose version

能够正常输出版本信息即可继续。

3. 创建项目和 .env 文件

首先创建一个独立的演示目录。

mkdir -p /opt/compose-env-demo
cd /opt/compose-env-demo

然后创建 .env 文件：

cat > .env <<'EOF'
WEB_PORT=8080
TZ=Asia/Shanghai
APP_MODE=production
EOF

查看文件内容：

cat .env

可以看到刚才配置的三个环境变量。

其中：

WEB_PORT：Nginx 对外映射的端口。

TZ：容器使用的时区设置。

APP_MODE：本教程使用的演示变量。

需要注意，Nginx 不会因为设置了 APP_MODE 就自动切换运行模式，这里只是展示环境变量的传递方式。

另外，.env 是以英文句点开头的隐藏文件。

如果通过文件管理器查看，需要开启显示隐藏文件功能。

4. 编写 Docker Compose 文件

接下来在相同目录创建 compose.yaml。

可以执行：

nano compose.yaml

写入以下配置：

services:
  web:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "${WEB_PORT:-8080}:80"
    environment:
      TZ: "${TZ:-Asia/Shanghai}"
      APP_MODE: "${APP_MODE:-production}"

保存退出。

这里最重要的是：

${WEB_PORT:-8080}

表示优先读取 WEB_PORT 的值。

如果变量没有设置或者为空，则使用默认值 8080。

同样：

${TZ:-Asia/Shanghai}

表示时区变量没有设置或者为空时，默认使用 Asia/Shanghai。

通过这种方式，可以在不修改 Compose 文件的情况下调整部分部署参数。

5. 检查环境变量是否生效

正式启动项目之前，建议先检查 Compose 配置。

执行：

docker compose config

Docker Compose 会解析环境变量，并输出最终配置。

如果前面的 .env 文件配置正确，应该能够看到端口映射使用 8080，时区使用 Asia/Shanghai。

确认配置无误后启动：

docker compose up -d

查看容器状态：

docker compose ps

测试 Nginx：

curl -I http://127.0.0.1:8080

如果返回正常的 HTTP 响应，说明项目已经成功运行。

注意，如果 Compose 配置包含真实密码或 Token，不要将完整的 docker compose config 输出公开。

如果本机可以访问，但外部无法访问，可以继续检查服务器防火墙和安全组。

6. 修改 .env 后为什么没有变化？

假设项目已经运行，现在希望将访问端口从 8080 修改为 8081。

首先编辑：

nano .env

将端口修改为：

WEB_PORT=8081

保存以后执行：

docker compose config

确认配置已经读取新的端口。

然后重新部署：

docker compose up -d

Docker Compose 会根据配置变化决定是否重新创建相应容器。

如果确实需要强制重新创建演示容器，可以执行：

docker compose up -d --force-recreate

重新部署完成以后，访问新的 8081 端口即可。

正式业务重新创建容器之前，应先检查端口配置和数据持久化情况，避免影响现有服务。

7. .env 和 env_file 有什么区别？

这是 Docker Compose 环境变量配置中容易混淆的地方。

.env 通常用于给 Compose 提供变量替换所需的值。

而 env_file 则可以将指定文件中的环境变量传递给某个容器。

例如，创建一个新的文件：

nano app.env

内容如下：

API_BASE_URL=https://api.example.com
APP_DEBUG=false

然后在 Compose 对应服务中添加：

env_file:
  - ./app.env

这样，app.env 中的变量就可以传递给对应容器。

需要注意，容器能否使用这些变量，取决于实际应用是否支持相应的环境变量。

如果通过 environment 和 env_file 同时设置了同名变量，还需要注意配置覆盖关系。

因此，不建议在多个位置重复定义同一个参数，以免增加排查难度。

8. 多环境部署如何配置？

如果同一个 Docker 项目需要部署在测试环境和正式环境，可以准备不同的环境变量文件。

例如：

.env.dev

.env.prod

测试环境可以使用：

WEB_PORT=8080
APP_MODE=development

正式环境可以使用：

WEB_PORT=8081
APP_MODE=production

启动正式环境时，可以指定：

docker compose --env-file .env.prod config

确认配置后执行：

docker compose --env-file .env.prod up -d

这样就可以使用不同环境的配置文件，而不需要反复修改同一份 Compose 文件。

需要注意，每次执行相关命令时，应确保使用的是正确的环境文件。

9. 如何设置环境变量默认值？

Docker Compose 支持为变量设置默认值。

例如：

environment:
  APP_MODE: "${APP_MODE:-production}"

当 APP_MODE 没有设置或者为空时，会使用 production。

对于一些必须配置的变量，还可以要求变量不能为空。

例如：

environment:
  API_TOKEN: "${API_TOKEN:?请先设置API_TOKEN}"

如果没有正确设置 API_TOKEN，Compose 会在解析配置时提示错误。

这种方式适合检查数据库连接信息、应用密钥等关键参数是否已经配置。

不过，配置验证不能代替实际的凭据安全管理。

10. 环境变量未生效怎么办？

如果已经修改 .env，但 Docker Compose 仍然没有使用预期的配置，可以按照以下顺序排查。

首先确认当前工作目录：

pwd

然后查看目录中的文件：

ls -la

确认 .env 文件是否存在。

接下来检查 Compose 配置：

docker compose config

如果变量仍然不符合预期，需要检查文件名称、变量拼写、命令执行目录，以及是否通过其他方式覆盖了环境变量。

例如：

WEB_PORT=8082 docker compose config

当前 Shell 中指定的 WEB_PORT 可以覆盖 .env 中同名变量提供的替换值。

另外，修改环境变量文件以后，已经运行的容器不会立即自动更新。

通常需要根据配置变化重新部署。

11. 数据库密码和 Token 如何保护？

实际项目中，.env 可能包含数据库密码、API Token 或其他敏感信息。

不建议将包含真实密码的 .env 文件提交到公开代码仓库。

如果项目使用 Git，可以在 .gitignore 中排除相关环境变量文件。

例如：

.env
.env.*

如果需要保留示例配置文件，可以另行设置例外规则。

对于保存敏感数据的 .env，还可以根据实际权限要求限制文件读取：

chmod 600 .env

但需要注意，文件权限并不代表环境变量已经加密。

对于正式生产环境，可以结合专门的密钥管理方案或容器 Secrets 管理重要凭据。

不要在技术文章、视频或操作截图中公开真实密码。

12. Docker Compose 环境变量快速排查表

问题现象	优先检查
环境变量没有替换	`.env` 文件位置和变量名称
修改端口后仍使用旧端口	是否重新部署容器
容器内部读取不到变量	是否配置 `environment` 或 `env_file`
测试和生产配置混乱	是否正确使用 `--env-file`
关键变量为空	是否设置变量校验
Compose 配置解析错误	执行 `docker compose config`
环境变量意外被覆盖	检查 Shell 和其他配置来源
担心密码泄露	检查文件权限和代码仓库配置

建议先确认文件位置，再验证变量替换结果，最后检查容器是否使用了更新后的配置。

13. 总结

Docker Compose 的 .env 文件可以帮助我们集中管理端口、时区及其他部署参数，减少反复修改 Compose 文件的操作。

使用时，需要区分 .env 和 env_file 的实际作用。

正式启动之前，建议先执行：

docker compose config

确认环境变量已经正确解析。

如果修改了配置，可以根据实际情况重新部署容器。

对于数据库密码、API Token 等敏感信息，还需要做好文件权限管理，不要将真实凭据公开。