こんにちは。ダタク @iQeeeda です。
2023 年の年明けに AWS の ECS で WordPress を動かそうとして、ずっと原因を調べていたことがあります。
コンテナから RDS につながらず、返ってくるのは DB 接続エラーでした。
原因は AWS 側ではなく、WordPress の Docker イメージの仕様にありました。
結論: 環境変数を読まない wp-config.php があると設定は反映されない
先に結論です。
- WordPress 公式イメージは
wp-config.php経由でしか環境変数を読まない wp-config.phpは起動時に置いていないときだけ自動生成される- 環境変数を読まない自前の
wp-config.phpがあると自動生成が飛ばされ、渡した値が読まれない - 切り分けはコンテナ内の
wp-config.phpに環境変数を読む関数 (getenv_docker) があるか見るだけ - 静的イメージに固めるときは公式同梱の
wp-config-docker.phpへシンボリックリンクを張る
今回は「 Docker の WordPress で環境変数が効かない理由と、その切り分け方」という話をします。
それでは解説していきます。
WORDPRESS_DB_HOST を渡しても DB 接続エラーが消えない
公式イメージには DB の接続情報を渡すための環境変数が用意されています。
Docker Hub の説明 には、次のような変数が並んでいます。
WORDPRESS_DB_HOSTWORDPRESS_DB_USERWORDPRESS_DB_PASSWORDWORDPRESS_DB_NAME
ところが環境変数を設定しても、DB 接続エラーが消えないことがあります。
僕が ECS から RDS につなごうとしたときも、環境変数が読み取られずずっと調べ続けることになりました。
環境変数を読むコードはイメージの中にある
ここで効いてくるのが、環境変数の一覧に添えられた一言です。
The following environment variables are also honored for configuring your WordPress instance (by a custom wp-config.php implementation) 「独自の wp-config.php 実装によって、これらの環境変数が設定に反映される」と書かれています。
この「独自の wp-config.php 実装」の部分がリンクになっており、飛ぶ先は公式イメージに同梱されている wp-config-docker.php です。
自分で書く wp-config.php のことではありません。
環境変数の値を実際に読み取るコードは、公式側が用意したこのファイルの中にあります。
起動スクリプト (docker-entrypoint.sh) は wp-config.php があると自動生成しない
では、その wp-config.php はどこで用意されるのか。
コンテナの起動スクリプト docker-entrypoint.sh です (以下は 2026 年 9 月時点の master / PHP 8.4 版で確認)。
条件を決めているのはこの分岐です。
wpEnvs=( "${!WORDPRESS_@}" )
if [ ! -s wp-config.php ] && [ "${#wpEnvs[@]}" -gt 0 ]; then 条件は 2 つあります。
wp-config.phpがない (または空)WORDPRESS_で始まる環境変数が 1 つ以上ある
両方そろったときだけ、起動スクリプトは wp-config.php を作ります。
中身のある wp-config.php がすでにあれば 1 つ目の条件を満たさないため、自動生成の処理ごとスキップされます。
-s は「存在して、かつ空でない」を見るので、0 バイトのファイルは「ない」と同じ扱いになります。
【重要】生成を飛ばしたことは起動ログに出ない
このスクリプトが wp-config.php について標準エラーへログを出すのは、新しく作ったときだけです。
No 'wp-config.php' found in $PWD, but 'WORDPRESS_...' variables supplied; copying ... 生成をスキップしたときは、それに対応するログが何も出ません。wp-config.php だけを先に置いた初回起動時なら本体コピーのログなどは出るため、wp-config.php に関する行だけがすっぽり抜けます。
なお本体一式ごと持ち込んだ場合や、初期化済みボリュームの再起動時は本体コピーのログも出ません。
ログに手がかりが残らないため、ネットワークや DB 側の設定を疑い続けてしまいがちです。
自動で作られる wp-config.php には getenv_docker が入っている
起動スクリプトが元にするのはさきほどの wp-config-docker.php です。
ここに getenv_docker というヘルパ関数があり、DB の設定は次のように書かれています (抜粋)。
define( 'DB_NAME', getenv_docker('WORDPRESS_DB_NAME', 'wordpress') );
// ...
define( 'DB_HOST', getenv_docker('WORDPRESS_DB_HOST', 'mysql') ); 環境変数を読んでいるのはこの関数です。
自分で置いた wp-config.php が環境変数を読んでいなければ、渡した値はどこにも使われません。
WordPress 本体のほうは wp-load.php が wp-config.php の存在を見て読み込むだけです (抜粋)。
if ( file_exists( ABSPATH . 'wp-config.php' ) ) {
// ...
require_once ABSPATH . 'wp-config.php';
} WordPress 本体は置いてある wp-config.php をそのまま読みます。
中身が別の DB を指していれば、そこへつなぎにいきます。
【余談】2022 年版のスクリプトと比べても分岐は同じ
2022 年 12 月時点のスクリプト と 2026 年 9 月時点の master (PHP 8.4 版) を diff で比べると、wp-config.php を作る分岐の差分は 0 行でした。
僕がこのエラーにハマった 2023 年の年明けから、この確認時点まで分岐は変わっていません。
環境変数を読まない自前の wp-config.php を持ち込む構成なら、同じ仕組みで止まります。
wp-config.php の中身を見れば切り分けられる
切り分けは動いているコンテナの中を見るのが早いです。
# 起動中のコンテナで wp-config.php の中身を確認する
docker exec -it [コンテナ名] cat wp-config.php ECS なら aws ecs execute-command に読み替えてください。
確認するのは、公式生成の wp-config.php に入っている getenv_docker の記述があるかどうかです (該当パスに存在しない場合はコマンドがエラーになります)。
getenv_dockerがある: 公式生成のwp-config.phpで、環境変数を読む設定になっている
getenv_dockerがない: 自前でgetenv()等を書いていない限り、環境変数は読まれない
getenv_docker がないときにやること
まずは自前の wp-config.php がコンテナに入らないようにします。
- イメージに焼き込んでいるなら Dockerfile の
COPYを外す - マウントしたボリュームに残っているなら消す
とくに既存サイト一式をそのまま移行した構成だと、うっかり wp-config.php ごと持ち込んでいるパターンが多いです。
設定を足したい場合や静的構成に固めたい場合は、次の章の公式手順に寄せます。
wp-config.php の設定追加や静的構成の公式手順
起動時の自動生成に任せず、ビルド時に本体一式を固めたい場合や、独自の定数を足したい場合もあります。
Docker Hub の説明 には、本体を含めて固めてしまい更新のたびに再デプロイする構成 (静的イメージ構成) の手順が載っています。
静的構成では cp -s で wp-config-docker.php にリンクする
Apache 版 (wordpress:apache) で静的構成を作る場合、Dockerfile に次のように書きます。
WORKDIR /usr/src/wordpress
RUN set -eux; \
find /etc/apache2 -name '*.conf' -type f -exec sed -ri -e "s!/var/www/html!$PWD!g" -e "s!Directory /var/www/!Directory $PWD!g" '{}' +; \
cp -s wp-config-docker.php wp-config.php cp -s はコピーではなくシンボリックリンクを作るオプションです。
名前は wp-config.php のまま、実体は getenv_docker を持つ wp-config-docker.php を参照させる仕組みです。
find の行は Apache の参照先を /var/www/html から /usr/src/wordpress に書き換える処理です。cp -s の行だけ真似しても、Apache は元の場所を見たままになります。
なお /etc/apache2 を書き換えるため、この手順は Apache 版前提で FPM 版には使えません。
実体の wp-config-docker.php は公式の Dockerfile があらかじめ配置しています (2026 年 9 月時点の master で確認)。
COPY --chown=www-data:www-data wp-config-docker.php /usr/src/wordpress/ 定数を足したいだけなら WORDPRESS_CONFIG_EXTRA で渡せる
wp-config.php を丸ごと自前で持たなくても、define() で独自の定数を少し足したいだけなら環境変数 WORDPRESS_CONFIG_EXTRA で渡せます。
渡した文字列が wp-config-docker.php の中で eval() にかけられるため、公式の仕組みを保ったまま設定を追加できます。
ただし wp-config-docker.php が使われている前提なので、環境変数を読まない自前の wp-config.php が残っているとこの変数も無視されます。
どうしても独自の wp-config.php を用意したい場合は、公式の wp-config-docker.php をベースにして getenv_docker の読み取りを残すのが安全です。
というわけで、Docker の WordPress で環境変数が効かないときは、ネットワークやクラウド側の設定を疑う前にまず wp-config.php の中身を見てみてください。
まだコメントはありません