字體模組

next/font 會自動優化您的字型（包括自訂字型），並移除外部網路請求以提升隱私和效能。

它包含內建的自動自我託管功能，適用於任何字型檔案。這意味著您可以無需擔心版面偏移 (layout shift) 的情況下最佳化載入網頁字型。

您也可以方便地使用所有 Google 字型。CSS 和字型檔案會在建置時下載，並與其他靜態資源一起自我託管。瀏覽器不會向 Google 發送任何請求。

要在所有頁面中使用字型，請將其新增至 /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 分鐘)。

參考

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)，有以下可能性：

• 一個字串，值為特定字型可用的字重，或如果是可變字型 (variable font) 則為值的範圍
• 如果字型不是可變 Google 字型 (variable google font)，則為字重值的陣列。僅適用於 next/font/google

用於 next/font/google 和 next/font/local

• 如果使用的字型不是可變字型 (variable)，則必填

範例：

• 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 字型 (variable google font)，則為樣式值的陣列。僅適用於 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)。透過 subsets 指定的字型在 preload 選項為 true（預設值）時，會在 head 中注入一個 link preload 標籤。

用於 next/font/google

• 選填

範例：

• subsets: ['latin']：包含子集 latin 的陣列

您可以在 Google 字型頁面上找到您字型的所有子集列表。

axes

某些可變字型具有可以包含的額外 axes。預設情況下，僅包含字重以保持檔案大小較小。axes 的可能值取決於特定字型。

用於 next/font/google

• 選填

範例：

• axes: ['slnt']：值為 slnt 的陣列，用於 Inter 可變字型，該字型具有 slnt 作為額外的 axes，如此處所示。您可以在 Google 可變字型頁面上使用篩選器並尋找 wght 以外的 axes 來找到您字型的可能 axes 值

display

字型的顯示 (display)，可能的字串值為 'auto'、'block'、'swap'、'fallback' 或 'optional'，預設值為 'swap'。

用於 next/font/google 和 next/font/local

• 選填

範例：

• display: 'optional'：分配給 optional 值的字串

preload

一個布林值，指定是否應預載 (preload) 字型。預設為 true。

用於 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：一個布林值，設定是否應使用自動後備字型來減少累積版面偏移 (Cumulative Layout Shift)。預設為 true。
• 對於 next/font/local：一個字串或布林值 false，設定是否應使用自動後備字型來減少累積版面偏移 (Cumulative Layout Shift)。可能的值為 '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

一個字型面描述符 (descriptor) 鍵值對的陣列，進一步定義生成的 @font-face。

用於 next/font/local

• 選填

範例：

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

範例

Google 字型

要使用 Google 字型，請從 next/font/google 匯入它作為一個函式。我們建議使用可變字型 (variable fonts) 以獲得最佳效能和靈活性。

要在所有頁面中使用字型，請將其新增至 /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>
  )
}

如果您無法使用可變字型，則需要指定一個字重：

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>
  )
}

您可以透過使用陣列來指定多個字重和/或樣式：

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

小知識： 對於包含多個單詞的字型名稱，請使用底線 (_)。例如，Roboto Mono 應匯入為 Roboto_Mono。

在 <head> 中套用字型

您也可以在不使用包裝器和 className 的情況下使用字型，方法是將其注入到 <head> 中，如下所示：

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} />
    </>
  )
}

單頁使用

要在單一頁面上使用字型，請將其新增至特定頁面，如下所示：

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 字型會自動子集化 (subset)。這減少了字型檔案的大小並提高了效能。您需要定義您想要預載的子集。如果在 preload 為 true 時未指定任何子集，則會產生警告。

這可以透過將其新增至函式呼叫來完成：

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

查看字型 API 參考以獲取更多資訊。

使用多種字型

您可以在應用程式中匯入並使用多種字型。有兩種方法可以實現。

第一種方法是建立一個匯出字型的工具函式，在需要的地方匯入並套用其 className。這確保字型只在渲染時預先載入：

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',
})

在上面的範例中，Inter 會全域套用，而 Roboto Mono 可以按需匯入並套用。

或者，您可以建立一個 CSS 變數 並與您偏好的 CSS 解決方案一起使用：

html {
  font-family: var(--font-inter);
}

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

在上面的範例中，Inter 會全域套用，而任何 <h1> 標籤會使用 Roboto Mono 樣式。

建議：謹慎使用多種字型，因為每新增一種字型都是客戶端需要下載的額外資源。

本地字型

匯入 next/font/local 並指定本地字型檔案的 src。我們建議使用 可變字型 (variable fonts) 以獲得最佳效能和靈活性。

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 可以是陣列：

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',
    },
  ],
})

檢視 字型 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> 標籤。

import { Inter } 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 設定檔：

Tailwind CSS v4

從 Tailwind v4 開始，預設不需要任何設定。如果需要設定 Tailwind，可以遵循 官方文件 來設定全域 CSS 檔案。

@import "tailwindcss";

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

Tailwind CSS v3

/** @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 工具類別將字型套用到元素上。

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

套用樣式

您可以透過三種方式套用字型樣式：

• className
• style
• CSS 變數

className

返回一個唯讀的 CSS className，用於將載入的字型傳遞給 HTML 元素。

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

style

返回一個唯讀的 CSS style 物件，用於將載入的字型傳遞給 HTML 元素，包括 style.fontFamily 以存取字型家族名稱和備用字型。

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

CSS 變數

如果您想在外部樣式表中設定樣式並在那裡指定其他選項，請使用 CSS 變數方法。

除了匯入字型外，還匯入定義 CSS 變數的 CSS 檔案，並如下設定字型載入器物件的 variable 選項：

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

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

要使用字型，將要設定樣式的文字父容器的 className 設定為字型載入器的 variable 值，並將文字的 className 設定為來自外部 CSS 檔案的 styles 屬性。

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

在 component.module.css CSS 檔案中定義 text 選擇器類別如下：

.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 檔案。

然後，如下指定您的字型定義：

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'

// 定義您的可變字型
const inter = Inter()
const lora = Lora()
// 定義非可變字型的兩種字重
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 }

現在您可以在程式碼中使用這些定義如下：

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

export default function Page() {
  return (
    <div>
      <p className={inter.className}>使用 Inter 字型的 Hello world</p>
      <p style={lora.style}>使用 Lora 字型的 Hello world</p>
      <p className={sourceCodePro700.className}>
        使用字重 700 的 Source_Sans_3 字型的 Hello world
      </p>
      <p className={greatVibes.className}>使用 Great Vibes 字型的標題</p>
    </div>
  )
}

為了更輕鬆地在程式碼中存取字型定義，您可以在 tsconfig.json 或 jsconfig.json 檔案中定義路徑別名如下：

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

現在您可以如下匯入任何字型定義：

import { greatVibes, sourceCodePro400 } from '@/fonts'

預先載入

當在您網站的頁面上呼叫字型函式時，它不會全域可用，也不會在所有路由上預先載入。相反，字型只會根據使用它的檔案類型在相關路由上預先載入：

• 如果是 唯一頁面，它會在該頁面的唯一路由上預先載入。
• 如果在 自訂 App 中，它會在 /pages 下的所有網站路由上預先載入。

版本變更