Astro 官方模版集成 KaTeX 实现 LaTeX 公式渲染

1. 安装必要依赖

首先安装支持 Markdown 数学公式的 remark 和 rehype 插件及 KaTeX 本身。remark-math 负责解析 Markdown 中的数学公式语法，rehype-katex 在构建时将公式节点渲染为 KaTeX 输出。在项目根目录运行：

# 使用 npm 或 pnpm 安装所需的插件和 KaTeX 库
pnpm add remark-math rehype-katex katex
# 如果使用 npm:
# npm install remark-math rehype-katex katex

安装完成后，项目中将多出 remark-math、rehype-katex 和 katex 三个依赖包。

2. 修改 Astro 配置

将两个插件接入 Astro 的 Markdown 渲染管道。打开配置文件（通常是 astro.config.mjs 或 astro.config.ts）并进行如下修改：

import { defineConfig } from 'astro/config';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  // ... 其他 Astro 配置 ...
  markdown: {
    // 添加 remark 和 rehype 插件以支持数学公式
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
  // ... 其他 Astro 配置 ...
});

这段配置让 Astro 在处理 Markdown 时，先通过 remark-math 将 $...$ 和 $$...$$ 内容解析为数学公式节点，再通过 rehype-katex 渲染为对应的 HTML 和 MathML。如果项目中已有其他 remarkPlugins 或 rehypePlugins，将新插件追加进去即可。

3. 引入 KaTeX 样式

仅配置插件还不够——没有 KaTeX 的 CSS，公式排版和字体将缺失。在主布局文件（例如 src/layouts/Layout.astro）的 <head> 中加入：

---
import { Astro } from 'astro';
---
<html>
  <head>
    <!-- 其他元数据和样式 -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" />
  </head>
  <body>
    <slot />  <!-- 页面主要内容 -->
  </body>
</html>

如果不便使用 CDN，也可以在布局组件的 frontmatter 中直接 import 'katex/dist/katex.min.css' 加载本地 KaTeX CSS。无论哪种方式，构建后请确认页面 <head> 中确实加载了 katex.min.css。

4.（可选）调整暗色模式样式

如果博客支持深色模式或使用了 Tailwind CSS 的排版插件，KaTeX 默认输出可能与深色背景冲突。块级公式元素带有 .katex-display 类，其文字颜色默认为黑色，在深色背景下会不可见。在全局样式文件中添加：

.prose .katex-display {
  color: inherit;  /* 继承父元素的文本颜色 */
}

这条规则让公式文字颜色跟随页面文本颜色，在深色背景下保持可见。请根据站点的 CSS 架构调整选择器和属性。未使用暗色模式或 Tailwind 排版插件的项目可跳过此步骤。

完成以上步骤后，插件和样式已集成进 Astro 项目，可以开始编写含有 LaTeX 公式的 Markdown 内容。

在 Markdown 中书写 LaTeX 公式

行内公式使用单个美元符号 $...$ 包裹，例如 $E = mc^2$ 将渲染为 $E = mc^2$。块级公式使用 $$...$$，起止符各自独占一行：

在质能方程中，质量和能量的关系可以表示为：
$$
E = mc^2
$$

另一个示例是二次方程的求根公式：
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

\sum、\int 等命令可插入求和、积分符号，KaTeX 支持几乎所有常见的 LaTeX 数学符号和环境。

踩坑记录

公式不渲染或原样显示：页面中 $E = mc^2$ 仍以文本形式显示，通常是 remark-math 未生效或语法有误。确认 astro.config.mjs 中已正确添加 remarkPlugins: [remarkMath]，并检查公式语法——行内公式不要有换行，块级公式的起止 $$ 各自独占一行。
样式异常：公式渲染出来但字体、对齐或颜色不对，大概率是 katex.min.css 未加载。可打开浏览器开发者工具，在网络面板或元素面板中确认样式文件已成功加载并生效。
暗色模式下公式不可见：公式在暗色模式下"消失"，实际是文字颜色与背景融为一体。在 CSS 中设置 .katex-display { color: inherit; } 可解决此问题。
构建时报错：复杂公式若有语法错误（括号未闭合、命令拼写有误），Astro 构建阶段可能报错，因为 remark-math 在解析无效 LaTeX 时会出错。检查并修正 Markdown 文件中的公式语法即可。

Astro 本身不支持 LaTeX 渲染，但通过 remark/rehype 插件与 KaTeX，可以较为轻松地扩展其 Markdown 功能。