KaTeX 配置

一、渲染选项

核心参数

{
  displayMode: false,    // 渲染模式：true=块公式(displaystyle)，false=行内公式(textstyle)
  leqno: false,          // true时公式标签居左（默认居右）
  fleqn: false,          // true时公式左对齐（默认居中）
  throwOnError: true,    // true时解析错误抛出异常，false时显示错误源码
  errorColor: "#cc0000", // 非抛错模式下的错误显示颜色
  maxExpand: 1000,       // 宏扩展最大次数（防无限循环攻击）
}

高级控制

{
  macros: { 
    "\\R": "\\mathbb{R}",  // 自定义宏：简单字符串替换
    "\\foo": (expander) => expander.expand("#1")  // 函数型宏定义
  },
  minRuleThickness: 0.04,   // 最小线宽（分数线/根号等）
  trust: (context) => {      // 安全信任策略
    return context.protocol === 'https' // 仅允许HTTPS资源
  },
  globalGroup: false        // true时宏定义全局共享
}

二、安全策略 ⚠️

防护机制

关键措施

  1. 命令过滤
    • 禁用危险命令如\includegraphics
    • 使用trust函数限制协议：['http','https','_relative']
  2. 漏洞报告流程
    1. 私密提交至 GitHub Security Advisory
2. 或邮件发送至 katex-security@mit.edu
3. 待修复后公开披露

三、错误处理

安全渲染示例

try {
  katex.render("E=mc^2", element)
} catch (e) {
  if (e instanceof katex.ParseError) {
    // 转义错误信息防XSS攻击
    const safeMsg = e.message
      .replace(/&/g, "&")
      .replace(/</g, "&lt;")
      .replace(/>/g, "&gt;");
    element.innerHTML = `错误: ${safeMsg}`;
  }
}

替代方案

katex.render("x^", element, {
  throwOnError: false, // 直接显示错误源码
  errorColor: "#ff5500" // 自定义高亮颜色
});

四、字体配置

字体加载策略

// SCSS变量覆盖示例
@use 'katex/src/styles/katex' with (
  $use-ttf: false,     // 禁用TTF
  $use-woff: true,      // 启用WOFF
  $font-folder: "../katex-fonts" // 自定义字体路径
);

特性调整

参数默认值作用
$font-size1.21em基础字号缩放比
$use-woff2true优先加载WOFF2(体积最小)
$use-wofftrue兼容旧浏览器

总结

核心要点

  1. 渲染控制：通过displayMode/macros实现公式样式定制
  2. 安全防护：结合trust函数和maxExpand抵御代码注入攻击
  3. 错误隔离：严格转义错误信息或启用内置安全渲染
  4. 字体优化：通过SCSS变量控制字体加载策略与路径

完整配置参考https://katex.org/docs/options.html

最后更新: