LaTeX 公式渲染修复指南

LaTeX 公式渲染修复指南

问题描述

尽管服务器端已正确配置 KaTeX，但在浏览器中公式可能仍然显示为纯文本 $$...$$。

这通常是由于以下原因：

  1. KaTeX 资源加载失败
  2. 浏览器缓存了旧版本的 HTML
  3. JavaScript 执行时机问题
  4. 其他 JavaScript 错误

诊断步骤

第一步：访问诊断页面

打开浏览器访问：

http://localhost:8080/LATEX_DIAGNOSTIC.html

这个页面将自动检测并报告渲染状态。

第二步：查看渲染状态

在诊断页面中，你会看到多个公式：

成功状态（✅）:

  • 行内公式：$E = mc^2$ 应该与文字行内对齐，字体精美
  • 显示公式：$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$ 应该居中显示，排版精美

失败状态（❌）:

  • 所有公式显示为纯文本 $$...$$
  • 公式显示为乱码或方块

第三步：检查浏览器控制台

如果渲染失败，按 F12 打开浏览器控制台：

1. Network 标签页

  • 检查 katex.min.js 是否加载成功（状态 200）
  • 检查 auto-render.min.js 是否加载成功
  • 如果有红色错误，说明资源加载失败

2. Console 标签页

  • 查看是否有红色 JavaScript 错误
  • 如果有 renderMathInElement is not defined 错误，说明 KaTeX 未加载

3. Elements 标签页

  • 检查公式元素是否有 .katex 或 .katex-html 包裹
  • 如果没有，说明 KaTeX 未执行渲染

修复方案

方案 1: 强制刷新浏览器缓存

Chrome/Edge:

  • Windows/Linux: Ctrl + Shift + R
  • Mac: Cmd + Shift + R

Firefox:

  • Windows/Linux: Ctrl + F5
  • Mac: Cmd + Shift + R

Safari:

  • Cmd + Option + E (清空缓存) 然后刷新

方案 2: 清除浏览器缓存

Chrome:

  1. 按 F12 打开开发者工具
  2. 右键点击刷新按钮
  3. 选择 "清空缓存并硬性重新加载"

Firefox:

  1. 打开 "选项" > "隐私与安全"
  2. 点击 "清除数据"
  3. 勾选 "缓存的 Web 内容" 并清除

方案 3: 检查 KaTeX 资源加载

在浏览器控制台执行以下代码：

// 检查 KaTeX 是否加载
if (typeof katex !== 'undefined') {
    console.log("✅ KaTeX 已加载");
    console.log("版本:", katex.version);
} else {
    console.log("❌ KaTeX 未加载");
}

// 检查渲染函数
if (typeof renderMathInElement !== 'undefined') {
    console.log("✅ renderMathInElement 可用");
} else {
    console.log("❌ renderMathInElement 不可用");
}

// 手动触发渲染
var content = document.querySelector('.article-content');
if (content && typeof renderMathInElement !== 'undefined') {
    renderMathInElement(content, {
        delimiters: [
            {left: "$$", right: "$$", display: true},
            {left: "$", right: "$", display: false}
        ]
    });
    console.log("🔄 已手动触发渲染");
}

方案 4: 检查是否已使用最新模板

确保 blog/articletemplate_v2.php 存在并已加载：

# 在 PowerShell 中运行
php -r "require_once '_blog/config.php'; echo (file_exists('_blog/article_template_v2.php') ? '✅ 新模板存在' : '❌ 新模板不存在');"

如果新模板不存在，请重新创建：

<?php
// 在 _blog/article_template_v2.php 中
function generateArticleHtml($title, $content, $currentDir) {
    // 使用字符串拼接方式构建 HTML
    $rootPath = getRootPath($currentDir);
    $html = '<!DOCTYPE html>' . "\n";
    // ... 完整模板
    return $html;
}
?>

方案 5: 重新生成 HTML

# 重新生成 mHC 研读文件
php -r "require_once '_blog/config.php'; checkAndUpdateHtml('agi/mHC研读.md', 'agi/mHC研读.html'); echo 'Regenerated';"

# 或者直接访问
http://localhost:8080/LATEX_DIAGNOSTIC.html

快速测试

访问以下 URL 快速测试：

  1. 诊断页面（推荐）:

http://localhost:8080/LATEX_DIAGNOSTIC.html

  1. 简单测试页:

http://localhost:8080/test-latex.html

  1. mHC 论文:

http://localhost:8080/agi/mHC研读.html

预期结果

渲染成功时:

  • 所有公式显示精美
  • 行内公式与文本对齐
  • 显示公式居中
  • 字体清晰，排版正确

渲染失败时:

  • 显示纯文本 $$...$$
  • 或显示乱码/方块

联系支持

如果以上方法都无法解决问题：

  1. 在浏览器控制台执行 console.log(navigator.userAgent); 并提供输出
  2. 截图浏览器控制台的 Network 和 Console 标签页
  3. 提供浏览器类型和版本

最后更新: 2026-01-06 KaTeX 版本: 0.16.9 模板版本: v2 (字符串拼接)

← 返回目录