Laravel Sail 中数据库连接问题的分析与解决

问题背景

在使用 Laravel Sail 进行本地开发时，开发者可能会遇到数据库连接失败的问题。具体表现为访问应用首页时出现 SQLSTATE[HY000] [2002] 错误，提示 "php_network_getaddresses: getaddrinfo for mysql failed: Temporary failure in name resolution"。

错误原因分析

这个错误通常表明 PHP 应用容器无法解析 MySQL 容器的主机名。在 Docker 环境中，容器间的网络通信需要特别注意以下几点：

1. 容器命名解析：默认情况下，Laravel Sail 配置中会使用 "mysql" 作为数据库服务名称，PHP 应用会尝试连接这个主机名

2. 网络配置：Docker 为每个容器创建独立的网络命名空间，容器间需要通过正确的网络配置才能相互通信

3. 环境变量配置：.env 文件中的 DB_HOST 设置必须与 Docker 网络中的实际服务名称匹配

解决方案

标准配置下的解决方法

对于未修改默认配置的项目，可以尝试以下步骤：

1. 确保已正确启动所有服务：

sail up -d

2. 运行数据库迁移：

sail artisan migrate

3. 如果问题仍然存在，检查网络连接状态

自定义配置下的解决方法

如果开发者修改了默认的 docker-compose.yml 配置（如更改服务名称或端口），需要相应调整环境变量：

1. 修改 .env 文件中的 DB_HOST 为 Docker 内部主机名：

DB_HOST=host.docker.internal

2. 或者使用修改后的服务名称：

DB_HOST=projectname-mysql

3. 确保端口映射正确，并在 .env 中更新 DB_PORT

最佳实践建议

1. 保持默认配置：除非有特殊需求，建议保留 Sail 的默认配置，减少配置错误的可能性

2. 环境一致性：确保开发、测试和生产环境使用相似的配置，避免环境差异导致的问题

3. 网络调试：遇到连接问题时，可以使用以下命令进入容器内部测试网络连接：

sail exec laravel.test ping mysql

4. 日志检查：查看容器日志有助于诊断问题：

sail logs mysql

总结

Laravel Sail 提供了开箱即用的 Docker 开发环境，但在自定义配置时需要注意服务名称和网络设置的匹配。数据库连接问题通常源于主机名解析失败，通过正确配置 DB_HOST 环境变量可以解决大多数连接问题。保持环境配置的一致性和简单性，能够有效提高开发效率并减少此类问题的发生。