如何解决Azure环境下Yii2的yii\debug\Module实例化失败异常

核心原因 #

Docker构建时执行了composer install --no-dev，会跳过require-dev中的依赖包（包括yiisoft/yii2-debug），但应用配置（config/web.php）中仍启用了debug模块，导致容器运行时找不到该类。

解决方案 #

方案一：生产环境禁用debug模块（推荐） #

1. 修改config/web.php，仅在开发环境加载debug模块：

$config = [
    // 原有配置内容
];

if (YII_ENV_DEV) {
    // 仅开发环境启用debug模块
    $config['modules']['debug'] = [
        'class' => 'yii\debug\Module',
        // 其他debug模块相关配置
    ];
    // 若有gii模块，同样按此逻辑处理
    $config['modules']['gii'] = [
        'class' => 'yii\gii\Module',
    ];
}

return $config;

2. 在Dockerfile中添加环境变量，指定生产环境：

# 在Dockerfile末尾添加
ENV YII_ENV=prod
ENV YII_DEBUG=false

方案二：生产环境强制安装debug模块（不推荐） #

如果确实需要在生产环境使用debug功能，将yiisoft/yii2-debug从require-dev移到require区域：

{
    "require": {
        // 原有依赖项
        "yiisoft/yii2-debug": "~2.1.0"
    },
    "require-dev": {
        // 移除yiisoft/yii2-debug，保留其他开发依赖
    }
}

修改后重新构建Docker镜像，composer install --no-dev就会安装该模块。

Dockerfile优化建议 #

调整文件复制顺序，利用Docker缓存减少构建时间：

FROM yiisoftware/yii2-php:8.2-apache

RUN a2enmod rewrite

WORKDIR /app

# 先复制composer配置文件，缓存依赖安装层
ADD composer.lock composer.json /app/
RUN composer install --prefer-dist --optimize-autoloader --no-dev && \
    composer clear-cache

# 再复制项目代码
COPY . /app

RUN mkdir -p runtime web/assets && \
    chmod -R 775 runtime web/assets && \
    chown -R www-data:www-data runtime web/assets

RUN echo "ServerName localhost" >> /etc/apache2/apache2.conf

# 设置生产环境变量
ENV YII_ENV=prod
ENV YII_DEBUG=false

内容的提问来源于stack exchange，提问作者mightycode Newton