Next.js生产环境Google字体初始渲染不加载问题求助

问题详情 #

在自定义_document.tsx的Head组件中引入Google字体后，生产环境（next build > next start）下初始页面渲染时字体不加载，只有切换到其他页面后才会加载；但开发环境（next dev）完全正常。

已尝试的无效方案：

• 在link标签中设置display=optional
• 直接使用字体名称而非SCSS变量

当前代码实现：

_document.tsx中的字体引入 #

<Head>
    <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;700&display=swap" rel="stylesheet" />
    <link href="https://fonts.googleapis.com/css2?family=Berkshire+Swash&display=swap" rel="stylesheet" />
</Head>

SCSS变量定义（styles/variables.scss） #

$font: 'Poppins', sans-serif;
$font-hand: 'Berkshire Swash', cursive;

全局样式使用（styles/global.scss） #

@import './variables.scss';

body {
  font-family: $font;
}

组件样式使用（components/UI/header/header.module.scss） #

@import '../../../styles/variables.scss';

.logo {
  font-family: $font-hand;
}

可行解决方案 #

1. 迁移字体引入到_app.tsx的next/head中 #

Next.js的_document.tsx是根文档模板，部分资源在生产构建时可能不会被优先加载。改用_app.tsx中的next/head组件引入字体，确保每个页面渲染时都会加载字体资源：

// pages/_app.tsx
import Head from 'next/head';
import '../styles/global.scss';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Head>
        <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;700&display=swap" rel="stylesheet" />
        <link href="https://fonts.googleapis.com/css2?family=Berkshire+Swash&display=swap" rel="stylesheet" />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

2. 添加字体预加载（Preload） #

在_document.tsx中添加预加载指令，强制浏览器优先加载字体文件：

// pages/_document.tsx
import Document, { Html, Head, Main, NextScript } from 'next/document';

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          {/* 预加载字体文件（需替换为实际字体文件URL，可从Google Fonts的CSS中提取） */}
          <link rel="preload" href="https://fonts.gstatic.com/s/poppins/v20/pxiEyp8kv8JHgFVrJJfedw.woff2" as="font" type="font/woff2" crossOrigin="anonymous" />
          <link rel="preload" href="https://fonts.gstatic.com/s/berkshireswash/v17/ptRRTi-cavZOGqCvnNJDlM4KaU4.woff2" as="font" type="font/woff2" crossOrigin="anonymous" />
          {/* 原有的字体样式表引入 */}
          <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;700&display=swap" rel="stylesheet" />
          <link href="https://fonts.googleapis.com/css2?family=Berkshire+Swash&display=swap" rel="stylesheet" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

注：字体文件URL可通过打开Google Fonts的CSS链接（如https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;700&display=swap），提取其中的@font-face里的src地址。

3. 内联字体样式到_document.tsx #

将Google Fonts的CSS内容直接内联到_document.tsx的style标签中，避免外部样式表加载延迟：

// pages/_document.tsx
import Document, { Html, Head, Main, NextScript } from 'next/document';

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <style dangerouslySetInnerHTML={{ __html: `
            @font-face {
              font-family: 'Poppins';
              font-style: normal;
              font-weight: 300;
              font-display: swap;
              src: url(https://fonts.gstatic.com/s/poppins/v20/pxiByp8kv8JHgFVrLDz8Z1xlEA.woff2) format('woff2');
              unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
            }
            @font-face {
              font-family: 'Poppins';
              font-style: normal;
              font-weight: 400;
              font-display: swap;
              src: url(https://fonts.gstatic.com/s/poppins/v20/pxiEyp8kv8JHgFVrJJfedw.woff2) format('woff2');
              unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
            }
            @font-face {
              font-family: 'Poppins';
              font-style: normal;
              font-weight: 700;
              font-display: swap;
              src: url(https://fonts.gstatic.com/s/poppins/v20/pxiByp8kv8JHgFVrLCz7Z1xlEA.woff2) format('woff2');
              unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
            }
            @font-face {
              font-family: 'Berkshire Swash';
              font-style: normal;
              font-weight: 400;
              font-display: swap;
              src: url(https://fonts.gstatic.com/s/berkshireswash/v17/ptRRTi-cavZOGqCvnNJDlM4KaU4.woff2) format('woff2');
              unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
            }
          ` }} />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

4. 禁用Next.js的CSS优化（临时方案） #

如果以上方法都无效，可尝试在next.config.js中禁用CSS优化，排查是否是构建时的CSS处理导致字体加载异常：

// next.config.js
module.exports = {
  optimizeCSS: false,
};

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