Authelia 无预览邮件模板No Preview实战指南避开 MUA 渲染陷阱的通知模板定制方案【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读Authelia 的邮件通知系统通过 Go 模板 生成 HTML 与纯文本邮件其官方模板基于 react-email 编写。默认模板在 HTML 头部注入Preview组件用于生成邮件预览文本但在极少数邮件客户端MUA上会引发渲染异常。本指南以仓库内examples/templates/notifications/no-preview/目录中的官方无预览示例为核心系统讲解该示例的目录结构、三个模板Event、IdentityVerificationOTC、IdentityVerificationJWT的完整字段与占位符语义、如何通过template_path配置将其接入 Authelia以及如何基于 react-email 源码定位和裁剪Preview组件。读完本文你将掌握一套可复制、可落地、可验证的自定义通知模板方案。一、背景Authelia 的通知模板体系与预览组件Authelia 使用模板生成经由通知服务发送的 HTML 与纯文本邮件每类通知对应两个扩展名文件.html与.txt。其官方模板源码位于仓库的internal/templates/src/emails/基于 react-email 编写构建产物编译后的 HTML被嵌入二进制并同步存放在internal/templates/embed/notification/。以事件通知为例Event.tsx 的源码中包含如下片段{hidePreview ? null : PreviewAn important event has occurred with your account/Preview}Preview是 react-email 的 Preview 组件用于在邮件客户端中生成收件箱预览文本。虽然绝大多数 MUA 支持良好但在极少数邮件客户端上曾引发渲染问题。为此Authelia 官方在examples/templates/notifications/no-preview/目录中提供了不包含该组件的模板示例供受影响的用户直接参考和复用。这一设计在 README.md 中有明确说明该目录专门收录不含 Preview 组件的模板规避其在部分 MUA 上的渲染异常。二、目录结构与三个模板的分工examples/templates/notifications/目录下包含no-preview/本指南核心不含Preview组件的官方示例Event.htmlIdentityVerificationOTC.htmlIdentityVerificationJWT.htmlREADME.mdhtml_email_with_button_and_link.html另一个独立示例含按钮与链接no-preview目录中的三个模板与 Authelia 官方内置模板一一对应覆盖全部三类通知模板名称渲染场景对应官方源码Event账户事件通知如二因素方法新增、凭据变更等Event.tsxIdentityVerificationOTC有状态校验如管理凭据时的一次性代码IdentityVerificationOTC.tsxIdentityVerificationJWT无状态校验如重置密码的一次性链接IdentityVerificationJWT.tsx从 notification-templates.md 参考文档 可知这三类模板正是 Authelia 通知模板的全部范围。因此no-preview目录提供的是一套完整覆盖所有通知类型的降级方案而非仅针对某一类邮件。三、模板文件逐层拆解结构、字段与占位符3.1 通用 HTML 骨架三个模板的 HTML 骨架完全一致均以 XHTML 1.0 Transitional 声明开头外层结构为!DOCTYPE html PUBLIC -//W3C//DTD XHTML 1.0 Transitional//EN http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd html dirltr langen head meta contenttext/html; charsetUTF-8 http-equivContent-Type/ meta namex-apple-disable-message-reformatting/ /head body stylebackground-color:rgb(255,255,255);...其中x-apple-disable-message-reformatting用于禁止 Apple Mail 自动重排版是邮件模板的常见兼容性处理。正文统一采用max-width:465px的居中卡片式容器border-style:solid;border-width:1px;border-color:rgb(234,234,234);border-radius:0.25rem字体栈为ui-sans-serif,system-ui,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji。与 react-email 官方示例 对比可知这些样式正是Body、Container、Tailwind组件编译后的产物。注意无预览模板中head内已不再包含Preview组件的输出这正是本示例的核心差异。3.2 Event.html事件通知模板Event.html 的核心占位符占位符说明{{ .Title }}邮件标题与主题行一致{{ .DisplayName }}收件人显示名称如John Doe{{ .BodyPrefix }}事件正文前缀{{ .BodyEvent }}事件描述加粗斜体显示{{ .BodySuffix }}事件正文后缀{{ .Details }}事件附加详情映射按键排序渲染{{ .RemoteIP }}触发事件的客户端 IP模板中Details的渲染方式值得关注它使用了 Go 模板内置函数{{- $keys : sortAlpha (keys .Details) }}{{- range $key : $keys }} p style...strong{{ $key }}:/strong {{ index $.Details $key }}/p {{ end }}即先通过keys取出映射键集合再经sortAlpha排序后遍历输出保证详情列表顺序稳定。这一实现与 Event.tsx 中的detailsPrefix/detailsKey/detailsValue/detailsSuffix四字段结构一一对应。3.3 IdentityVerificationOTC.html一次性代码模板IdentityVerificationOTC.html 用于有状态身份校验核心占位符占位符说明{{ .DisplayName }}收件人名称{{ .Domain }}相关 Authelia 域名{{ .OneTimeCode }}一次性代码加粗居中展示{{ .RevocationLinkURL }}撤销链接地址{{ .RevocationLinkText }}撤销按钮文本{{ .RemoteIP }}触发请求的 IP模板特色一次性代码区域使用letter-spacing:0.5rem加大字距、font-weight:700加粗并带有idone-time-code锚点便于自动化测试或脚本定位撤销按钮为品红色background-color:rgb(245,0,87)同时提供纯文本形式的 URL 兜底展示内置未发起该流程时的处置步骤撤销代码、重置凭据、联系管理员。3.4 IdentityVerificationJWT.html一次性链接模板IdentityVerificationJWT.html 用于无状态身份校验如重置密码核心占位符占位符说明{{ .DisplayName }}收件人名称{{ .Domain }}相关 Authelia 域名{{ .LinkURL }}校验链接地址{{ .LinkText }}校验按钮文本{{ .RevocationLinkURL }}撤销链接地址{{ .RevocationLinkText }}撤销按钮文本{{ .RemoteIP }}触发请求的 IP模板特色主校验按钮为蓝色background-color:rgb(25,118,210)带idlink锚点链接文本使用word-break:break-all防止长 JWT URL 撑破布局撤销按钮同样为品红色与 OTC 模板保持视觉一致。三个模板的尾部均包含灰色小字声明收件人、来源 IP、安全建议与 Powered by Authelia 品牌行对应 Brand.tsx 组件。四、如何接入template_path 配置与覆盖规则4.1 配置入口在 configuration.yml 示例 中通知配置结构为notifier: disable_startup_check: false template_path: filesystem: {} smtp: {}其中template_path即自定义模板目录。官方参考文档明确说明该配置允许管理员指定一个目录用于存放通知的自定义模板该目录只需放置需要覆盖的模板文件未提供的模板将自动回退到默认模板。4.2 覆盖规则以修改IdentityVerificationJWT的 HTML 模板为例官方参考文档 原文若template_path配置为/config/email_templates则创建/config/email_templates/IdentityVerificationJWT.html即可覆盖 HTML 版IdentityVerificationJWT模板。同理将no-preview目录中的三个文件复制到template_path指向的目录即可完整替换全部通知模板# 假设 template_path 为 /config/email_templates mkdir -p /config/email_templates cp examples/templates/notifications/no-preview/*.html /config/email_templates/对应配置文件notifier: template_path: /config/email_templates smtp: host: smtp.example.com port: 587 ...4.3 三条重要注意事项按照 notification-templates.md 的说明自定义模板必须注意稳定性边界模板不受 Authelia 版本稳定性策略保护。官方虽尽量避免需要用户手动修改的模板变更但为修复缺陷或改进模板仍可能调整用户有责任保证自己的模板保持最新。支持边界官方只对官方模板提供调试支持与修复不承诺直接支持用户自定义模板的调试。编码硬性要求所有模板必须为 UTF-8 编码且使用 CRLF 行尾不能是单纯的 LF。这直接决定了从仓库复制示例文件后需要先用unix2dos或编辑器转换行尾再部署。此外从 templating.md 可知通知模板默认启用模板渲染若需在配置文件中也启用模板语法需设置环境变量X_AUTHELIA_CONFIG_FILTERStemplate二者互不影响。五、从源码理解如何去掉 Preview并保持其余一致5.1 官方源码中的开关官方模板并未直接删除 Preview而是通过hidePreview属性控制。在 Event.tsx 中{hidePreview ? null : PreviewAn important event has occurred with your account/Preview}IdentityVerificationOTC.tsx 与 IdentityVerificationJWT.tsx 采用同样的条件渲染模式。因此官方源码层面已经预留了无预览能力no-preview示例可视为将hidePreview置为true后的渲染产物。5.2 对比验证将 Event.html 与 Event.tsx 的 PreviewPropstitle: Second Factor Method Added、bodyEvent: Second Factor Method、bodyPrefix: a、bodySuffix: was added to your account.对照可发现模板渲染逻辑、样式类名text-black text-[24px] font-normal text-center→ 内联color:rgb(0,0,0);font-size:24px等完全一致唯一差异就是head中缺失了 Preview 组件的输出。这印证了该示例的定位仅移除 Preview不改动其余渲染结果。5.3 模板函数支持模板引擎provider.go在解析模板时注入了FuncMap()提供的内置函数如模板内使用的keys、sortAlpha自定义模板可以继续使用这些函数。需要深入了解函数清单时可查阅 templating.md 参考文档。六、部署与验证建议行尾转换仓库内文件为 LF 行尾部署前务必转换为 CRLF例如unix2dos /config/email_templates/*.html否则模板可能无法被正确解析。最小覆盖原则只需复制你确实需要覆盖的通知类型。例如仅当重置密码邮件渲染异常时只放置IdentityVerificationJWT.html即可其余模板继续使用内置默认。纯文本配套官方模板同时提供.html与.txt两种形式见 internal/templates/embed/notification/。no-preview目录目前只含 HTML 示例若你的通知服务同时发送纯文本版本建议同时准备同名.txt文件或确认你的使用场景仅依赖 HTML 渲染。验证手段部署后可通过filesystem通知提供者将邮件写入文件目录进行冒烟测试该提供者的启动检查会验证目录可写确认模板渲染无异常后再切换回 SMTP 生产环境。七、总结examples/templates/notifications/no-preview/是 Authelia 官方为规避Preview组件在部分邮件客户端上的渲染问题而提供的完整模板示例集覆盖 Event、IdentityVerificationOTC、IdentityVerificationJWT 三类全部通知。它基于 react-email 官方模板裁剪而来除移除 Preview 外保持样式与占位符语义完全一致。接入方式非常直接将对应.html文件放入template_path目录注意 UTF-8 与 CRLF 要求即可在不动其余模板的前提下完成替换。对于正在排查邮件预览异常、或希望完全掌控通知邮件的开发者而言这是一份开箱即用的参考实现。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考