企业官网建设流程全解析

• AI 应用
• 前端

适用版本：Voyager 1.3.7 及以上版本。

导读：本文围绕 Voyager 扩展的"用户消息 LaTeX 渲染"功能展开，讲解如何在 Gemini 聊天输入框中直接书写$...$与$$...$$语法，让发送出去的公式被自动排版为美观的数学符号，并深入源码分析其基于 KaTeX 的渲染管线、分段解析算法、异常降级策略，以及与导出/时间线等下游功能的协同机制。读完本文，你将掌握该功能的全部用法、语法边界与底层原理，能够在日常对话中熟练写出可渲染的数学公式。

功能概述

Voyager 作为 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件（项目定位见 README.md），在 1.3.7 版本起引入了一项轻量但实用度极高的能力：自动渲染用户自己发送消息中的 LaTeX 数学公式。

在 Gemini 聊天中输入诸如$E=mc^2$或$$\int_0^1 x^2 dx$$这样的语法后，Voyager 会自动检测并渲染成规范的数学排版，而不是把$...$原样当成普通文本。该功能仅作用于用户自己发送的消息，Gemini 的回复本身带有官方公式渲染能力，不在本功能处理范围内。

核心特性

使用方法

该功能开箱即用，无需任何设置项：

1. 在 Gemini 聊天输入框中输入包含 LaTeX 语法的消息；
2. 发送后，公式会被自动渲染为数学符号；
3. 行内公式$...$嵌入在文本行中随文显示；
4. 块级公式$$...$$独立成行并居中显示。

底层实现上，该功能由内容脚本在页面初始化时启动。在 src/pages/content/index.tsx 中，startUserLatex()与initKaTeXConfig()均在站点识别成功后随内容脚本挂载执行，分别负责公式渲染与 KaTeX 严格模式告警抑制。

语法示例

KaTeX 支持完整的 LaTeX 数学模式语法，包括分数、求和、积分、根式、希腊字母、矩阵、对齐环境等，$$...$$形式还可以搭配\begin{aligned}等环境书写多行推导。

工作流程

用户发送消息（含 $...$ / $$...$$） │ ▼ MutationObserver 监听 DOM（300ms 防抖） │ ▼ processAll() 扫描 p.query-text-line 段落 │ ▼ processElement() 快速退出检查（无 $ 则跳过） │ ▼ parseSegments() 分割纯文本与数学片段 │ ▼ 动态加载 KaTeX（懒加载，仅当存在数学片段） │ ▼ katex.renderToString() 渲染（throwOnError: false） │ ▼ 生成 span.gv-user-latex-inline / .gv-user-latex-display，替换段落内容 │ ▼ 记录>katex.renderToString(seg.value, { displayMode: seg.display, // 块级公式为 true throwOnError: false, // 语法错误时降级输出，不抛异常 output: 'html', // 输出 HTML 而非 MathML });

渲染结果被放入带gv-user-latex-inline（行内）或gv-user-latex-display（块级）类名的<span>中，块级类名对应居中显示样式。若 KaTeX 加载失败或语法无效，则保留原始$...$/$$...$$文本作为回退，这正是文档中"LaTeX 语法无效时显示原文"承诺的实现方式。

4. KaTeX 告警抑制与页面上下文注入

Gemini 页面自身的 CSP 策略禁止内联脚本，为了在不触发告警的前提下优雅运行，Voyager 在 src/pages/content/katexConfig/index.ts 中通过browser.runtime.getURL('katex-config.js')以外部脚本方式注入页面上下文（Safari 构建走 manifest 原生注入，跳过 DOM 注入）。注入的脚本 public/katex-config.js 通过 monkey-patchconsole.warn静默抑制 KaTeX 在数学模式下遇到 Unicode/CJK 字符时产生的unicodeTextInMathMode等严格模式告警，让公式中可以包含中文注释而不污染控制台。

与导出、时间线的协同

用户消息 LaTeX 渲染并非孤立的 DOM 美化，它与 Voyager 的导出、时间线等下游功能形成了闭环：

• src/pages/content/export/adapter/platform/gemini.ts 在抽取用户文本时优先读取line.dataset?.userLatexOriginal（即渲染前的 LaTeX 原文），确保导出内容保留可编辑的公式源码，而非渲染后的 HTML；
• src/pages/content/timeline/TimelineTurns.ts 在克隆节点进入时间线时，将带有data-user-latex-original的元素恢复为原始文本，避免公式渲染结构与时间线布局冲突；
• src/pages/content/responseNotification/index.ts 同样在克隆节点时用userLatexOriginal还原原文，保证通知内容中的公式以可读文本呈现。

此外，Voyager 的导出体系（见 src/features/export/services/katexExportStyles.ts）在 PDF/图片导出时也会携带 KaTeX 样式，使导出的文档保持公式排版。

注意事项

• 仅作用于用户消息：Gemini 官方回复自带公式渲染，Voyager 不重复处理；
• 语法无效回退：LaTeX 语法错误时，公式保持原始文本形态，不会破坏消息可读性；
• 货币表达不受影响：$5、$1,000等金额写法不会被误判为公式；
• 支持中文内容：通过 KaTeX 告警抑制，公式内可包含 CJK 字符而控制台无噪音。

该功能的演进记录见 src/pages/content/changelog/notes/1.3.7.md，其中将该特性与 Notion 兼容公式复制等能力并列为该版本的核心新功能。如需了解项目整体能力，可参考 docs/en/index.md 与 docs/en/plugins.md。

• AI 应用
• 前端