NextJS+TailwindCSS添加本地字体报错：无法解析字体文件路径

问题根源 #

你遇到的「Module not found」错误，核心是字体文件的引用路径错误——public目录是NextJS的静态资源根目录，引用时需使用根路径（以/开头），而非相对路径（./开头）。

正确配置步骤 #

1. 确认字体文件位置 #

确保字体文件已正确放置在public/fonts/目录下，例如：
public/fonts/Recoleta-Regular.ttf

注意：Linux/macOS系统区分文件名大小写，务必保证代码中的文件名和实际文件完全一致。

2. 方式一：使用NextJS官方next/font/local（推荐，NextJS 13+） #

步骤1：在根布局中导入并配置字体

• 若使用App Router，编辑app/layout.js：

import { localFont } from 'next/font/local'

// 配置本地字体，src使用根路径
const recoleta = localFont({
  src: '/fonts/Recoleta-Regular.ttf',
  weight: '400',
  style: 'normal',
  // 定义CSS变量，方便Tailwind调用
  variable: '--font-recoleta',
})

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN" className={recoleta.variable}>
      <body>{children}</body>
    </html>
  )
}

• 若使用Pages Router，编辑pages/_app.js：

import { localFont } from 'next/font/local'

const recoleta = localFont({
  src: '/fonts/Recoleta-Regular.ttf',
  weight: '400',
  style: 'normal',
  variable: '--font-recoleta',
})

export default function App({ Component, pageProps }) {
  return (
    <div className={recoleta.variable}>
      <Component {...pageProps} />
    </div>
  )
}

步骤2：在Tailwind配置中注册字体族

编辑tailwind.config.js，扩展fontFamily：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      fontFamily: {
        recoleta: ['var(--font-recoleta)'],
      },
    },
  },
  plugins: [],
}

步骤3：在代码中使用

直接通过Tailwind类名调用：

<h1 className="font-recoleta text-3xl">使用Recoleta字体的标题</h1>

3. 方式二：使用全局CSS定义@font-face #

步骤1：在全局CSS中声明字体

编辑app/globals.css（App Router）或styles/globals.css（Pages Router）：

@font-face {
  font-family: 'Recoleta';
  src: url('/fonts/Recoleta-Regular.ttf') format('truetype');
  font-weight: 400;
  font-style: normal;
  font-display: swap; /* 优化字体加载体验 */
}

步骤2：在Tailwind配置中注册字体族

同样编辑tailwind.config.js：

module.exports = {
  // ...其他配置
  theme: {
    extend: {
      fontFamily: {
        recoleta: ['Recoleta', 'sans-serif'],
      },
    },
  },
}

步骤3：在代码中使用

和方式一一样，用font-recoleta类名即可。

额外注意事项 #

• 若有多种字重（如Bold、Italic），只需在配置中新增对应的src路径即可，例如：

  const recoleta = localFont({
    src: [
      { path: '/fonts/Recoleta-Regular.ttf', weight: '400', style: 'normal' },
      { path: '/fonts/Recoleta-Bold.ttf', weight: '700', style: 'normal' },
    ],
    variable: '--font-recoleta',
  })
  

• 确保字体文件格式正确（TTF、OTF、WOFF2等都是NextJS支持的格式）。

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