如何正确搭建PHP Yii2扩展模块开发调试环境？解决命名空间加载异常

方案一：Composer本地关联开发（推荐） #

这种方式既能独立管理扩展代码（不受主项目.gitignore影响），又能让Yii2正常加载扩展命名空间：

• 1. 单独创建扩展仓库目录
     在主项目同级目录新建comp-blog（名称可自定义），按照Yii2扩展规范搭建结构：

  comp-blog/
    src/
      Module.php       // 模块核心文件，命名空间声明为comp\blog
      controllers/     // 控制器目录
      models/          // 模型目录
    composer.json      // 扩展的Composer配置文件
  

  扩展的composer.json配置示例：

  {
    "name": "comp/blog",
    "type": "yii2-extension",
    "autoload": {
      "psr-4": {
        "comp\\blog\\": "src/"
      }
    },
    "require": {
      "yiisoft/yii2": "~2.0.0"
    }
  }
  

• 2. 主项目关联本地扩展
     编辑主项目根目录的composer.json，添加本地仓库配置：

  {
    "repositories": [
      {
        "type": "path",
        "url": "../comp-blog" // 根据实际路径调整，指向你的扩展目录
      }
    ]
  }
  

• 3. 安装扩展并生成软链接
     在主项目根目录执行命令：

  composer require comp/blog:@dev
  

  执行后Composer会在vendor/comp目录下创建软链接指向本地扩展目录，既不影响主项目的.gitignore（扩展代码在独立仓库提交），又能让Yii2自动加载扩展的命名空间。

方案二：直接在项目目录内开发扩展 #

如果不想拆分独立仓库，直接在主项目内开发，需手动配置命名空间映射解决加载失败问题：

• 1. 放置扩展文件
     在主项目根目录新建extensions目录，将扩展放在extensions/comp/blog/src下，确保目录结构与命名空间严格对应：comp\blog\Module对应文件路径extensions/comp/blog/src/Module.php，且文件内声明命名空间：

  <?php
  namespace comp\blog;
  
  use yii\base\Module;
  
  class Module extends Module
  {
      // 模块逻辑代码
  }
  

• 2. 配置Composer自动加载
     编辑主项目的composer.json，在autoload的psr-4节点添加扩展的命名空间映射：

  {
    "autoload": {
      "psr-4": {
        "comp\\blog\\": "extensions/comp/blog/src/"
      }
    }
  }
  

• 3. 更新自动加载缓存
     执行命令更新Composer的自动加载规则：

  composer dump-autoload
  

• 4. 注册模块到Yii2配置
     在主项目的配置文件（如config/web.php或config/main.php）的modules节点添加模块注册：

  'modules' => [
      'blog' => [
          'class' => 'comp\blog\Module',
          // 模块的其他配置项
      ],
  ],
  

常见注意事项 #

• 命名空间必须与目录结构严格匹配，大小写也要一致（Yii2对大小写敏感）
• 每次修改composer.json的自动加载配置后，必须执行composer dump-autoload更新缓存
• 确保扩展目录的文件权限正常，Yii2应用有权限读取扩展文件

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