Django 6.1 邮件配置大改：旧项目如何平稳升级？

Django 6.1 邮件配置大改旧项目如何平稳升级Django 项目里的邮件配置很多年都长得差不多一个EMAIL_BACKEND再配上一组EMAIL_HOST、EMAIL_PORT和账号密码。项目只有一个发信通道时这套配置够用但当订单通知、管理员告警和营销邮件需要不同服务商时代码往往开始到处传连接对象。Django 6.1 RC1 引入了新的MAILERS配置并计划在 Django 7.0 移除旧邮件配置。它不是简单地给设置项换名字而是把“一个全局邮件后端”改成了“多个具名邮件通道”。本文用一个隔离实验验证迁移路径并给出老项目可以直接执行的升级清单。当前 Django 6.1 仍是候选版本不建议直接替换生产环境。本文适合提前改造、运行测试和排查第三方包兼容性。旧配置为什么开始吃力典型的旧项目通常这样配置EMAIL_BACKENDdjango.core.mail.backends.smtp.EmailBackendEMAIL_HOSTsmtp.example.comEMAIL_PORT587EMAIL_USE_TLSTrueEMAIL_HOST_USERos.environ[EMAIL_ACCOUNT]EMAIL_HOST_PASSWORDos.environ[EMAIL_PASSWORD]它的优点是直观但全站默认只有一套连接参数。如果事务邮件使用国内服务商、营销邮件使用海外服务商、管理员告警还要投递到本机中继就需要手动创建不同连接或者依赖第三方封装。Django 6.1 把配置方式改成了与DATABASES、CACHES、STORAGES类似的字典结构MAILERS{default:{BACKEND:django.core.mail.backends.smtp.EmailBackend,OPTIONS:{host:os.environ[DEFAULT_SMTP_HOST],port:587,use_tls:True,username:os.environ[DEFAULT_SMTP_USER],password:os.environ[DEFAULT_SMTP_PASSWORD],},},transactional:{BACKEND:django.core.mail.backends.smtp.EmailBackend,OPTIONS:{host:os.environ[ORDER_SMTP_HOST],port:465,use_ssl:True,username:os.environ[ORDER_SMTP_USER],password:os.environ[ORDER_SMTP_PASSWORD],},},}发送时不再手动拼连接而是通过using选择通道fromdjango.core.mailimportsend_mail send_mail(订单创建成功,订单已进入处理流程。,serviceexample.com,[readerexample.com],usingtransactional,)实验验证我做了什么实验环境如下Windows 11Python 3.12.1Django 6.1 RC1本地内存邮件后端不连接真实 SMTP不产生外部邮件。我配置了三个别名default、transactional和marketing然后分别通过后两个通道发送订单通知和技术通讯。实验结果检查项结果已识别邮件通道3 个隔离发信次数2 次事务邮件主题订单创建成功营销邮件主题八月技术通讯收件地址两封都正确这证明新配置可以在同一项目中按业务选择后端而且测试时仍能使用内存后端检查邮件主题、收件人和数量。老项目最稳妥的迁移顺序第一步先盘点不要边删边改搜索项目中的这些内容EMAIL_BACKEND EMAIL_HOST get_connection( connection fail_silently auth_user auth_password不仅要检查自己的代码还要检查邮件模板库、账号系统、后台任务和自定义邮件后端。官方迁移文档特别提醒测试环境经常自动替换邮件后端因此只跑单元测试可能看不到生产配置触发的弃用警告。第二步先增加 MAILERS暂时保留旧配置迁移期先定义MAILERS让新代码使用别名旧代码暂时保留便于逐个模块切换。不要在同一个提交里同时更换服务商、域名、账号和 Django 版本否则失败后很难判断是哪一层出了问题。第三步把连接对象改成 using过去常见的写法是先调用get_connection()再把连接传给send_mail()或EmailMessage。Django 6.1 推荐使用mail.mailers[别名]或者在发送函数中传入using别名。这一步需要重点检查自定义封装。如果某个工具函数把connection、auth_user或auth_password暴露成参数应将它们收回配置层避免调用方掌握连接细节。第四步把失败策略写清楚fail_silently也进入弃用路径。过去写成fail_silentlyTrue很容易把发送失败吞掉。更可靠的做法是让后端抛出异常在业务层决定重试、记录失败任务还是降级通知。try:send_order_email(order,usingtransactional)exceptException:logger.exception(订单邮件发送失败,extra{order_id:order.id})enqueue_email_retry(order.id)日志只记录业务标识和脱敏地址不要输出 SMTP 密码、完整凭据或邮件正文。第五步在接近生产的环境打开弃用警告先运行完整测试再在预发布环境检查第三方包是否仍读取旧设置。确认所有通道都能连接、超时、重试和报警后再删除旧配置。三个容易踩的坑1. 把配置改名当成迁移完成真正的迁移还包括get_connection()、连接参数、自定义后端和第三方包。只修改settings.py并不能证明运行路径已经切换。2. 在代码里直接写 SMTP 密码新结构把所有参数集中到了OPTIONS但这不代表可以提交凭据。用户名、密码、接口密钥仍应来自环境变量或密钥服务。3. 测试通过就认为生产邮件一定正常内存后端只能证明调用、路由和内容组装正确不能证明 DNS、TLS、端口、服务商限流、发件域名验证和退信处理正确。上线前仍要做受控的真实投递测试。结论与最后的迁移清单所有旧邮件设置和连接调用已经盘点MAILERS至少包含default不同业务使用明确别名SMTP 凭据没有进入代码和日志自定义后端兼容新的OPTIONS失败策略不再依赖静默吞错单元测试、预发布投递和监控都已验证第三方包不再依赖即将移除的接口。Django 6.1 的邮件改造真正的价值不是配置变得更“新”而是让事务邮件、营销邮件和系统告警拥有清晰的路由边界。老项目最稳妥的策略也不是一次性删除旧代码而是先增加新通道、逐条切换调用、扩大验证范围最后再清理兼容层。参考资料Django 6.1 发布说明Django 邮件配置迁移指南Django 发送邮件文档