NNext.js 中文网 GitHub

Font 模块

使用内置的 next/font 加载器优化网页字体的加载。

next/font 会自动优化你的字体(包括自定义字体),并消除外部网络请求,以提升隐私性和性能。

它为任何字体文件提供内置自动自托管。这意味着你可以以最佳方式加载网页字体而不会出现布局偏移。

你还可以方便地使用所有 Google Fonts。CSS 和字体文件在构建时下载,并与其余静态资源一起自托管。浏览器不会向 Google 发送任何请求。

app/layout.tsx
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}

要在所有页面中使用该字体,请按如下所示将其添加到 /pages 下的 _app.js 文件中:

pages/_app.js
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({ subsets: ['latin'] })

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={inter.className}>
      <Component {...pageProps} />
    </main>
  )
}

🎥 观看: 了解有关使用 next/font 的更多信息 → YouTube(6 分钟)。

参考#

键font/googlefont/local类型必填
src✗✓字符串或对象数组是
weight✓✓字符串或数组必填/可选
style✓✓字符串或数组-
subsets✓✗字符串数组-
axes✓✗字符串数组-
display✓✓字符串-
preload✓✓布尔值-
fallback✓✓字符串数组-
adjustFontFallback✓✓布尔值或字符串-
variable✓✓字符串-
declarations✗✓对象数组-

src#

字体文件的路径,为字符串或对象数组(类型为 Array<{path: string, weight?: string, style?: string}>),相对于调用字体加载器函数的目录。

用于 next/font/local

  • 必填

示例:

  • src:'./fonts/my-font.woff2',其中 my-font.woff2 放置在 app 目录内名为 fonts 的目录中
  • src:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]
  • 如果在 app/page.tsx 中使用 src:'../styles/fonts/my-font.ttf' 调用字体加载器函数,则 my-font.ttf 放置在项目根目录的 styles/fonts 中

weight#

字体 weight,可能的值如下:

  • 一个字符串,其可能值为特定字体可用的字重值,如果是可变字体,则为值的范围
  • 如果字体不是可变 Google 字体,则为字重值数组。仅适用于 next/font/google。

用于 next/font/google 和 next/font/local

  • 如果所用字体不是可变字体,则为必填

示例:

  • weight: '400':表示单个字重值的字符串——对于字体 Inter,可能的值为 '100'、'200'、'300'、'400'、'500'、'600'、'700'、'800'、'900' 或 'variable'(其中 'variable' 为默认值)
  • weight: '100 900':表示可变字体 100 到 900 之间范围的字符串
  • weight: ['100','400','900']:非可变字体的 3 个可能值组成的数组

style#

字体 style,可能的值如下:

  • 字符串值,默认值为 'normal'
  • 如果字体不是可变 Google 字体,则为样式值数组。仅适用于 next/font/google。

用于 next/font/google 和 next/font/local

  • 可选

示例:

  • style: 'italic':字符串——对于 next/font/google,可以是 normal 或 italic
  • style: 'oblique':字符串——对于 next/font/local,可以是任意值,但预期来自标准字体样式
  • style: ['italic','normal']:用于 next/font/google 的包含 2 个值的数组——值来自 normal 和 italic

subsets#

字体 subsets 由一个字符串值数组定义,其中包含你希望预加载的每个子集的名称。当 preload 选项为 true(默认值)时,通过 subsets 指定的字体将在 head 中注入一个 link preload 标签。

用于 next/font/google

  • 可选

示例:

  • subsets: ['latin']:包含子集 latin 的数组

你可以在 Google Fonts 页面上找到你的字体的所有子集列表。

axes#

某些可变字体包含额外的 axes(轴)。默认情况下,仅包含字体粗细以保持文件大小较小。axes 的可能值取决于具体字体。

用于 next/font/google

  • 可选

示例:

  • axes: ['slnt']:一个值为 slnt 的数组,适用于 Inter 可变字体,该字体将 slnt 作为额外的 axes,如此处所示。你可以通过使用 Google 可变字体页面上的过滤器并查找 wght 以外的轴,来找到你的字体可能的 axes 值。

display#

字体 display,可能的字符串值为 'auto'、'block'、'swap'、'fallback' 或 'optional',默认值为 'swap'。

用于 next/font/google 和 next/font/local

  • 可选

示例:

  • display: 'optional':赋值为 optional 的字符串

preload#

一个布尔值,指定字体是否应预加载。默认值为 true。

一次调用加载的每个字体文件都共享此设置,因为它们会成为一组具有单个 font-family 的 @font-face 规则。

用于 next/font/google 和 next/font/local

  • 可选

示例:

  • preload: false

fallback#

