CDN MathJax + Astro with typesetting in the browser: how can I make the code more concise?

在静态网站生成器领域，Astro 凭借零 JavaScript 运行时、岛屿架构等特性，正在成为开发者的新宠。但对于需要展示数学公式的技术博客、学术文档站点来说，如何在 Astro 中优雅地集成 MathJax 并实现浏览器端排版，一直是个令人纠结的痛点。许多开发者发现，按照官方文档配置后，代码往往显得冗长、重复，甚至因为 CDN 加载时机不当导致渲染延迟。“如何让代码更简洁？” 这个问题，在 Stack Overflow 和 GitHub 讨论区被反复提及。本文将从实战角度，梳理一套精简方案。

为什么要用 CDN + 浏览器端排版？

Astro 默认生成纯静态 HTML，数学公式如果要在服务端预处理，需要安装配套的 Node 包（如 katex），并配置构建插件。这种方式虽然“干净”，但增加了项目依赖和构建复杂度，且公式风格固定，难以动态切换主题。而采用 CDN 加载 MathJax + 浏览器端排版，只需在页面中引入一个脚本标签，MathJax 会在客户端识别 $$...$$ 或 $...$ 等标记，自动渲染为可缩放、可右键复制的标准公式。这种方式代码量最小，且与 Astro 的“零 JS”理念并不冲突——因为 MathJax 只在包含公式的页面才下载，其余页面保持轻量。

传统写法的痛点

许多开发者的初始配置是这样的：在 src/layouts/BaseLayout.astro 中，用 <script> 标签引入 MathJax CDN，同时配置 tex2jax 和 MathML 预处理器。比如：

<script is:inline>
  window.MathJax = {
    tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] },
    options: { ignoreHtmlClass: 'no-math' }
  };
</script>
<script is:inline src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

这段代码本身没问题，但在大型项目中，你可能会遇到以下冗余： - 每个布局文件都重复写相同的 window.MathJax 配置。 - 如果某个页面不需要公式，脚本依然被加载，浪费带宽。 - 为了控制加载时机，不得不用 is:inline 或 defer 属性，代码可读性下降。

简洁方案：按需加载 + 组件化封装

要让代码更简洁，核心思路是将 MathJax 的初始化和加载封装成一个独立的 Astro 组件，只在需要展示公式的页面引入。

第一步：创建 MathJax.astro 组件

---
// src/components/MathJax.astro
// 仅需一行配置，其余由 MathJax 自动处理
---
<script is:inline>
  (function() {
    if (window.MathJax) return; // 避免重复加载
    window.MathJax = {
      tex: { inlineMath: [['$', '$'], ['\\(', '\\)']], displayMath: [['$$', '$$'], ['\\[', '\\]']] },
      options: { ignoreHtmlClass: 'no-math', processHtmlClass: 'math' },
      startup: { pageReady: () => { console.log('MathJax ready'); } }
    };
    const script = document.createElement('script');
    script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js';
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

这个组件做了三件事：配置 MathJax 选项；动态创建 <script> 标签加载 CDN 脚本；利用闭包防止重复加载。配置中的 processHtmlClass: 'math' 允许你只在特定 HTML 元素上启用公式解析，避免污染整页文本。

第二步：在需要使用公式的页面引入

在 src/pages/blog/some-post.astro 中：

---
import MathJax from '../components/MathJax.astro';
---
<article class="math">
  <p>爱因斯坦的质能方程：$$E=mc^2$$</p>
  <p>还有勾股定理：$a^2 + b^2 = c^2$</p>
</article>
<MathJax />

你只需要在文章的根元素上加 class="math"，MathJax 就会自动解析其内部的所有公式。如果文章中没有数学公式，直接不引入 <MathJax />，CDN 脚本根本不会下载——按需加载让代码和资源都变得简洁。

进一步优化：全局配置与自定义延迟

如果你大部分页面都有公式，可以考虑在布局文件中全局引入组件，但利用 transform 属性在构建阶段过滤掉无公式页面。不过 Astro 目前没有原生钩子，更简洁的做法是：在 src/layouts/BaseLayout.astro 中仅保留 <slot />，然后让每个页面自行决定是否引入 MathJax 组件。这比全局重复配置要干净得多。

另外，如果你想延迟渲染以提升首屏速度，可以在 MathJax.astro 中配合 IntersectionObserver：当用户滚动到文章区域时才加载 MathJax。但考虑到数学博客大多为长内容，用户通常不会立即滚动，这个优化因人而异。简洁代码有时意味着放弃过度优化，保持默认的 async 加载已经足够。

效果对比：从20行到3行

优化前（传统全局写法，每页必加载）：每个布局文件至少10行配置 + 1行 CDN 引入，重复于多个布局，共约20行重复代码。

优化后（组件化按需加载）： - 组件内 3 行核心配置 + 1 行动态脚本，共约8行。 - 具体页面仅需 2 行（import + 组件调用）。 - 无公式页面零开销。

总结

在 Astro 中使用 CDN MathJax 实现浏览器排版，简洁的关键在于组件化封装 + 按需加载。不要把配置散落在各个布局里，也不要一味追求全量全局加载。一个精心设计的 <MathJax /> 组件，能让代码量减少 60% 以上，同时保持可读性和可维护性。当你下次需要在 Astro 站点中渲染 ( \LaTeX ) 公式时，不妨试试这个方案，你会发现——简洁不仅是代码的美学，更是效率的提升。

为什么要用 CDN + 浏览器端排版？

传统写法的痛点

简洁方案：按需加载 + 组件化封装

进一步优化：全局配置与自定义延迟

效果对比：从20行到3行

总结

相关阅读