Django中send_mail无报错无异常，邮件发送失败如何排查？

安全阿岳

2026-7-3

问题描述

我尝试发送SMTP邮件但功能异常，不知道如何调试：

在settings.py中设置了错误的端口：

EMAIL_PORT = 3

在Django Shell中执行send_mail未报错，返回值为1：

from django.core.mail import send_mail

send_mail(
    'Test Email',
    'That is an test.',
    'test@test.com',
    ['test@gmail.com'],
    fail_silently=False,
)

已配置根日志器记录所有DEBUG级别的日志，但日志文件中无任何内容：

...
'loggers': {
    '': {
        'handlers': ['file'],
        'level': 'DEBUG',
        'propagate': True,
    },
...

这是默认行为吗？我哪里操作出错了？

回答

1. 为什么`send_mail`返回1且不报错？

send_mail的返回值代表成功进入发送流程的邮件数量，不是邮件实际送达的数量。正常情况下，当fail_silently=False时，SMTP连接失败应该直接抛出smtplib.SMTPException相关异常，但出现这种情况大概率是以下原因：

使用了异步邮件后端：如果你的EMAIL_BACKEND配置的是异步后端（比如基于Celery的后端、django-anymail的异步模式等），send_mail只会把发送任务加入队列，不会立即执行SMTP连接，所以不会当场报错，返回1表示任务已成功入队。实际发送失败的错误会在队列worker执行任务时才会触发。
极端网络环境异常：极少数情况下，你的网络环境中端口3被异常监听（比如某些奇怪的代理或本地服务），导致SMTP连接能建立但后续发送失败，但这种情况非常罕见。

2. 为什么日志没有记录内容？

你只配置了根日志器的规则，但日志能否正常写入还要看handlers部分的完整配置，常见问题包括：

Handler级别不匹配：如果file handler的level设置为INFO或更高，会过滤掉DEBUG级别的日志；
文件路径错误/权限不足：日志文件所在目录不存在、路径写错，或者进程没有写入该文件的权限，都会导致日志无法生成；
Formatter未配置：如果handler指定了未定义的formatter，可能会导致日志写入失败（部分日志框架会静默忽略这种错误）。

检查你的handlers配置是否完整，比如：

'handlers': {
    'file': {
        'level': 'DEBUG',
        'class': 'logging.FileHandler',
        'filename': '/var/log/django/debug.log',  # 确保路径存在且有写入权限
        'formatter': 'verbose',
    },
},
'formatters': {
    'verbose': {
        'format': '{levelname} {asctime} {module} {message}',
        'style': '{',
    },
},

3. 调试步骤

步骤1：确认邮件后端类型

在Django Shell中执行以下命令，查看当前使用的邮件后端：

from django.conf import settings
print(settings.EMAIL_BACKEND)

如果不是默认的django.core.mail.backends.smtp.EmailBackend，参考对应后端的文档排查异步任务或队列日志。

步骤2：手动测试SMTP连接

直接用Python标准库smtplib测试连接，获取详细错误信息：

import smtplib
from django.conf import settings

# 替换为你的实际配置
smtp_server = settings.EMAIL_HOST
smtp_port = settings.EMAIL_PORT
sender = 'test@test.com'
recipient = 'test@gmail.com'

try:
    server = smtplib.SMTP(smtp_server, smtp_port, timeout=10)
    server.set_debuglevel(1)  # 开启调试模式，打印详细交互过程
    server.sendmail(sender, [recipient], 'Subject: Test\n\nTest message body')
    server.quit()
except Exception as e:
    print(f"SMTP Error: {e}")

这段代码会直接暴露连接或发送过程中的错误，比send_mail更直观。

步骤3：检查日志生效情况

在Django Shell中手动写入一条DEBUG日志，验证日志配置是否正常：

import logging
logger = logging.getLogger(__name__)
logger.debug("Test debug log message")

如果这条日志也没出现在文件中，说明日志handler的配置存在问题，重点检查路径、权限和级别。

步骤4：针对默认SMTP后端的额外调试

如果使用默认后端，确保EMAIL_USE_TLS和EMAIL_USE_SSL的配置与SMTP服务器要求匹配（比如端口3既不是标准的TLS端口587，也不是SSL端口465，这两个开关可能导致连接异常）。你也可以临时修改后端的调试级别，在settings.py中添加：

import logging
logging.getLogger('django.core.mail').setLevel(logging.DEBUG)

这样邮件模块的所有调试日志会被强制开启，便于排查问题。

内容的提问来源于stack exchange，提问作者Philipp S.