无法加载字体时使用的回退字体。由回退字体组成的字符串数组,无默认值。

  • 可选

用于 next/font/google 和 next/font/local

示例:

  • fallback: ['system-ui', 'arial']:将回退字体设置为 system-ui 或 arial 的数组

adjustFontFallback#

  • 对于 next/font/google:一个布尔值,设置是否使用自动回退字体以减少累积布局偏移。默认值为 true。
  • 对于 next/font/local:一个字符串或布尔值 false,设置是否使用自动回退字体以减少累积布局偏移。可能的值为 'Arial'、'Times New Roman' 或 false。默认值为 'Arial'。

用于 next/font/google 和 next/font/local

  • 可选

示例:

  • adjustFontFallback: false:用于 next/font/google
  • adjustFontFallback: 'Times New Roman':用于 next/font/local

variable#

一个字符串值,用于定义在使用 CSS 变量方法应用样式时要使用的 CSS 变量名称。

用于 next/font/google 和 next/font/local

  • 可选

示例:

  • variable: '--my-font':声明了 CSS 变量 --my-font

declarations#

由字体描述符键值对组成的数组,用于进一步定义生成的 @font-face。

设置 font-family 会替换 Next.js 生成的名称。请保持该值与导出的常量相同,以便 className 和 CSS 变量引用同一个字体系列。

app/fonts.ts
import localFont from 'next/font/local'

export const myFont = localFont({
  src: './my-font.woff2',
  declarations: [{ prop: 'font-family', value: 'myFont' }],
})

用于 next/font/local

  • 可选

示例:

  • declarations: [{ prop: 'ascent-override', value: '90%' }]

示例#

Google Fonts#

要使用 Google 字体,请将其从 next/font/google 作为函数导入。我们建议使用可变字体以获得最佳性能和灵活性。

app/layout.tsx
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}

如果不能使用可变字体,你将需要指定字重:

app/layout.tsx
import { Roboto } from 'next/font/google'

const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={roboto.className}>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import { Roboto } from 'next/font/google'

const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
  display: 'swap',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={roboto.className}>
      <body>{children}</body>
    </html>
  )
}

要在所有页面中使用该字体,请按如下所示将其添加到 /pages 下的 _app.js 文件中:

pages/_app.js
import { Inter } from 'next/font/google'

// 如果加载的是可变字体,则无需指定字体粗细
const inter = Inter({ subsets: ['latin'] })

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={inter.className}>
      <Component {...pageProps} />
    </main>
  )
}

如果不能使用可变字体,你将需要指定字重:

pages/_app.js
import { Roboto } from 'next/font/google'

const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
})

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={roboto.className}>
      <Component {...pageProps} />
    </main>
  )
}

你可以通过使用数组指定多个字重和/或样式:

app/layout.js
const roboto = Roboto({
  weight: ['400', '700'],
  style: ['normal', 'italic'],
  subsets: ['latin'],
  display: 'swap',
})

小知识:对于包含多个单词的字体名称,请使用下划线 (\_)。例如,Roboto Mono 应导入为 Roboto_Mono。

在 <head> 中应用字体#

你也可以通过如下方式将字体注入 <head> 内,从而在不使用包装器和 className 的情况下使用该字体:

pages/_app.js
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <style jsx global>{`
        html {
          font-family: ${inter.style.fontFamily};
        }
      `}</style>
      <Component {...pageProps} />
    </>
  )
}

单页使用#

要在单个页面上使用该字体,请按如下所示将其添加到特定页面:

pages/index.js
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function Home() {
  return (
    <div className={inter.className}>
      <p>Hello World</p>
    </div>
  )
}

指定子集#

Google 字体会自动进行子集化。这减小了字体文件的大小并提升了性能。你需要定义要预加载哪些子集。当 preload 为 true 时未指定任何子集将导致警告。

这可以通过将其添加到函数调用中来完成:

app/layout.tsx
const inter = Inter({ subsets: ['latin'] })
app/layout.js
const inter = Inter({ subsets: ['latin'] })
pages/_app.js
const inter = Inter({ subsets: ['latin'] })

有关更多信息,请查看 Font API 参考。

使用多个字体#

你可以在应用程序中导入和使用多个字体。可以采用两种方法。

第一种方法是创建一个工具函数来导出字体,在需要的地方导入并应用其 className。这确保字体仅在渲染时才被预加载:

app/fonts.ts
import { Inter, Roboto_Mono } from 'next/font/google'

export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
})
app/fonts.js
import { Inter, Roboto_Mono } from 'next/font/google'

export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})

