本文详解 Docker 环境下 PHP 通过 mhsendmail 连接 MailHog 的完整配置方案，解决 dial tcp 127.0.0.1:1025: connection refused 错误，涵盖镜像构建、网络互通、路径配置及验证方法。
本文详解 docker 环境下 php 通过 mhsendmail 连接 mailhog 的完整配置方案，解决 `dial tcp 127.0.0.1:1025: connection refused` 错误，涵盖镜像构建、网络互通、路径配置及验证方法。
该错误的根本原因在于：PHP 容器内 mhsendmail 默认尝试连接 localhost:1025（即容器自身环回地址），而非同属 app-network 的 mailhog 服务。即使 docker-compose.yml 正确声明了服务依赖与网络，若未显式指定 --smtp-addr=mailhog:1025（注意等号写法），或二进制版本/权限/配置加载顺序存在缺陷，均会导致连接被拒绝。
✅ 正确配置要点
1. 使用预编译二进制替代 go get 构建
go get 在容器中编译可能引入兼容性问题或路径混乱；推荐直接下载官方 Release 二进制：
# 替换原有 go get + cp 步骤
RUN curl -LkSso /usr/bin/mhsendmail 'https://github.com/mailhog/mhsendmail/releases/download/v0.2.0/mhsendmail_linux_amd64' && \
chmod +x /usr/bin/mhsendmail && \
echo 'sendmail_path = "/usr/bin/mhsendmail --smtp-addr=mailhog:1025"' > /usr/local/etc/php/conf.d/mhsendmail.ini⚠️ 注意：
- 使用
conf.d/mhsendmail.ini而非直接覆盖php.ini，避免被后续挂载的local.ini覆盖；--smtp-addr=mailhog:1025中的=是关键（部分旧版解析器要求严格格式）；chmod +x确保可执行权限。
2. 验证网络连通性（容器内调试）
进入 PHP 容器后，执行：
立即学习“PHP免费学习笔记（深入）”；
# 测试 DNS 解析与端口连通性 nslookup mailhog # 应返回 mailhog 容器 IP telnet mailhog 1025 # 或使用：echo "" | nc -w3 mailhog 1025
若 telnet 不可用，可临时安装：
apt-get update && apt-get install -y telnet netcat
3. PHP 配置生效验证
检查最终生效的配置：
docker exec GKapp php -i | grep sendmail_path # 输出应为：sendmail_path => /usr/bin/mhsendmail --smtp-addr=mailhog:1025
4. 测试脚本（推荐 CLI 方式）
创建 test-mail.php 并运行：
<?php
// test-mail.php
$ok = mail(
'test@example.com',
'MailHog Test',
"Hello from Docker!\nTime: " . date('Y-m-d H:i:s'),
"From: <test@localhost>\r\n"
);
var_dump($ok); // true 表示调用成功（不保证送达，仅表示 mhsendmail 接收成功）执行：
docker exec GKapp php /var/www/test-mail.php
随后访问 http://localhost:8025（MailHog Web UI），即可查看捕获的邮件。
❗ 常见陷阱与修复
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
connection refused on 127.0.0.1:1025
|
mhsendmail 未正确读取 --smtp-addr，回退至默认 localhost |
确保 sendmail_path 中 = 存在且无空格，使用 .ini 文件而非覆盖主 php.ini
|
mail() 返回 false 但无报错 |
sendmail_path 配置未生效（如被挂载的 local.ini 覆盖） |
检查 php -i \| grep conf.d 加载顺序，将配置放入 /usr/local/etc/php/conf.d/ 下独立 .ini 文件 |
| MailHog UI 无邮件 | PHP 容器与 MailHog 网络隔离 | 确认 docker-compose.yml 中两者共用同一 networks，且无 depends_on 逻辑错误（Docker Compose v3+ 不保证启动顺序，但 DNS 解析需服务已就绪） |
✅ 最终推荐 Dockerfile 片段（精简可靠）
# ... 其他基础配置（如 PHP 安装）
# 安装 mhsendmail（预编译二进制）
RUN curl -LkSso /usr/bin/mhsendmail 'https://github.com/mailhog/mhsendmail/releases/download/v0.2.0/mhsendmail_linux_amd64' && \
chmod +x /usr/bin/mhsendmail
# 独立配置文件，确保优先级与持久性
RUN echo 'sendmail_path = "/usr/bin/mhsendmail --smtp-addr=mailhog:1025"' > /usr/local/etc/php/conf.d/mhsendmail.ini
# 清理缓存
RUN rm -rf /var/lib/apt/lists/*完成构建后，重启服务：
docker-compose down && docker-compose up -d --build
至此，PHP 的 mail() 函数即可稳定通过 MailHog 捕获测试邮件，彻底规避 connection refused 错误。
