Yii 2 数据库连接失败需优先检查配置文件加载路径（main-local.php或db-local.php）、Unix socket路径一致性（localhost改127.0.0.1或同步php.ini三处socket配置）、MySQL用户host匹配（如root@'127.0.0.1'需显式授权）。
连接失败时先确认 db 配置落在哪个文件
Yii 2 的数据库配置不写在 main.php，而是由环境加载机制决定——最终生效的是 main-local.php（高级模板）或 db-local.php（基础模板）。这个文件通常被 .gitignore 排除，容易被误删或漏建。
常见错误现象：CDbConnection failed to open the DB connection，但你刚改了 main.php ——其实它根本没被读。
- 检查
config/目录下是否存在main-local.php；若不存在，手动创建，内容必须包含完整'components' => ['db' => [...]]结构，并以return $config;结尾 - 运行
php yii serve或访问首页前，用php -r "var_dump(require 'config/main-local.php');"快速验证该文件语法是否合法、是否返回数组 - Docker 环境中注意：若 PHP 容器和 MySQL 容器分离，
host必须填容器名（如mysql），不能填localhost或127.0.0.1（后者会指向 PHP 容器自身）
localhost 连不上？大概率是 Unix socket 路径错位
报错 SQLSTATE[HY000] [2002] Can't connect to local MySQL server through socket 或 Connection refused，本质是 PHP 尝试通过 Unix socket 连接 MySQL，但路径对不上。macOS 和部分 Linux 发行版尤其高发。
- 最简解法：把 DSN 中的
host=localhost改成host=127.0.0.1，强制走 TCP，绕过 socket 查找 - 若仍需用
localhost（比如某些 Docker Compose 场景），则必须同步配置 PHP 的三处 socket 路径：mysql.default_socket、pdo_mysql.default_socket、mysqli.default_socket，值需与 MySQL 实际监听路径一致（可用mysql --socket=/path/to/mysql.sock -u root -p验证） - 改完
php.ini后，必须重启 Web 服务（Apache/Nginx+PHP-FPM）或 CLI SAPI（如brew services restart php），仅重启 PHP 进程无效
Access denied for user 'root'@'localhost' 但密码没错
这不是 Yii 的问题，是 MySQL 权限表没覆盖连接来源。MySQL 8.0+ 默认只创建 'root'@'localhost'，而 Yii 用 127.0.0.1 连时，实际匹配的是 'root'@'127.0.0.1' —— 若该记录不存在，就拒绝。
- 进 MySQL 执行：
SELECT host, user FROM mysql.user;，确认是否存在'root'@'127.0.0.1' - 若无，执行：
CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'your_password'; GRANT ALL PRIVILEGES ON *.* TO 'root'@'127.0.0.1' WITH GRANT OPTION; FLUSH PRIVILEGES; - Windows 下一般不受影响；但 WSL2 或 Docker 桥接网络中，宿主机 MySQL 对容器而言也是远程，
host应设为宿主机 IP（如172.17.0.1），而非localhost
增删改查代码跑不通？先绕过 AR 测通底层连接
别急着 debug User::find()->all()，先用最原始方式验证 PDO 是否真通。AR 层的报错经常掩盖真实连接问题。
- 在控制器或
web/index.php末尾加测试代码：
try {
Yii::$app->db->open();
echo "PDO 连接成功";
} catch (\Exception $e) {
echo "PDO 错误：" . $e->getMessage();
}- 若报错含
Plugin 'caching_sha2_password' is not loaded，说明 MySQL 8.0+ 默认认证插件不被旧版 PHP 驱动支持，需在 MySQL 中执行：ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password'; - 若报错
Unknown database，说明dbname写错或库还没建；若报SQLSTATE[42000]开头，大概率是initSQLs里 SQL 语法错误（比如SET NAMES utf8mb4写成utf8）
真正卡住人的地方往往不是语法，而是配置文件加载路径、socket 路径一致性、以及 MySQL 用户 host 匹配逻辑这三处——它们不报具体 PDO 错误，只抛笼统异常，得一层层剥开看。
