如何解决Symfony与Docker数据库连接中的主机名解析问题

在Symfony与Docker结合的开发部署场景中，数据库连接的主机名解析问题是高频出现的故障点，很多开发者在配置完成后启动应用时会遇到数据库无法连接的报错，多数情况都和主机名无法被容器正确解析有关。

问题常见表现

当主机名解析出现问题时，Symfony通常会抛出数据库连接相关的异常，常见的错误信息包括：

• SQLSTATE[HY000] [2002] Connection refused
• SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo failed: Name or service not known
• 数据库服务器响应超时，应用启动卡住无法继续运行

问题成因分析

Docker网络与服务命名规则

Docker Compose启动多个服务时，默认会为所有服务创建一个独立的桥接网络，每个服务在network中的主机名默认就是docker-compose.yml中定义的服务名称。如果Symfony的数据库配置中填写的主机名和Docker服务名不一致，就会导致解析失败。

Symfony环境配置问题

Symfony的数据库配置通常存放在.env文件或者config/packages/doctrine.yaml中，如果配置的环境变量没有正确映射到Docker容器中，或者本地开发环境和Docker环境的配置没有区分，也会出现主机名解析错误。

网络隔离问题

如果数据库容器和Symfony应用容器没有处于同一个Docker网络中，应用容器就无法通过网络访问到数据库容器的主机名，从而导致解析失败。

排查步骤

1. 检查Docker服务状态与网络

首先确认Docker Compose的所有服务都正常启动，执行以下命令查看运行中的容器：

# 查看当前项目启动的容器
docker-compose ps
# 查看容器所属的网络
docker network ls
# 查看指定网络的详细信息，替换network_name为实际网络名
docker network inspect network_name

在网络的详细信息中，可以看到所有连接到该网络的容器，以及对应的主机名和IP地址，确认数据库服务和Symfony服务是否都在同一个网络中。

2. 测试容器内主机名解析

进入Symfony应用所在的容器，测试能否解析数据库服务的主机名：

# 进入Symfony应用容器，替换symfony_container_name为实际容器名
docker exec -it symfony_container_name bash
# 在容器内测试解析数据库主机名，替换db_service_name为数据库服务名
ping db_service_name
# 或者使用nslookup测试
nslookup db_service_name

如果解析失败，说明容器网络或者主机名配置有问题。

3. 检查Symfony数据库配置

查看Symfony的.env文件中的数据库相关配置：

# 数据库配置示例，DATABASE_HOST需要和Docker数据库服务名一致
DATABASE_URL="mysql://db_user:db_password@db_service_name:3306/db_name?serverVersion=5.7"

同时检查config/packages/doctrine.yaml中的配置是否正确引用了环境变量：

doctrine:
    dbal:
        # 这里需要确保url配置正确引用了DATABASE_URL环境变量
        url: '%env(resolve:DATABASE_URL)%'
        # 也可以单独配置host，同样需要和Docker服务名一致
        # host: '%env(DATABASE_HOST)%'

解决方案

1. 统一Docker服务名与数据库配置主机名

确保docker-compose.yml中数据库服务的名称和Symfony配置中的数据库主机名完全一致，示例配置如下：

version: '3.8'
services:
  # Symfony应用服务
  php:
    build: .
    volumes:
      - .:/var/www/html
    depends_on:
      - db
    networks:
      - app_network
  # 数据库服务，服务名为db，对应Symfony配置中的主机名db
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: db_name
      MYSQL_USER: db_user
      MYSQL_PASSWORD: db_password
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - app_network
networks:
  app_network:
    driver: bridge
volumes:
  db_data:

此时Symfony的.env文件中数据库主机名需要填写为db，和Docker服务名保持一致。

2. 确保容器处于同一网络

如果之前的服务没有显式声明网络，需要为所有相关服务添加到同一个自定义网络中，避免默认网络隔离导致的问题。可以参考上面的docker-compose.yml示例，显式定义app_network网络，并将php和db服务都加入该网络。

3. 区分环境配置

如果本地开发不使用Docker，需要为Docker环境单独配置环境变量，可以在docker-compose.yml中单独为php服务设置环境变量，覆盖本地的.env配置：

services:
  php:
    build: .
    volumes:
      - .:/var/www/html
    depends_on:
      - db
    networks:
      - app_network
    environment:
      # 覆盖DATABASE_URL配置，使用Docker内部的主机名
      DATABASE_URL: "mysql://db_user:db_password@db:3306/db_name?serverVersion=5.7"

4. 清理Docker缓存后重启

如果修改了配置还是有问题，可以尝试清理Docker的缓存和网络，重新启动服务：

# 停止并删除容器、网络
docker-compose down
# 重新构建并启动服务
docker-compose up -d --build

总结

Symfony与Docker数据库连接的主机名解析问题核心就是Docker网络内的服务名称映射，只要保证Symfony配置的数据库主机名和Docker Compose中数据库服务的名称一致，并且两个容器处于同一个网络中，大部分解析问题都可以解决。排查时可以从容器网络、主机名解析测试、Symfony配置三个维度逐步定位问题，再针对性调整配置即可。

SymfonyDockerdocker_composeMySQLhostname_resolution修改时间：2026-06-05 16:01:10