Django PasswordResetView 无法渲染自定义邮件模板，始终发送原始HTML

问题现象 #

在Django项目中配置自定义密码重置邮件逻辑时，发送的邮件始终包含未被渲染解析的原始HTML内容。此前完全相同的实现逻辑在其他Django、Django REST Framework项目中可正常运行，调整各类配置后异常仍无法解决。
已完成的复现验证：删除自定义的registration/password_reset_email.html模板文件后，系统可以正常调用Django内置默认密码重置模板发送邮件，HTML内容渲染正常。

现有项目配置 #

根路由配置 #

项目根目录下urls.py的配置内容：

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('store.urls')),
    path('', include('django.contrib.auth.urls')),
]
urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

密码重置视图配置 #

store/urls.py中自定义的密码重置路由配置：

path('password_reset',
      auth_views.PasswordResetView.as_view(
            template_name='registration/password_reset_form.html',
            html_email_template_name='registration/html_password_reset_email.html',
            email_template_name = 'registration/password_reset_email.html',  
            ),
     name='password_reset'
    ),

模板目录结构 #

当前项目的模板文件目录结构：

templates
└── registration
    ├── html_password_reset_email.html 
    ├── password_reset_email.html
    └── ...

异常原因与解决方法 #

首先明确Django密码重置视图的两个邮件模板的定位差异，这是该类问题的核心诱因：

• email_template_name 指定的是纯文本格式的邮件正文模板，虽然文件后缀为.html，但Django会将其渲染结果作为text/plain类型的邮件内容发送，不会自动解析其中的HTML标签。
• html_email_template_name 指定的是HTML格式的邮件正文模板，Django会将其渲染结果作为text/html类型的MIME内容，和纯文本部分组成多段格式邮件发送。
  对应不同的异常诱因，按优先级排查即可：
• 模板内容配置错误
  自定义的password_reset_email.html中如果写入了完整的HTML结构内容（而非纯文本格式的邮件文案），Django会直接将带HTML标签的字符串作为纯文本邮件部分发送。大部分邮件客户端会优先展示纯文本部分，最终用户收到的邮件就会呈现为未解析的原始HTML标签。
  解决方法：将password_reset_email.html的内容替换为纯文本格式的邮件文案，参考Django默认模板的纯文本内容结构，示例：

  你正在申请重置站点 {{ site_name }} 的账号密码，请访问以下链接完成重置：
  {{ protocol }}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}
  所有带样式的HTML邮件内容统一放在html_password_reset_email.html中，保证HTML结构符合邮件客户端的解析标准。

• 路由匹配冲突
  配置中自定义的password_reset路径没有加结尾斜杠，且根路由中同时引入了Django内置的认证路由。如果实际请求触发的是Django内置默认参数的PasswordResetView，而非自定义配置了模板参数的视图，就会出现模板加载异常的问题。
  解决方法：将自定义的密码重置路由路径补上结尾斜杠，即修改为path('password_reset/', ...)，和Django内置路由的路径规则保持一致，避免匹配歧义。
• 模板文件格式异常
  HTML邮件模板文件如果开头包含多余空行、UTF-8 BOM不可见字符，会导致MIME邮件头解析错误，让邮件客户端将HTML内容识别为纯文本展示。
  解决方法：检查两个自定义邮件模板的文件开头，删除多余的空行和不可见字符，保证文件内容从有效HTML标签开始。

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