Svelte中KaTeX的mhchem扩展失效：无法渲染\ce{}命令

问题描述 #

在Svelte + Vite项目中使用KaTeX 0.16.11时，\ce{}化学方程式命令无法正常渲染，出现无内容输出或抛出**"Undefined control sequence"**错误，但copytex等其他扩展可正常工作。

现有代码：

<script lang="ts">
    import katex from 'katex';

    export function renderMath(math: string, displayMode = false) {
        return katex.renderToString(math, {
            displayMode,
            throwOnError: false
        });
    }
</script>

<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css"
        integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X"
        crossorigin="anonymous"
    />
    <script
        defer
        src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/mhchem.min.js"
        integrity="sha384-ifpG+NlgMq0kvOSGqGQxW1mJKpjjMDmZdpKGq3tbvD3WPhyshCEEYClriK/wRVU0"
        crossorigin="anonymous"
    ></script>
</svelte:head>

{@html renderMath('\\ce{H2O}')}

已尝试操作：

• 引入mhchem.min.js脚本
• 调整多种KaTeX配置选项
• 更换不同KaTeX渲染方式
• 验证copytex等其他扩展正常工作

解决方案 #

1. 正确加载mhchem扩展的两种方法 #

问题根源：CDN引入的mhchem扩展挂载在全局katex对象上，而代码中导入的是本地npm包的katex实例，两者不共享，导致扩展无法生效。

方法一：npm安装并导入扩展

1. 安装依赖：

npm install katex @katex/mhchem

2. 修改代码注册扩展：

<script lang="ts">
    import katex from 'katex';
    import mhchem from '@katex/mhchem';

    // 将mhchem注册到当前katex实例
    katex.use(mhchem);

    export function renderMath(math: string, displayMode = false) {
        return katex.renderToString(math, {
            displayMode,
            throwOnError: false
        });
    }
</script>

<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css"
        integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X"
        crossorigin="anonymous"
    />
</svelte:head>

{@html renderMath('\\ce{H2O}')}

方法二：统一使用全局CDN实例

若坚持用CDN加载，需确保渲染时使用全局window.katex，并保证加载顺序：

<script lang="ts">
    let katexReady = false;

    function onKatexLoaded() {
        katexReady = true;
    }

    export function renderMath(math: string, displayMode = false) {
        if (!katexReady || !window.katex) return '';
        return window.katex.renderToString(math, {
            displayMode,
            throwOnError: false
        });
    }
</script>

<svelte:head>
    <link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css"
        integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X"
        crossorigin="anonymous"
    />
    <!-- 先加载主KaTeX脚本 -->
    <script
        src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"
        integrity="sha384-mXg5+81gB6OHTLlC36bTl7c5+G7E59QZQiu1d55gR3YVxnlK44wQ2Wd963K06l4"
        crossorigin="anonymous"
        on:load={onKatexLoaded}
    ></script>
    <!-- 再加载mhchem扩展 -->
    <script
        defer
        src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/mhchem.min.js"
        integrity="sha384-ifpG+NlgMq0kvOSGqGQxW1mJKpjjMDmZdpKGq3tbvD3WPhyshCEEYClriK/wRVU0"
        crossorigin="anonymous"
    ></script>
</svelte:head>

{#if katexReady}
    {@html renderMath('\\ce{H2O}')}
{/if}

2. Svelte的特定注意事项 #

Svelte本身无需额外配置，但需注意：

• 使用npm导入方式时，Vite会自动处理模块依赖，直接使用即可；
• 使用CDN方式时，必须确保KaTeX主脚本先加载完成，再加载mhchem，且渲染前需验证全局实例已就绪，避免因脚本未加载完成导致的错误。

内容的提问来源于stack exchange，提问作者Bram