本文详解 laravel sail 在 apple silicon mac（m1/m2）上因 mysql/mariadb 驱动配置不当导致的 “could not find driver” 错误，重点解决 `db_host` 解析异常与 `mysql_root_host` 冲突问题，并提供安全、可复用的配置方案。
该错误看似是 PHP 缺失 PDO MySQL 扩展（即“could not find driver”），但在 Laravel Sail 环境中，实际根源通常是数据库连接配置与 Docker 网络解析不一致所致。尤其在 Apple Silicon Mac（M1/M2）上，Docker Desktop 对 localhost 和容器间 DNS 解析存在细微差异，而 sail 命令底层调用的是宿主机的 PHP CLI（非容器内 PHP），因此 DB_HOST 的值必须与宿主机能真实访问的地址匹配。
关键矛盾点在于：
- sail artisan migrate 或 sail tinker 运行在 宿主机的 PHP 环境 中（通过 sail 脚本代理）；
- .env 中的 DB_HOST=mariadb 会被宿主机 PHP 直接解析 —— 但 mariadb 是 Docker 容器服务名，仅在 Docker 内部网络中有效，宿主机无法通过该域名解析到 MariaDB 容器；
- 因此，当 DB_HOST=mariadb 时，宿主机 PHP 尝试连接 mariadb:3306 失败，PDO 报错“could not find driver”，实为连接超时/拒绝后被 Laravel 误判为驱动缺失（底层 mysqli_connect() 或 PDO::__construct() 返回 false，框架未区分具体原因）。
✅ 正确做法：统一使用 127.0.0.1 作为 DB_HOST 值，并确保 MariaDB/MySQL 容器允许来自 127.0.0.1 的连接。
✅ 推荐配置步骤（安全且无需反复修改）
-
修改 docker-compose.yml（推荐永久生效）
注释或删除 mariadb 服务下的 MYSQL_ROOT_HOST: "%" 行（如答案所述）。该配置会强制 MariaDB 绑定到所有接口，但可能引发权限冲突或监听异常；更稳妥的方式是显式指定 bind-address：services: mariadb: image: 'mariadb:11' # ⚠️ 移除或注释以下行（避免 root host 冲突） # MYSQL_ROOT_HOST: "%" command: ['--bind-address=0.0.0.0'] environment: MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}' MYSQL_DATABASE: '${DB_DATABASE}' ports: - '${FORWARD_DB_PORT:-3306}:3306' volumes: - 'sail-mariadb:/var/lib/mysql' networks: - sail -
更新 .env 文件（一次设置，长期有效）
kashen-mysql DDLtoExcel下载解析 MySQL 8.0 的 DDL 脚本，并将表结构导出为 Excel 格式。适用于用户需将 MySQL 的 `CREATE TABLE` 语句转换为结构化的 Excel 文件场景，导出内容包含字段名、数据类型、长度及精度等信息。支持多张表的批量处理，每张表对应 Excel 中的一个独立工作表。适用于数据库文档编写、数据字典生成及模式分析等任务。
DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_database DB_USERNAME=sail DB_PASSWORD=password
✅ 注意：DB_HOST=127.0.0.1（而非 localhost）可绕过 Unix socket 优先逻辑，确保走 TCP 连接；DB_PORT 必须与 docker-compose.yml 中 ports 映射的宿主机端口一致（默认 3306）。
-
重启服务并验证
sail down sail up -d sail artisan migrate:fresh --seed
若仍报错，请检查宿主机是否已安装 pdo_mysql 扩展（Sail 默认不依赖宿主机扩展，但 sail 命令若被误配为调用本地 PHP，则需确认）：
php -m | grep pdo_mysql # 应输出 pdo_mysql
? 补充说明：为何 tinker 显示连接成功？
tinker 输出 Illuminate\Database\MySqlConnection {#525} 仅表示 Laravel 成功实例化了连接对象，并不代表已建立真实数据库连接。Laravel 采用懒加载（lazy connection），首次执行查询（如 DB::table('users')->get()）时才真正尝试连接。因此，DB::connection() 不报错 ≠ 数据库连通。
✅ 最佳实践总结
- ✅ 始终用 DB_HOST=127.0.0.1 + 显式 DB_PORT 配合 Sail；
- ✅ 避免在 docker-compose.yml 中设置 MYSQL_ROOT_HOST: "%", 改用 command: ['--bind-address=0.0.0.0']；
- ✅ 不要临时切换 DB_HOST 值（如迁移时切 127.0.0.1，完后切回 mariadb），易引发环境不一致；
- ✅ 如需在容器内运行命令（如 CI 或调试），改用 sail artisan（自动进入容器执行），此时 DB_HOST=mariadb 才生效。
遵循以上配置，即可在 Mac（含 M1/M2）上稳定使用 Laravel Sail 连接 MariaDB/MySQL，彻底规避 “could not find driver” 的误导性报错。