export const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
})
app/layout.tsx
import { inter } from './fonts'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.className}>
      <body>
        <div>{children}</div>
      </body>
    </html>
  )
}
app/layout.js
import { inter } from './fonts'

export default function Layout({ children }) {
  return (
    <html lang="en" className={inter.className}>
      <body>
        <div>{children}</div>
      </body>
    </html>
  )
}
app/page.tsx
import { roboto_mono } from './fonts'

export default function Page() {
  return (
    <>
      <h1 className={roboto_mono.className}>My page</h1>
    </>
  )
}
app/page.js
import { roboto_mono } from './fonts'

export default function Page() {
  return (
    <>
      <h1 className={roboto_mono.className}>My page</h1>
    </>
  )
}

在上面的示例中,Inter 将全局应用,而 Roboto Mono 可以按需导入和应用。

或者,你可以创建一个 CSS 变量并将其与你偏好的 CSS 解决方案一起使用:

app/layout.tsx
import { Inter, Roboto_Mono } from 'next/font/google'
import styles from './global.css'

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
  display: 'swap',
})

const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  variable: '--font-roboto-mono',
  display: 'swap',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={`${inter.variable} ${roboto_mono.variable}`}>
      <body>
        <h1>My App</h1>
        <div>{children}</div>
      </body>
    </html>
  )
}
app/layout.js
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
  display: 'swap',
})

const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  variable: '--font-roboto-mono',
  display: 'swap',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${roboto_mono.variable}`}>
      <body>
        <h1>My App</h1>
        <div>{children}</div>
      </body>
    </html>
  )
}
app/global.css
html {
  font-family: var(--font-inter);
}

h1 {
  font-family: var(--font-roboto-mono);
}

在上面的示例中,Inter 将全局应用,任何 <h1> 标签都将使用 Roboto Mono 设置样式。

建议:谨慎使用多个字体,因为每增加一种字体都是客户端必须下载的额外资源。

本地字体#

导入 next/font/local 并指定本地字体文件的 src。我们建议使用可变字体以获得最佳性能和灵活性。

app/layout.tsx
import localFont from 'next/font/local'

// 字体文件可以放在 `app` 内
const myFont = localFont({
  src: './my-font.woff2',
  display: 'swap',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={myFont.className}>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import localFont from 'next/font/local'

// 字体文件可以放在 `app` 内
const myFont = localFont({
  src: './my-font.woff2',
  display: 'swap',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={myFont.className}>
      <body>{children}</body>
    </html>
  )
}
pages/_app.js
import localFont from 'next/font/local'

// 字体文件可以放在 `pages` 内
const myFont = localFont({ src: './my-font.woff2' })

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={myFont.className}>
      <Component {...pageProps} />
    </main>
  )
}

如果你想为单个字体系列使用多个文件,src 可以是一个数组:

js
const roboto = localFont({
  src: [
    {
      path: './Roboto-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './Roboto-Italic.woff2',
      weight: '400',
      style: 'italic',
    },
    {
      path: './Roboto-Bold.woff2',
      weight: '700',
      style: 'normal',
    },
    {
      path: './Roboto-BoldItalic.woff2',
      weight: '700',
      style: 'italic',
    },
  ],
})

有关更多信息,请查看 Font API 参考。

使用 Tailwind CSS#

next/font 使用 CSS 变量与 Tailwind CSS 无缝集成。

在下面的示例中,我们使用来自 next/font/google 的 Inter 和 Roboto_Mono 字体(你可以使用任何 Google 字体或本地字体)。使用 variable 选项为这些字体分别定义 CSS 变量名称,例如 inter 和 roboto_mono。然后,应用 inter.variable 和 roboto_mono.variable 将这些 CSS 变量包含到你的 HTML 文档中。

小知识:你可以将这些变量添加到 <html> 或 <body> 标签,具体取决于你的偏好、样式需求或项目要求。

app/layout.tsx
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})

const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html
      lang="en"
      className={`${inter.variable} ${roboto_mono.variable} antialiased`}
    >
      <body>{children}</body>
    </html>
  )
}
app/layout.js
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})

const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
})

export default function RootLayout({ children }) {
  return (
    <html
      lang="en"
      className={`${inter.variable} ${roboto_mono.variable} antialiased`}
    >
      <body>{children}</body>
    </html>
  )
}
pages/_app.js
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
})

const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
})

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={`${inter.variable} ${roboto_mono.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

最后,将 CSS 变量添加到你的 Tailwind CSS 配置中:

global.css
@import 'tailwindcss';

@theme inline {
  --font-sans: var(--font-inter);
  --font-mono: var(--font-roboto-mono);
}

Tailwind CSS v3#

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

现在你可以使用 font-sans 和 font-mono 工具类将字体应用到你的元素上。

html
<p class="font-sans ...">The quick brown fox ...</p>
<p class="font-mono ...">The quick brown fox ...</p>

应用样式#

你可以通过三种方式应用字体样式:

className#

返回已加载字体的只读 CSS className,可传递给 HTML 元素。

tsx
<p className={inter.className}>Hello, Next.js!</p>

style#

返回已加载字体的只读 CSS style 对象,可传递给 HTML 元素,包括用于访问字体系列名称和回退字体的 style.fontFamily。

tsx
<p style={inter.style}>Hello World</p>

CSS 变量#

如果你希望在外部样式表中设置样式并在其中指定其他选项,请使用 CSS 变量方法。

除了导入字体外,还要导入定义了 CSS 变量的 CSS 文件,并按如下方式设置字体加载器对象的 variable 选项:

app/page.tsx
import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'

const inter = Inter({
  variable: '--font-inter',
})
app/page.js
import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'

const inter = Inter({
  variable: '--font-inter',
})

要使用该字体,请将要设置样式的文本的父容器的 className 设置为字体加载器的 variable 值,并将文本的 className 设置为外部 CSS 文件中的 styles 属性。

app/page.tsx
<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>
app/page.js
<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>

在 component.module.css CSS 文件中按如下方式定义 text 选择器类:

styles/component.module.css
.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

在上面的示例中,文本 Hello World 使用 Inter 字体和生成的字体回退进行样式设置,并带有 font-weight: 200 和 font-style: italic。

使用字体定义文件#

每次调用 localFont 或 Google 字体函数时,该字体都会作为应用程序中的一个实例进行托管。因此,如果你需要在多个地方使用同一字体,应该在一个地方加载它,并在需要的地方导入相关的字体对象。这可以通过字体定义文件来实现。

例如,在应用目录根目录的 styles 文件夹中创建一个 fonts.ts 文件。

然后,按如下方式指定你的字体定义:

styles/fonts.ts
import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'

// 定义你的可变字体
const inter = Inter()
const lora = Lora()
// 定义非可变字体的 2 个字重
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// 定义一个自定义本地字体,其中 GreatVibes-Regular.ttf 存储在 styles 文件夹中
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })

