mjml-head-font 深入解析:MJML 中通过 mj-font 智能加载邮件外部字体

原创2026-09-20 11:15:161,651 阅读
文章标签:前端CLI

mjml-head-font 深入解析:MJML 中通过 mj-font 智能加载邮件外部字体

导读

mjml-head-font 是 MJML 框架中负责“外部字体导入”的核心 head 组件,其对应的标签为 mj-font。在邮件 HTML 中,外部字体通常需要以 <link> 或 @import 的方式声明,但 MJML 并不简单地把这段声明原样照搬进输出——它只会在模板正文确实使用到该字体时才注入对应的字体加载标签。本文将以 packages/mjml-head-font/README.md 为主线,结合 mj-font 组件源码 与 字体标签构建器 fonts.js,完整讲解 mj-font 的用法、两个核心属性、默认字体注册机制,以及“按需引入”背后的实现原理。读完本文,你将能在自己的 MJML 模板中正确注册并引入任意网络字体,并理解输出 HTML 中字体标签的生成规则。


一、mj-font 是什么:MJML 的外部字体声明组件

mj-font 是一个只允许出现在 <mj-head> 内部的头部组件(Head Component),它的唯一职责是导入外部字体(external fonts)。与 <mj-style> 直接内联 CSS 不同,mj-font 指向的是一个托管了 @font-face 声明的远程 CSS 文件,例如 Google Fonts 的样式表地址:

https://fonts.googleapis.com/css?family=Raleway

这个 URL 返回的 CSS 中包含 @font-face 规则,定义了 Raleway 字体的字形文件来源与字重变体。mj-font 的角色就是告诉 MJML 渲染器:“模板里可能会用到名为 Raleway 的字体,请从该地址加载它。”

从源码结构看,该组件被实现为一个继承自 HeadComponent 的类,包内仅有一个入口文件 packages/mjml-head-font/src/index.js,package.json 声明其唯一核心依赖是 mjml-core(同版本 5.4.0),并在构建时通过 Babel 输出到 lib/ 目录(见 packages/mjml-head-font/package.json)。


二、完整示例:注册 Raleway 并在正文中使用

原 README 给出了一个最小可用示例,这里保持原样并补充行内注释以便逐行理解:

<mjml>
  <mj-head>
    <!-- 声明外部字体:name 是字体名,href 是托管 @font-face 的 CSS 地址 -->
    <mj-font name="Raleway"
      href="https://fonts.googleapis.com/css?family=Raleway" />
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <!-- 正文中通过 font-family 引用该字体 -->
        <mj-text font-family="Raleway, Arial">
          Hello World!
        </mj-text>
      </mj-column>
     </mj-section>
  </mj-body>
</mjml>

要点拆解:

  1. <mj-font> 必须放在 <mj-head> 之内;
  2. name="Raleway" 与正文中 font-family 的第一个字体名保持大小写一致,这是触发字体加载的关键匹配条件;
  3. font-family="Raleway, Arial" 提供了回退方案——当邮件客户端无法加载 Raleway 时,会依次回退到 Arial,最终回退到客户端默认字体。这是邮件中引用网络字体的标准写法,可以避免“字体加载失败导致样式异常”。

三、属性说明:href 与 name

原 README 的属性表如下,两列补充了各自的约束与行为细节:

attribute accepts description default value
href string URL of a hosted CSS file (无默认值)
name string name of the font (无默认值)

结合源码 packages/mjml-head-font/src/index.js 可以看到,组件把 allowedAttributes 精确限制为这两个属性:

static allowedAttributes = {
  name: 'string',
  href: 'string',
}

属性行为细节:

  • name(必填语义上的字体标识):声明的字体名称,同时也是正文 CSS font-family 匹配时的“关键字”。它不必与 @font-face 内部定义的字体族名完全一致,但必须与正文中实际书写的字体名匹配才能触发加载(匹配逻辑见下文“按需注入”一节)。
  • href(必填的样式表地址):指向一个托管 CSS 文件的 URL,该文件内需包含 @font-face 声明。它既可以是 Google Fonts 这类公共字体服务的地址,也可以是自托管字体服务或 CDN 上任意可公开访问的样式表地址。
  • 两者在 README 中均未标注默认值,即未声明时不产生任何字体注册效果;若只写了 name 而没有 href,或反之,该字体同样不会被正确加载。

四、仅注入实际使用的字体:按需加载的核心机制

mj-font 最值得注意的行为是 README 第一句强调的:“only applied if the template uses the font”(仅当模板使用该字体时才生效)。这一点从组件与核心渲染器的配合中可以看得非常清楚。

4.1 组件层:把字体注册进全局 context

组件自身的 handler 并不直接输出任何 HTML,而是把 (name, href) 这对映射写入渲染上下文:

handler() {
  const { add } = this.context
  add('fonts', this.getAttribute('name'), this.getAttribute('href'))
}

(见 packages/mjml-head-font/src/index.js)

也就是说,mj-font 完成的是声明注册,真正的 HTML 输出发生在后续骨架(skeleton)拼装阶段。

4.2 渲染器层:比对正文后决定是否输出

在 packages/mjml-core/src/helpers/skeleton.js 中,buildFontsTags 被嵌入到 <head> 的生成流程里:

${buildFontsTags(content, inlineStyle, fonts)}

而 packages/mjml-core/src/helpers/fonts.js 实现了完整的按需判定逻辑:

export function buildFontsTags(content, inlineStyle, fonts = {}) {
  const toImport = []

  forEach(fonts, (url, name) => {
    const regex = new RegExp(`"[^"]*font-family:[^"]*${name}[^"]*"`, 'gmi')
    const inlineRegex = new RegExp(`font-family:[^;}]*${name}`, 'gmi')

    if (content.match(regex) || inlineStyle.some((s) => s.match(inlineRegex))) {
      toImport.push(url)
    }
  })

  if (toImport.length > 0) {
    return `
      <!--[if !mso]><!-->
        ${map(toImport,
          (url) => `<link href="${url}" rel="stylesheet" type="text/css">`,
        ).join('\n')}
        <style type="text/css">
          ${map(toImport, (url) => `@import url(${url});`).join('\n')}
        </style>
      <!--<![endif]-->\n
    `
  }

  return ''
}

这里的关键判断逻辑可以拆成三步:

  1. 遍历已注册字体:以 fonts 对象({ name: url } 结构)为输入,逐个检查模板正文;
  2. 两类匹配规则:
    • content.match(regex):在正文 HTML 中查找形如 font-family:... 且包含字体名的属性值字符串(用于匹配如 font-family="Raleway, Arial" 这类属性写法);
    • inlineStyle.some(...):在所有内联样式(inlineStyle 数组)中查找 font-family: 声明里出现该字体名的片段(用于匹配组件样式属性中生成的 style 内容);
    • 正则均带 i 标志,即匹配时不区分大小写;
  3. 只对“被用到”的字体生成标签:只有命中匹配的字体 URL 才会被收集进 toImport,进而输出加载代码;若没有任何字体被实际使用,函数直接返回空字符串,<head> 中不会出现多余的 <link> 或 @import。

4.3 输出形态:link + @import 双保险,且绕过 Outlook

命中的字体最终会以如下形式注入输出 HTML 的 <head>:

<!--[if !mso]><!-->
  <link href="https://fonts.googleapis.com/css?family=Raleway" rel="stylesheet" type="text/css">
  <style type="text/css">
    @import url(https://fonts.googleapis.com/css?family=Raleway);
  </style>
<!--<![endif]-->

两个细节值得注意:

  • 双通道加载:同时输出 <link rel="stylesheet"> 与 <style>@import</style> 两种方式,提高不同邮件客户端的兼容概率;
  • 条件注释 <!--[if !mso]><!--> ... <!--<![endif]-->:整段字体加载代码被包裹在“非 Microsoft Office(Outlook)”的条件注释中,即 Outlook 桌面客户端不会加载这些字体(Outlook 对 @font-face 支持有限,通常会回退到系统字体)。这正是正文中 font-family="Raleway, Arial" 需要带回退字体的现实原因。

(输出逻辑详见 packages/mjml-core/src/helpers/fonts.js)


五、默认字体注册与全局 fonts 选项

除了 <mj-font> 显式注册外,MJML 渲染器还内置了一组默认字体映射。在 packages/mjml-core/src/index.js 中可以找到:

fonts = {
  'Open Sans': 'https://fonts.googleapis.com/css?family=Open+Sans:300,400,500,700',
  'Droid Sans': 'https://fonts.googleapis.com/css?family=Droid+Sans:300,400,500,700',
  Lato: 'https://fonts.googleapis.com/css?family=Lato:300,400,500,700',
  Roboto: 'https://fonts.googleapis.com/css?family=Roboto:300,400,500,700',
  Ubuntu: 'https://fonts.googleapis.com/css?family=Ubuntu:300,400,500,700',
},

含义与用法:

  • 这 5 个字体(Open Sans、Droid Sans、Lato、Roboto、Ubuntu)无需 <mj-font> 声明即可在模板正文中直接使用,只要正文出现 font-family 引用,就会走 4.2 节同样的“按需注入”逻辑;
  • 该默认表是 mjml() 渲染函数的选项级默认值,用户可以在调用 mjml(mjmlString, { fonts: {...} }) 时整体覆盖,例如换成自定义字体服务地址或追加新字体;
  • 这个 fonts 对象最终被写入渲染的全局数据(globalData.fonts,见 packages/mjml-core/src/index.js),并在骨架拼装阶段由 skeleton.js 的 buildFontsTags(content, inlineStyle, fonts) 消费——也就是说,<mj-font> 注册的字体与默认字体、选项传入的字体,最终在同一个映射表里统一处理。

所以从使用角度可以这样理解:

字体来源 声明方式 是否需按需匹配
默认内置字体 无需声明,直接使用 是
自定义外部字体 <mj-font name="..." href="..." /> 是
运行时注入 mjml(input, { fonts: {...} }) 选项 是

六、常见问题与使用建议

  • 字体名大小写/拼写不一致导致加载失败:按需匹配依赖字符串比对(正则带 i 标志,大小写不敏感,但拼写必须一致)。请确保 <mj-font name> 与正文 font-family 中的字体名完全相同。
  • 不要忘记回退字体:由于字体加载段被包裹在 [if !mso] 条件注释中,Outlook 桌面端必然回退到第二个字体名。因此 font-family="Raleway, Arial" 这类带兜底的字体系列是邮件内的推荐写法。
  • href 必须是可直接访问的 CSS:href 指向的必须是返回 CSS 文本(含 @font-face)的 URL,而不是字体文件(.woff2/.ttf)本身。
  • 未使用不产生体积成本:如果声明了 <mj-font> 但正文从未引用该字体,输出 HTML 中不会出现任何相关 <link> 或 @import,不会给邮件体积带来负担。
  • 自定义字体服务:如果希望使用自己的字体 CDN,只需把 href 换成自托管样式表地址,或在 mjml() 选项的 fonts 中自行注册。

七、相关源码与测试入口

以下文件是理解 mj-font 完整行为链路的推荐阅读入口:

MJML 官方组件文档(doc/body_components.md、doc/head_components.md 等)与 packages/mjml-head-font/README.md 一并构成了学习头部组件用法的资料体系,可按需查阅。

登录后查看全文
mjml