yii3项目在docker中启动失败主因是php扩展缺失、composer依赖未安装或环境变量未生效，导致容器秒退或500错误；需通过docker ps -a查状态、docker logs看报错、php -m验扩展、修正dockerfile启用扩展、删除vendor挂载、设app_env=prod，并确认web服务进程与重写模块已启用。
Yii3项目在Docker中启动失败，常见于容器内PHP扩展缺失、Composer依赖未正确安装或环境变量未生效，导致web服务直接退出或返回500错误。
检查容器是否真正启动并保持运行
执行 docker ps -a 查看容器状态，若显示 Exited (1) 或 Created，说明启动后立即崩溃，不是端口映射或Nginx配置问题，而是入口命令失败。
运行 docker logs <container_id></container_id>，重点查看最后一行——90%的崩溃原因会直接打印在这里，比如 PHP Fatal error: Uncaught Error: Class "yii\console\Application" not found 或 Failed to load extension 'gd'。
如果日志为空或只显示 standard_init_linux.go:228: exec user process caused: exec format error，说明 Dockerfile 中 base image 架构与宿主机不匹配（例如在 Intel 机器上用了 arm64 镜像），需改用 php:8.2-apache 这类官方多架构支持镜像。
验证PHP扩展是否完整加载
进入容器内部：docker exec -it <container_id> bash</container_id>。
执行 php -m | grep -E "pdo|mbstring|xml|json|gd|opcache"，确认 Yii3 所需核心扩展全部存在。缺 mbstring 会导致 InvalidArgumentException: mbstring extension is required 错误，必须补全。
若发现缺失，不要手动 docker-php-ext-install ——这会破坏镜像一致性。应退回 Dockerfile，在 RUN 指令中显式启用：例如添加 RUN docker-php-ext-install pdo_mysql mbstring gd xml zip opcache，然后重新构建镜像。
修复 Composer 自动加载失效问题
方法一：重建 autoload 文件
在容器内执行 composer dump-autoload --optimize，强制刷新类映射。Yii3 依赖 PSR-4 自动加载，若 vendor/autoload.php 未正确生成或被覆盖，Web 请求会直接报 Class not found。
方法二：检查 volume 挂载是否覆盖了 vendor 目录
查看 docker-compose.yml 中是否将本地 ./vendor 挂载进容器，例如 - ./vendor:/app/vendor。这会导致容器内 composer install 结果被本地空目录覆盖，【必须删除该挂载项】，改用 COPY 或构建时安装依赖。
方法三：确认 APP_ENV 和 YII_ENV 是否设为 prod
在 docker-compose.yml 的 environment 下检查是否设置了 APP_ENV=prod 和 YII_ENV=prod。Yii3 在非 prod 环境下默认不启用优化自动加载器，且部分调试组件（如 debug toolbar）缺失时会中断启动流程。
快速验证 Web 入口是否可达
第一步：确认 Apache 或 PHP-FPM 正在监听
在容器内运行 ps aux | grep -E "(apache|php-fpm)"，若无进程，说明启动脚本没触发服务，检查 Dockerfile 中 CMD 是否指向 apache2-foreground 或 php-fpm -F。
第二步：手动触发 index.php
执行 php /app/web/index.php（路径按实际调整），观察是否抛出异常。若此处报错，说明应用层配置问题（如 config/web.php 中数据库连接未适配容器网络），而非 Web 服务器问题。
第三步：检查 .htaccess 是否生效（Apache 场景）
确认 Dockerfile 中启用了 rewrite 模块：RUN a2enmod rewrite，并在虚拟主机配置中设置 AllowOverride All，否则路由 404 不是代码问题，而是 URL 重写未启用。