export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }
styles/fonts.js
import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'

// 定义你的可变字体
const inter = Inter()
const lora = Lora()
// 定义非可变字体的 2 个字重
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// 定义一个自定义本地字体,其中 GreatVibes-Regular.ttf 存储在 styles 文件夹中
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })

export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }

现在你可以在代码中按如下方式使用这些定义:

app/page.tsx
import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts'

export default function Page() {
  return (
    <div>
      <p className={inter.className}>Hello world using Inter font</p>
      <p style={lora.style}>Hello world using Lora font</p>
      <p className={sourceCodePro700.className}>
        Hello world using Source_Sans_3 font with weight 700
      </p>
      <p className={greatVibes.className}>My title in Great Vibes font</p>
    </div>
  )
}
app/page.js
import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts'

export default function Page() {
  return (
    <div>
      <p className={inter.className}>Hello world using Inter font</p>
      <p style={lora.style}>Hello world using Lora font</p>
      <p className={sourceCodePro700.className}>
        Hello world using Source_Sans_3 font with weight 700
      </p>
      <p className={greatVibes.className}>My title in Great Vibes font</p>
    </div>
  )
}

为了在代码中更方便地访问字体定义,你可以在 tsconfig.json 或 jsconfig.json 文件中按如下方式定义路径别名:

tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/fonts": ["./styles/fonts"]
    }
  }
}

现在你可以按如下方式导入任何字体定义:

app/about/page.tsx
import { greatVibes, sourceCodePro400 } from '@/fonts'
app/about/page.js
import { greatVibes, sourceCodePro400 } from '@/fonts'

预加载#

当在你站点的某个页面上调用字体函数时,它并非全局可用并在所有路由上预加载。相反,字体仅根据使用它的文件类型在相关路由上预加载:

  • 如果是独立页面,则在该页面的独立路由上预加载。
  • 如果是布局,则在布局包裹的所有路由上预加载。
  • 如果是根布局,则在所有路由上预加载。

当在你站点的某个页面上调用字体函数时,它并非全局可用并在所有路由上预加载。相反,字体仅根据使用它的文件类型在相关路由上预加载:

  • 如果是独立页面,则在该页面的独立路由上预加载
  • 如果在自定义 App中,则在站点 /pages 下的所有路由上预加载

版本变更#

版本变更
v13.2.0@next/font 更名为 next/font。不再需要安装。
v13.0.0添加了 @next/font。
Next.js 中文网