本文约 2,784 字，预计阅读 7 分钟。文中命令与配置均经过实测，可直接参考执行。
引言：同样的镜像，为什么别人一次跑通你却连不上库
很多人用 Docker 起 WordPress，卡住的地方高度一致：数据库连不上、上传限制 2MB、想改常量又不知道往哪儿写。这些问题本质都是同一个——没搞清楚官方镜像到底认哪些环境变量。
官方 wordpress 镜像并不是”把 WordPress 塞进容器”就完事，它在容器启动时有一段 docker-entrypoint.sh 脚本，会读取环境变量、自动生成 wp-config.php。你给它什么变量，它就写出什么配置。看懂这个机制，所有问题都有解。
原理分析：entrypoint 脚本做了什么
容器启动时按顺序执行：
- 检查
/var/www/html是否已有 WordPress 文件，没有就从官方包复制一份； - 读取
WORDPRESS_DB_*系列变量，渲染wp-config.php； - 若设置了
WORDPRESS_CONFIG_EXTRA，把它原样追加进wp-config.php； - 把
/var/www/html属主改成www-data； - 启动 Apache（或 PHP-FPM，取决于镜像 tag）。
关键点有两个：一是 wp-config.php 是生成的，你手工改了它，下次重建容器可能被覆盖，所以自定义内容应该走 WORDPRESS_CONFIG_EXTRA；二是数据库主机必须填容器网络里的服务名，写 localhost 指向的是 WordPress 容器自己。
保姆级实操
一、数据库四件套（必填）
| 变量 | 含义 | 示例 |
|---|---|---|
WORDPRESS_DB_HOST |
数据库主机，可带端口 | db:3306 |
WORDPRESS_DB_NAME |
数据库名 | wordpress |
WORDPRESS_DB_USER |
数据库用户 | wpuser |
WORDPRESS_DB_PASSWORD |
数据库密码 | 强密码 |
配套还要给数据库镜像传 MARIADB_ROOT_PASSWORD、MARIADB_DATABASE、MARIADB_USER、MARIADB_PASSWORD，两边对上才能连通。
二、表前缀：WORDPRESS_TABLE_PREFIX
environment:
WORDPRESS_TABLE_PREFIX: "mmf_"
站点上线后再改前缀代价很大，第一次部署就该定好。
三、注入自定义常量：WORDPRESS_CONFIG_EXTRA
这是最实用也最少被正确使用的一个变量。它支持多行：
environment:
WORDPRESS_CONFIG_EXTRA: |
define('WP_MEMORY_LIMIT', '256M');
define('WP_MAX_MEMORY_LIMIT', '512M');
define('DISABLE_WP_CRON', true);
define('WP_POST_REVISIONS', 5);
define('EMPTY_TRASH_DAYS', 15);
define('FS_METHOD', 'direct');
define('AUTOMATIC_UPDATER_DISABLED', true);
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
$_SERVER['HTTPS'] = 'on';
}
注意：这段内容会被写进 wp-config.php，所以语法必须是合法 PHP，少一个分号整个站点白屏。
四、调试与开发变量
environment:
WORDPRESS_DEBUG: 1
只在排查时开，线上务必关掉——开启后 PHP 警告会直接输出到页面，等于把路径和结构暴露给访客。
五、自定义 php.ini（解除上传限制）
官方镜像支持把 *.ini 放进 /usr/local/etc/php/conf.d/ 自动加载：
mkdir -p /opt/wp-site/conf
cat > /opt/wp-site/conf/uploads.ini <<'EOF'
upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 300
max_input_vars = 3000
EOF
wordpress:
volumes:
- ./conf/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini:ro
max_input_vars 常被忽略：菜单项特别多或者用页面构建器时，默认 1000 会导致保存菜单只保存了一部分。
六、验证配置是否生效
docker compose exec wordpress php -i | grep -E "upload_max_filesize|post_max_size"
docker compose exec wordpress php -r 'echo WP_MEMORY_LIMIT;'
常见踩坑与失败案例
WORDPRESS_CONFIG_EXTRA里用了双引号导致 YAML 解析失败 —— 用|块语法可以避免转义地狱。- 改了环境变量但配置没变 ——
wp-config.php只在文件不存在时生成。已经装好的站点，要么删掉wp-config.php让容器重新生成，要么直接改文件。 - 案例：一位站长把
WP_HOME/WP_SITEURL写死在WORDPRESS_CONFIG_EXTRA里，后来换域名，后台改不动地址，因为常量优先级高于数据库设置。建议只在迁移救急时临时用这两个常量。 - 把密码明文写进 docker-compose.yml 并推到公开仓库 —— 一定要用
.env文件，并把.env加进.gitignore。
总结
官方 wordpress 镜像的环境变量可以分成三类：数据库连通类、配置注入类、调试类。真正需要你记的只有 WORDPRESS_DB_HOST 填服务名、WORDPRESS_CONFIG_EXTRA 写自定义常量、自定义 php.ini 通过挂载 conf.d 生效这三条。掌握之后，容器化部署 WordPress 的可控性比传统方式高得多。
