1. .env 文件：只负责插值#

在 compose 文件同目录建一个 .env：

1
NGINX_PORT=8080
2
IMAGE_TAG=1.27
3
DB_PASSWORD=example_password_123

compose 文件里用 ${...} 引用它：

1
services:
2
  web:
3
    image: nginx:${IMAGE_TAG}
4
    ports:
5
      - "${NGINX_PORT}:80"

运行 docker compose up -d 时，Compose 会先读 .env，把 ${IMAGE_TAG} 换成 1.27、${NGINX_PORT} 换成 8080，再去执行。注意：NGINX_PORT 这个变量不会出现在容器内部，你在容器里执行 printenv 是看不到它的——它只参与了拼凑 compose 文件这一步。

2. env_file：批量把变量塞进容器#

应用真正要读的配置（数据库地址、密码、开关等）一般这样给：

1
DATABASE_URL=postgres://app:secret@db:5432/appdb
2
LOG_LEVEL=info
3
FEATURE_X=on

1
services:
2
  app:
3
    image: myapp:latest
4
    env_file:
5
      - app.env

容器启动后，在容器内执行 printenv 就能看到 DATABASE_URL 等变量。一个服务可以挂多个 env_file，写成列表即可；多个文件里有同名变量时，后写的文件覆盖先写的。

env_file 里也可以做插值（Compose 2.24 以后支持，需要在文件里用 ${...} 并配合 env_file 的长语法 required 等属性，一般场景用不到，先知道有这回事）。

3. environment：直接写在 compose 里#

1
services:
2
  app:
3
    image: myapp:latest
4
    environment:
5
      - TZ=Asia/Shanghai
6
      - LOG_LEVEL=debug
7
      - EMPTY_VALUE=
8
      - PASSTHROUGH_VAR

两种写法：上面这种列表写法里，KEY=VALUE 是直接赋值；只写 KEY 不带等号（如 PASSTHROUGH_VAR）表示把宿主机当前 shell 里的同名变量透传进容器，宿主机没有这个变量时它在容器里就是空值（并会给出一条警告）。也可以写成映射写法，效果一样：

1
    environment:
2
      TZ: Asia/Shanghai
3
      LOG_LEVEL: debug

4. 三者优先级#

当同一个变量在多处出现时，谁说了算：

• 注入容器时：environment 的优先级高于 env_file。两边都有 LOG_LEVEL，容器里拿到的是 environment 写的值。
• 插值时：${...} 的取值来源优先级是 宿主机 shell 环境变量 > .env 文件。也就是说，你临时想换个端口，不用改 .env，直接：

1
NGINX_PORT=9090 docker compose up -d

这一行 shell 里给的值会盖过 .env 里的 8080。这也是为什么 .env 里放默认值、命令行临时覆盖，是很常见的用法。

1. 五个字段逐个讲#

1
    healthcheck:
2
      test: ["CMD", "pg_isready", "-U", "postgres"]
3
      interval: 10s
4
      timeout: 5s
5
      retries: 5
6
      start_period: 30s

还有个较新的字段 start_interval：在 start_period 期间用更密的间隔体检，好让服务一旦就绪就尽快转 healthy，日常可以不写。

体检命令的判定标准只有一个：退出码为 0 算通过，非 0 算失败。

2. 三个可直接抄的例子#

PostgreSQL（镜像自带 pg_isready）：

1
services:
2
  db:
3
    image: postgres:16
4
    environment:
5
      - POSTGRES_PASSWORD=${DB_PASSWORD:?请先在 .env 里设置 DB_PASSWORD}
6
    healthcheck:
7
      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
8
      interval: 10s
9
      timeout: 5s
10
      retries: 5
11
      start_period: 20s

MySQL（镜像自带 mysqladmin；MySQL 8 的镜像也可以用 mysqladmin ping）：

1
services:
2
  mysql:
3
    image: mysql:8.4
4
    environment:
5
      - MYSQL_ROOT_PASSWORD=${MYSQL_PASSWORD:?请先设置 MYSQL_PASSWORD}
6
    healthcheck:
7
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-p$$MYSQL_ROOT_PASSWORD"]
8
      interval: 10s
9
      timeout: 5s
10
      retries: 10
11
      start_period: 30s

注意这里的 $$MYSQL_ROOT_PASSWORD：双写 $ 是转义，意思是让容器内部的 shell/程序去读它自己的环境变量，而不是让 Compose 在宿主机上插值。mysqladmin ping 不带密码在开了密码认证时也能返回部分结果，为了严谨建议带上密码测。

HTTP 服务（用 curl 或 wget 探一个健康接口）：

1
services:
2
  web:
3
    image: myapp:latest
4
    healthcheck:
5
      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
6
      interval: 15s
7
      timeout: 5s
