yii容器化部署失败主因是php扩展缺失（pdo_mysql、mbstring、xml、json、ctype）、web服务器documentroot路径与allowoverride配置错误、数据库host误写localhost；需用php:8.2-apache镜像，安装并启用全部扩展，正确配置apache/nginx入口路径、服务名及runtime/assets目录权限。
Yii 容器化部署失败，八成卡在三个地方：PHP 扩展没装全、Apache/Nginx 路径配错、数据库 host 写成了 localhost。不是代码问题，是容器网络和权限模型变了，得按 Docker 的规则重配。
PHP 扩展缺失导致容器启动即退出
容器里跑 php -v 或 phpinfo() 一看，pdo_mysql、mbstring、xml、json、ctype 少一个，Yii 3.x 就直接报错退出；Yii 2.x 虽能硬扛，但路由、表单验证、JSON 返回全崩。
- 别用
php:8.2-alpine镜像——pdo_mysql编译依赖太多，容易卡在libmysqlclient上，改用php:8.2-apache或php:8.2-fpm -
RUN docker-php-ext-install pdo pdo_mysql mbstring xml ctype json这行必须完整，漏掉ctype会导致 Yii 3.x 的BaseObject初始化失败 - 装完必须跟一句
RUN docker-php-ext-enable pdo pdo_mysql mbstring xml ctype json，某些镜像（如 Debian 系）安装后不自动启用 - 检查
Loaded Configuration File是否指向你改过的/usr/local/etc/php/php.ini，而不是只读的镜像内置副本
Web 服务返回 403/404：DocumentRoot 和 AllowOverride 没对上
浏览器打开全是 403 Forbidden 或 404 Not Found，不是代码路径错了，是 Apache/Nginx 根本没把请求交给 index.php 处理。Yii 依赖 .htaccess（Apache）或重写规则（Nginx），但默认配置全关着。
- Apache 场景下，
DocumentRoot必须是/var/www/html/web（Yii 2.x）或/var/www/html/public（Yii 3.x），绝不能是项目根目录 -
<directory></directory>块里必须有AllowOverride All和Require all granted，否则.htaccess被无视 - Nginx 场景下，
location /块要包含try_files $uri $uri/ /index.php?$args;，且fastcgi_pass指向 PHP-FPM 服务名（如php:9000），不是127.0.0.1:9000 - 别在
web/目录放空.htaccess——如果mod_rewrite没加载，它会触发 500 错误，而 Docker 默认不暴露 Apache 错误日志
数据库连接 refused：host 写死 localhost 是最大陷阱
本地 php yii migrate 成功，一进容器就报 SQLSTATE[HY000] [2002] Connection refused，基本可以确定是 config/db.php 里还写着 'host' => 'localhost'。
- Docker 容器内
localhost指自己，不是宿主机，更不是隔壁的 MySQL 容器。必须改成db（或你在docker-compose.yml里定义的服务名） - 不要用
getenv('DB_HOST') ?: 'localhost'这类 fallback——环境变量没设时会退到localhost，反而掩盖问题 - 加
healthcheck：在db服务里写healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-proot"]，再让 app 服务depends_on: { db: { condition: service_healthy } } - 调试时别等 Yii 报错，进 PHP 容器直接跑：
ping db和nc -zv db 3306，10 秒内就能定位是 DNS 解析失败还是端口不通
runtime 和 assets 权限不对，页面白屏或 CSS/JS 加载失败
前端能打开，但登录后跳转空白、图标不显示、资源 404，大概率是 runtime 和 assets 目录权限没给 www-data（Apache）或 www-data/nginx（Nginx + PHP-FPM）写入权。
- 构建镜像时加一行：
RUN chown -R www-data:www-data /var/www/html/runtime /var/www/html/assets - 如果是挂载本地目录（开发模式），宿主机需提前
chown -R $(id -u):$(id -g) runtime assets，否则容器内www-data用户无法写入 - Yii 3.x 默认用
public/assets，注意路径别写成web/assets；Yii 2.x 是web/assets，但部分 Starter Kit 改过结构，以实际AssetManager::basePath配置为准 - 别在
Dockerfile里用COPY --chown=www-data:www-data . .代替显式chown——某些文件系统（如 macOS Docker Desktop）不支持该 flag
最常被忽略的是：容器内时间同步、时区未设、opcache.revalidate_freq 在开发中没关，导致改了代码却一直看到旧页面。这些不会报错，但会让调试变成玄学。
