必须开启yii_debug=true、yii_env='dev'并强制error_reporting(e_all)和display_errors=1，否则异常被静默吞掉只显示空白500页。
报错被吞掉，只显示空白 500 页面
这是最常见的情况：Yii2 在生产模式下默认静默处理异常，不输出任何错误信息。你看到的“白屏”或“500 Internal Server Error”根本不是真实错误，而是框架兜底返回的通用响应。
必须手动打开 PHP 错误显示和 Yii 调试模式才能看到真实报错：
-
defined('YII_DEBUG') or define('YII_DEBUG', true);要在web/index.php开头确保这行存在且为true -
defined('YII_ENV') or define('YII_ENV', 'dev');同样要在web/index.php中设为'dev' - 额外加两行强制暴露错误：
error_reporting(E_ALL);和ini_set('display_errors', '1');（放在require __DIR__ . '/../vendor/autoload.php';之前） - 如果仍无输出，检查
php.ini中display_errors = On是否生效（CLI 和 Web SAPI 配置可能不同）
SQLSTATE[HY000] [2002] No such file or directory
这个错误本质是 PHP 找不到 MySQL 的 socket 文件路径，不是用户名密码错，也不是服务没起。典型出现在 macOS、Linux 或 Vagrant 环境中，host=localhost 触发 Unix socket 连接，但 PHP 配置里三处 socket 路径为空或不匹配。
解决步骤：
- 先查 MySQL 实际 socket 路径：
mysql --socket=/tmp/mysql.sock -u root -p -e "SELECT 1"或进 MySQL 执行SHOW VARIABLES LIKE 'socket'; - 找到当前 PHP 使用的
php.ini（php --ini查 CLI，phpinfo()查 Web），修改以下三项为同一路径：mysql.default_socket、pdo_mysql.default_socket、mysqli.default_socket - 改完必须重启 Web 服务（Apache/Nginx + PHP-FPM）或 Web 服务器进程，仅重启 MySQL 无效
- 更省事的临时方案：把 DSN 中的
host=localhost直接换成host=127.0.0.1，强制走 TCP，绕过 socket 查找
SSL connection error: unknown error number
这个错误常让人误以为是 Yii2 配错了 SSL 参数，其实 90% 是 MySQL 服务端压根没启用 SSL 支持。PDO 连接时发现服务端不支持，就直接报错，连握手都进不去。
验证和修复要点：
- 先连上 MySQL 执行：
SHOW VARIABLES LIKE 'have_ssl';，结果必须是YES，否则一切客户端配置都是空谈 - 确认
my.cnf中已配置ssl-ca、ssl-cert、ssl-key，且路径可读，然后重启mysqld - Yii2 中 SSL 参数不能写在 DSN 里（如
?sslmode=require无效），必须通过attributes数组传入：PDO::MYSQL_ATTR_SSL_CA、PDO::MYSQL_ATTR_SSL_CERT、PDO::MYSQL_ATTR_SSL_KEY - 路径必须是绝对路径，推荐用
__DIR__ . '/certs/ca.pem'拼接，避免相对路径失效
命令行执行 migrate 报错但浏览器访问正常
这种“环境不一致”问题多见于 Windows 主机 + Vagrant / Docker 开发场景。你在 Windows 命令行运行 php yii migrate，调用的是 Windows 本地的 PHP，而 Web 请求走的是虚拟机或容器里的 PHP —— 两者配置完全独立。
关键判断点：
- 运行
php --ini和php -m | grep pdo，确认 CLI 模式下pdo_mysql已加载、php.ini路径正确 - 检查 CLI 的
php.ini是否也设置了正确的mysql.default_socket等三项（很多教程只改了 Web 版本的配置） - Vagrant 用户请务必在虚拟机内执行命令：
vagrant ssh→cd /vagrant && php yii migrate - Docker 用户注意挂载的
php.ini是否覆盖了容器内配置，docker exec -it your-app php --ini查真实路径
真正容易被忽略的是：CLI 和 Web SAPI 的 php.ini 完全是两套，socket 路径、扩展开关、错误报告级别都可能不同。别假设“Web 能连，命令行就一定行”。