8
      retries: 3
9
      start_period: 15s

curl -f 在 HTTP 状态码是 4xx/5xx 时返回非 0 退出码，正好符合体检的判定方式。

WARNING

体检命令依赖容器镜像里有这个工具。很多精简镜像（alpine、distroless）里既没有 curl 也没有 wget，这时 healthcheck 会一直失败，误报 unhealthy。解决办法：优先用服务自带的探针（如 pg_isready），实在没有就换带工具的镜像标签，或者在 Dockerfile 里把 curl 装进去。

经典问题：数据库没就绪，应用启动就报错#

没有健康检查配合时，经典翻车现场是这样的：depends_on 只保证 db 容器先启动，app 紧跟着起来，第一件事连数据库——而 PostgreSQL 还在初始化数据目录——连接被拒，app 直接崩溃退出，日志里全是 connection refused。以前大家靠在应用里写重试循环或者塞个 sleep 硬扛，现在标准解法是 healthcheck + service_healthy，一份完整的例子：

1
services:
2
  db:
3
    image: postgres:16
4
    environment:
5
      - POSTGRES_USER=app
6
      - POSTGRES_PASSWORD=${DB_PASSWORD:?请先在 .env 里设置 DB_PASSWORD}
7
      - POSTGRES_DB=appdb
8
    volumes:
9
      - db_data:/var/lib/postgresql/data
10
    healthcheck:
11
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
12
      interval: 5s
13
      timeout: 3s
14
      retries: 10
15
      start_period: 15s
16

17
  migrate:
18
    image: myapp:latest
19
    command: ./run-migrations.sh
20
    depends_on:
21
      db:
22
        condition: service_healthy
23
    environment:
24
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/appdb
25

26
  app:
27
    image: myapp:latest
28
    ports:
29
      - "${APP_PORT:-8080}:8080"
30
    depends_on:
31
      db:
32
        condition: service_healthy
33
      migrate:
34
        condition: service_completed_successfully
35
    environment:
36
      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/appdb
37

38
volumes:
39
  db_data:

这份配置的启动顺序是：db 先起 → 体检通过（真的能连了）→ migrate 迁移任务开跑 → 迁移以 0 退出 → app 才启动。三个条件一次全用上了。

两个必须知道的边界：

1. depends_on 只管「启动这一刻」。运行中途 db 重启了，app 不会跟着等它健康，要靠应用自身的连接重试兜底——编排解决顺序，代码解决健壮性，两回事。
2. 短语法在 Compose 老版本（V1）里还有「等网络就绪」的错觉，V2 里短语法就是纯粹的先后拉起，别指望更多。

WARNING

docker compose down 时的停止顺序正好和启动相反：先停 app，再停 db，这个不用你操心。但如果某个服务体检一直不过（比如探针命令写错），依赖它的服务会一直等着，up 看起来像卡死——先去看被依赖服务的健康状态，别干等，排查方法在最后一节。

1. 变量没生效#

按这个顺序查，基本都能定位：

1. 先看最终配置：docker compose config，找到对应服务，看变量被替换成了什么。如果这里就是错的，问题在插值层：检查 .env 在不在 compose 文件同目录、变量名有没有写错、是不是被 shell 里同名变量盖掉了（shell 优先级更高）。
2. 再看容器内部：docker compose exec <服务名> printenv | grep <变量名>。最终配置对、容器里没有，是注入层的问题：env_file 路径写错、或者变量只写在 .env 里——再强调一遍，.env 不进容器，要给容器用必须走 env_file 或 environment。
3. 改了没重启：改完 .env 或 compose 文件后，已经跑着的容器不会自动更新，必须重新 docker compose up -d 让它重建，光 restart 不会重新读配置。

2. healthcheck 一直 unhealthy#

docker compose ps 里状态一直 (health: starting) 或者 (unhealthy)，这样查：

1. 看健康检查的原始记录，Docker 把每次体检的退出码和输出都存了：

1
docker inspect --format='{{json .State.Health}}' <容器名>

输出里的 Log 数组是最近几次体检记录，重点看 ExitCode 和 Output——命令不存在会报 executable file not found，连接失败会直接把错误打在 Output 里，一看便知。

2. 手动在容器里跑一遍体检命令，复现它到底卡在哪：

1
docker compose exec db pg_isready -U app -d appdb
2
echo $?   # 0 是通，非 0 是不通

3. 对一下时间参数：服务本来就要启动 40 秒，你 start_period 只给了 10 秒、retries 又小，它会在还没就绪时就被判死刑。慢启动的服务（数据库首次初始化、Java 应用）把 start_period 给足、 retries 给大。
4. 确认命令在镜像里存在：精简镜像没 curl 是最常见的乌龙，按第四节警告里的方法换探针。