docker-composeのenv_fileで指定したファイルに書かれている環境変数と同じ変数が.envファイルにあると、.envで定義されているものに上書きされてしまうという現象に遭遇しました。

docker-compose.yamlは以下のようになっています。

version: "3"

services:
  php:
    image: php:8.0-fpm
    env_file:
      - .env.local

.env.local(env_fileで読み込んでいるファイル)

APP_NUMBER=345

.env

APP_NUMBER=123

この場合において、コンテナ内にでAPP_NUMBERの環境変数は「345」が表示されるものだと思っていました。
しかし実際に表示されるのは「123」となります。

$ docker compose exec php bash
root@102aa4b5b9ef:/var/www/html# echo $APP_NUMBER
123

env_fileを止める

この状況だと、.envもホスト側のコンテナの環境変数に設定されてしまうのでは？と思ったので.env_fileの部分をコメントアウトしてみました。

version: "3"

services:
  php:
    image: php:8.0-fpm
    # env_file:
    #   - .env.local

書き換えたあとにコンテナを再起動して、再度コンテナ内に接続します。

$ docker compose exec php bash
root@102aa4b5b9ef:/var/www/html# echo $APP_NUMBER

こんどは何も表示されなくなりました。。

.envに違う環境変数を定義してみる

今度はenv_fileのコメントアウトを外して.envに他の変数も追記しました。

APP_NUMBER=123
APP_VERSION=abc

docker compose exec php bash
root@102aa4b5b9ef:/var/www/html# echo $APP_VERSION

root@102aa4b5b9ef:/var/www/html# echo $APP_NUMBER 
123

APP_NUMBERは.envものになりましたが、APP_VERSIONは未定義のようです。

ここまでの挙動をみて分かったことは「env_fileで読み込んでコンテナ側に設定した環境変数は、.envで定義した値で上書きされてしまう」ということだと思います。

つまり以下のようなdocker-compose.yamlと同等かなと。

version: "3"

services:
  php:
    image: php:8.0-fpm
    environment:
      - APP_NUMBER=${APP_NUMBER}
    env_file:
      - .env.local

dockerに詳しい人この辺の挙動の解説お願いします...。
マニュアル見てもそれっぽい記述はなさそう。。。