CakePHP4.2迁移至5.x：非默认数据库报Datasource类找不到错误

我尝试了各种谷歌搜索，但找到的信息都不相关。现在正在把CakePHP 4.2的PHP应用迁移到CakePHP 5，发现只有default数据库能正常使用。

• 我在app_local.php里配置了多个数据库，和CakePHP 4里的配置方式完全一样，但只有default能工作。
• 执行命令/bin/cake schema_cache build --connection default时，缓存文件会正常生成在tmp/cache/model目录；但换成其他已配置的数据库时，会报错：

  Datasource class XXX could not be found.

• 如果把默认配置改成其他数据库名称，这个数据库的缓存就能生成，看起来系统只认default这一个数据库配置。
• 所有数据库都在同一主机，用的是相同的用户和MySQL配置。
• 尝试用代码声明数据库：

  ConnectionManager::setConfig('XXX', $config);
  $connection = ConnectionManager::get('XXX');
  

  会收到“数据源已声明”的错误；如果删掉app_local.php里XXX数据库的配置，又会返回：

  Missing Datasource

  Datasource class XXX could not be found.

• 已经多次执行composer update dumpautoload重新生成composer相关文件。
• 网上关于这个错误的帖子大多是旧内容，都是配置错误或数据库不可访问的问题，不确定有没有其他用户在最新版本里遇到同样的问题。

排查解决方向 #

1. 显式声明数据库配置的类名
   CakePHP 5对配置的依赖更严格，确保非默认数据库的配置里明确指定className和driver，不要依赖默认值：

   'XXX' => [
       'className' => \Cake\Database\Connection::class,
       'driver' => \Cake\Database\Driver\Mysql::class,
       'host' => 'localhost',
       'username' => 'your_user',
       'password' => 'your_pass',
       'database' => 'your_db',
       // 其他必要配置
   ]
   

2. 检查配置加载与合并逻辑
   在应用入口处临时添加代码，打印已配置的数据源列表，确认XXX是否被正确加载：

   var_dump(\Cake\Datasource\ConnectionManager::configured());
   

   如果列表里没有XXX，检查app.php是否正确合并了app_local.php的配置，或者是否存在配置覆盖的情况。

3. 手动清理全量缓存
   删除tmp/cache目录下的所有文件（包括model、persistent等子目录），然后重新执行缓存生成命令，避免旧缓存干扰新配置。

4. 验证驱动类拼写与命名空间
   确保配置中的driver类名拼写完全正确，比如MySQL驱动是\Cake\Database\Driver\Mysql::class，不要出现小写、拼写错误或命名空间错误。

5. 检查配置文件的加载顺序
   确认app_local.php是在app.php之后加载的，确保自定义数据库配置不会被主配置文件覆盖。

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