Symfony与Docker集成时数据库连接主机名解析失败怎么解决

Symfony项目与Docker集成部署时，数据库连接主机名解析失败是较为常见的问题，该问题会导致应用启动时抛出数据库连接异常，无法正常执行业务逻辑。这种问题本质上多是Docker容器网络或服务配置不匹配导致的，需要从多个维度排查解决。

问题成因分析

出现数据库连接主机名解析失败的核心原因是Symfony容器无法识别配置的数据库主机名对应的IP地址，常见诱因有以下几类：

• Docker Compose中数据库服务名与Symfony配置的数据库主机名不一致，导致DNS解析失败
• Symfony环境变量未正确加载，数据库DSN配置使用了错误的主机名
• Docker容器未处于同一自定义网络，不同网络的容器无法互相解析服务名
• 数据库容器未正常启动，导致主机名对应的服务不存在

排查步骤

1. 检查Docker Compose服务配置

首先查看docker-compose.yml中数据库服务的名称，确认Symfony配置的数据库主机名是否与该名称完全一致。以下是标准的docker-compose.yml示例：

version: '3.8'
services:
  php:
    build: .
    depends_on:
      - mysql
    environment:
      DATABASE_URL: "mysql://root:123456@mysql:3306/symfony_db?serverVersion=8.0"
    networks:
      - symfony_net
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_DATABASE: symfony_db
    networks:
      - symfony_net
networks:
  symfony_net:
    driver: bridge

上述配置中数据库服务名为mysql，Symfony的DATABASE_URL中主机名也必须为mysql，否则会出现解析失败。

2. 验证容器网络连通性

进入Symfony所在的PHP容器，尝试ping数据库服务名，确认网络是否通畅：

# 进入php容器
docker exec -it 项目目录_php_1 bash
# 测试解析数据库服务名
ping mysql

如果ping不通，说明容器不在同一网络，需要检查docker-compose.yml中的networks配置，确保所有相关服务都加入了同一个自定义网络。

3. 检查Symfony环境变量配置

查看Symfony项目的.env或.env.local文件，确认DATABASE_URL的配置是否正确，主机名是否与Docker Compose中的数据库服务名一致：

# .env.local 配置示例
DATABASE_URL="mysql://db_user:db_password@mysql:3306/db_name?serverVersion=8.0&charset=utf8mb4"

解决方案

1. 统一服务名与主机名配置

确保Docker Compose中数据库服务的名称，和Symfony配置的数据库主机名完全一致，这是最常见的解决方式。如果修改了服务名，需要重启所有容器使配置生效：

docker-compose down
docker-compose up -d

2. 调整Docker网络配置

如果之前使用的是默认网络，建议创建自定义bridge网络，将所有服务加入该网络，避免不同项目容器网络冲突。修改docker-compose.yml的networks部分即可，配置方式参考上文的docker-compose.yml示例。

3. 检查数据库容器启动状态

如果数据库容器未正常启动，也会导致主机名解析失败，可以通过以下命令查看容器状态：

docker-compose ps

如果mysql服务状态不是up，需要查看日志排查启动失败的原因：

docker-compose logs mysql

验证解决效果

完成配置修改后，重新访问Symfony应用，或者执行Symfony的数据库命令验证连接是否正常：

# 进入php容器后执行
php bin/console doctrine:database:create

如果命令执行成功，说明数据库连接主机名解析问题已经解决。

SymfonyDocker数据库连接主机名解析docker_compose修改时间：2026-06-10 23:33:24