如何在Next.js 14中延迟加载外部KaTeX CSS文件

问题描述 #

我需要用KaTeX CSS渲染数学公式，但没法提前确定哪些页面需要它——得看用户帖子里是否包含数学内容，不过我清楚哪些路由大概率会用到。目前我在根布局的<head>中全局引入了该CSS，代码如下：

// src/app/layout.jsx
export default async function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning lang="en">
      <head>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css" />
      </head>
      <body>
        <main>
         { children }
        </main>
      </body>
    </html>
  )
}

这种全局加载方式导致它成为Lighthouse报告中的渲染阻塞资源，拖慢页面加载性能。我希望实现按需加载：仅当页面存在数学内容时，才懒加载该CSS。已查阅Next.js的CSS和懒加载文档，但仍不清楚具体实现方法。

解决方案 #

方法1：基于路由/服务端判断的条件加载 #

既然已知哪些路由可能需要KaTeX，或能在服务端判断帖子是否含数学内容，可以在对应页面组件中按需引入CSS，同时添加非阻塞属性避免渲染阻塞：

// src/app/post/[slug]/page.jsx
import Head from 'next/head';

export default async function PostPage({ params }) {
  // 服务端判断：比如从数据库拉取帖子内容，检测是否有LaTeX标记（$、\(、\[等）
  const post = await fetchPostContent(params.slug);
  const hasMathContent = post.content.includes('$') || post.content.includes('\\(') || post.content.includes('\\[');

  return (
    <>
      {hasMathContent && (
        <Head>
          <link 
            rel="stylesheet" 
            href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css"
            media="print" 
            onLoad="this.media='all'"
          />
        </Head>
      )}
      {/* 页面内容渲染 */}
    </>
  );
}

media="print"会让浏览器将该资源标记为非渲染阻塞，加载完成后通过onLoad切换为正常生效的media="all"。

方法2：客户端动态检测加载 #

如果无法在服务端提前判断，可在客户端检测页面是否存在KaTeX相关元素，再动态加载CSS：

// src/components/LoadKaTeXStyle.jsx
'use client';

import { useEffect } from 'react';

export default function LoadKaTeXStyle() {
  useEffect(() => {
    // 检测页面是否有需要KaTeX样式的元素（比如带katex类的元素）
    const hasMathElements = document.querySelector('.katex, .math-display, .math-inline') !== null;
    
    if (hasMathElements) {
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = 'https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css';
      document.head.appendChild(link);
    }
  }, []);

  return null;
}

然后在根布局中引入这个客户端组件即可：

// src/app/layout.jsx
import LoadKaTeXStyle from '@/components/LoadKaTeXStyle';

export default async function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning lang="en">
      <head>
        {/* 移除全局的KaTeX CSS引入 */}
      </head>
      <body>
        <LoadKaTeXStyle />
        <main>
         { children }
        </main>
      </body>
    </html>
  )
}

方法3：预加载+条件触发 #

如果某些路由大概率需要KaTeX，但不确定具体页面，可在对应路由的布局中添加预加载标记，同时保留动态判断逻辑：

// src/app/post/layout.jsx
import Head from 'next/head';

export default function PostLayout({ children }) {
  return (
    <>
      <Head>
        <link 
          rel="preload" 
          href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css"
          as="style"
          onLoad="this.rel='stylesheet'"
        />
      </Head>
      {children}
    </>
  );
}

rel="preload"会提前加载资源但不立即生效，等到需要时通过onLoad切换为stylesheet，既提升加载速度又不阻塞渲染。

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