Yii2中localhost连接失败主因是Unix socket路径不匹配，改为127.0.0.1强制走TCP可立即解决；macOS需同步配置php.ini中mysql.default_socket、pdo_mysql.default_socket和mysqli.default_socket三处路径，并重启Web服务。
“SQLSTATE[HY000] [2002]” 错误：host 写成 localhost 就连不上
这是 Yii2 最常卡住人的点——dsn 里写 mysql:host=localhost;dbname=xxx，本地开发环境（尤其是 macOS 或某些 Linux 发行版）会走 Unix socket，但 Yii 的 PDO 初始化逻辑可能没对齐 MySQL 实际监听路径，结果报错 “Connection refused” 或 “No such file or directory”。
直接改 localhost 成 127.0.0.1 就能绕过 socket 查找，强制走 TCP 连接：
'dsn' => 'mysql:host=127.0.0.1;dbname=yii2basic'
- 不用重启 MySQL，改完配置立刻生效（记得清 Yii 缓存：
php yii cache/flush-all） - 如果还连不上，加
port=3306显式声明，避免端口被其他服务占位 - Windows 下一般不受影响，但 Docker 环境中容器间通信也建议用
127.0.0.1或实际宿主机 IP，别信localhost
macOS 上报 “Can't connect to local MySQL server through socket”
错误信息里带 /tmp/mysql.sock 或类似路径，说明 PHP 找不到 MySQL 的 socket 文件。Yii 底层用的是 PDO 和 mysqli，但默认只读 mysql.default_socket，漏了另外两个。
打开 /etc/php.ini（或你当前 PHP CLI / Web SAPI 对应的配置），补全这三行：
mysql.default_socket = /tmp/mysql.sock pdo_mysql.default_socket = /tmp/mysql.sock mysqli.default_socket = /tmp/mysql.sock
- macOS 默认 socket 路径是
/tmp/mysql.sock，MAMP 或 Homebrew 安装的 MySQL 可能是/usr/local/var/mysql/mysql.sock，得先用mysql --socket=/path/to/socket -u root -p验证 - 改完必须重启 Web 服务（如 Apache：
sudo apachectl restart；Nginx + PHP-FPM：sudo brew services restart php） - CLI 模式下运行
php -i | grep socket确认三处值已生效
“Access denied for user 'root'@'localhost'” 但密码明明是对的
这个报错不是 Yii 的锅，是 MySQL 权限层拒绝了连接。常见于新装 MySQL（8.0+）或重置 root 密码后未刷新权限。
- 进 MySQL 执行：
SELECT host, user FROM mysql.user;，确认是否存在'root'@'127.0.0.1'这条记录（而不仅是'root'@'localhost'） - 如果只有
'root'@'localhost'，但 Yii 连的是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'; FLUSH PRIVILEGES; - MySQL 8.0 默认认证插件是
caching_sha2_password，PHP 7.4 以下版本不支持，可临时降级：ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
配置没错，但 yii migrate 或控制器里查不到表
不是连不上，而是连上了却找不到库或表——大概率是 dbname 拼错、大小写敏感、或数据库压根没建。
- 检查
dsn中的dbname是否和 MySQL 里SHOW DATABASES;输出一致，Linux/macOS 下库名区分大小写 - 执行
php yii db（需启用yii\console\controllers\DbController）测试连通性，它会尝试SELECT 1并打印 DB 名字 - 如果用的是多数据库配置（
db1,db2），确认 Model 类里显式指定了public static function getDb() { return \Yii::$app->get('db1'); }，否则默认走db
真正麻烦的从来不是语法，而是 MySQL 认证方式、socket 路径、host 解析顺序这三者在不同系统上的隐式耦合——调的时候得同时盯住 Yii 日志、MySQL 错误日志、以及 php -m | grep -E "(pdo|mysql)" 的扩展加载状态。
