Docker构建Laravel镜像运行时出现SQLSTATE[HY000] [2002]连接错误

问题根本原因 #

docker-compose 启动时，所有服务（php、mysql 等）都加入了自定义的 laravel 网桥，Docker 内置 DNS 会自动将服务名 mysql 解析为对应 mysql 容器的内网 IP，所以数据库连接正常。而你单独 docker run 运行构建好的 Laravel 镜像时，默认会加入 Docker 的默认 bridge 网络，和 docker-compose 创建的 laravel 网络是二层隔离的，既无法通过服务名 mysql 做 DNS 解析，也无法直接访问 mysql 容器的内网 IP，所以出现各类连接报错。

你之前尝试的三种配置报错原因对应如下：

• 填 127.0.0.1/localhost：指向的是 Laravel 容器自身的回环地址，容器内没有运行 mysql 服务，所以报连接拒绝/找不到 sock 文件
• 填 mysql 容器的内网 IP 172.19.0.3：默认 bridge 网络和 laravel 网络隔离，路由不通所以超时

解决方案 #

方案1：运行镜像时加入 docker-compose 创建的 laravel 网络 #

适合本地测试，直接复用已启动的 mysql 容器：

1. 先确认 laravel 网络存在，执行 docker network ls 能看到名称为 laravel 的网络
2. 运行镜像时指定加入该网络即可，可直接传入数据库配置覆盖镜像内的 .env 参数：

docker run -d -p 8080:80 --network laravel -e DB_HOST=mysql 你的镜像名

此时容器和 mysql 在同一个网络内，直接用服务名 mysql 就能正常连接。

方案2：修改 DB_HOST 为宿主机 IP，用 mysql 映射的宿主机端口连接 #

适合需要把 Laravel 容器和 mysql 分开部署的场景：

1. 你的 docker-compose 已经配置了 mysql 3306 端口映射到宿主机 3306，确认宿主机 3306 端口对外开放
2. 将 .env 的 DB_HOST 改为你宿主机的局域网/公网 IP，不要填 127.0.0.1
3. 构建镜像后直接运行即可：

docker run -d -p 8080:80 你的镜像名

提示：Windows/macOS 环境的 Docker 桌面版，也可以直接填 host.docker.internal 作为 DB_HOST，这是 Docker 内置的指向宿主机的域名。

方案3：优化镜像构建逻辑，避免配置固化 #

你的 Dockerfile 里直接 COPY . . 会把本地的 .env 也打包到镜像里，不符合容器化最佳实践，配置应该在运行时注入，而不是固化在镜像内：

1. 把 .env 加入 .dockerignore 文件，避免打包到镜像
2. 运行容器时通过 -e 参数传入所有需要的环境变量，或者用 --env-file 指定外部 .env 文件：

docker run -d -p 8080:80 --network laravel --env-file ./.env 你的镜像名

额外配置修正建议 #

你当前的 docker-compose 配置存在两处错误，建议提前修改避免后续异常：

• nginx 服务的 networks 配置为 dataliteracyapp，和其他服务的 laravel 网络不一致，会导致 nginx 无法转发请求到 php 服务，统一改为 laravel 即可
• mysql 服务的 volumes 里错误挂载了 nginx 的配置文件到 mysql 的 conf.d 目录，直接删掉这行挂载配置即可

内容的提问来源于stack exchange，提问作者Del