如何在應用程式中使用 CSS

Next.js 提供了多種在應用程式中使用 CSS 的方式，包括：

CSS 模組 (CSS Modules)
全域 CSS (Global CSS)
外部樣式表 (External Stylesheets)
Tailwind CSS
Sass
CSS-in-JS

CSS 模組 (CSS Modules)

CSS 模組透過生成唯一的類別名稱來實現 CSS 的局部作用域。這讓您可以在不同檔案中使用相同的類別名稱，而不用擔心命名衝突。

要開始使用 CSS 模組，請建立一個副檔名為 .module.css 的新檔案，並將其導入到 app 目錄下的任何元件中：

app/blog/blog.module.css

.blog {
  padding: 24px;
}

import styles from './blog.module.css'

export default function Page() {
  return <main className={styles.blog}></main>
}

全域 CSS (Global CSS)

您可以使用全域 CSS 來為整個應用程式套用樣式。

建立一個 app/global.css 檔案並將其導入到根佈局 (root layout) 中，即可將樣式套用到應用程式中的每個路由：

app/global.css

body {
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}

// 這些樣式會套用到應用程式中的每個路由
import './global.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

重要須知： 全域樣式可以導入到 app 目錄下的任何佈局、頁面或元件中。然而，由於 Next.js 使用 React 內建的樣式表支援來與 Suspense 整合，目前這不會在路由之間導航時移除樣式表，這可能會導致衝突。我們建議將全域樣式用於真正全域的 CSS，而對於作用域 CSS 則使用 CSS 模組 (CSS Modules)。

外部樣式表 (External stylesheets)

外部套件發佈的樣式表可以導入到 app 目錄下的任何位置，包括共置的元件：

import 'bootstrap/dist/css/bootstrap.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="container">{children}</body>
    </html>
  )
}

重要須知： 在 React 19 中，也可以使用 <link rel="stylesheet" href="..." />。詳情請參閱 React link 文件。

排序與合併 (Ordering and Merging)

Next.js 在生產環境建置時會透過自動分塊（合併）樣式表來優化 CSS。CSS 的順序取決於您在程式碼中導入樣式的順序。

例如，base-button.module.css 會排在 page.module.css 之前，因為 <BaseButton> 是在 page.module.css 之前導入的：

import { BaseButton } from './base-button'
import styles from './page.module.css'

export default function Page() {
  return <BaseButton className={styles.primary} />
}

建議

為了保持 CSS 順序的可預測性：

嘗試將 CSS 導入集中在單一的 JavaScript 或 TypeScript 入口檔案中
在應用程式的根目錄導入全域樣式和 Tailwind 樣式表
對於嵌套元件，使用 CSS 模組而非全域樣式
為 CSS 模組使用一致的命名慣例。例如，使用 <name>.module.css 而非 <name>.tsx
將共享樣式提取到共享元件中，避免重複導入
關閉會自動排序導入的 linter 或格式化工具，如 ESLint 的 sort-imports
您可以在 next.config.js 中使用 cssChunking 選項來控制 CSS 的分塊方式

開發環境與生產環境 (Development vs Production)

在開發環境 (next dev) 中，CSS 更新會透過快速刷新 (Fast Refresh) 即時套用
在生產環境 (next build) 中，所有 CSS 檔案會自動串接成多個經過最小化和程式碼分割的 .css 檔案，確保為每個路由加載最少的 CSS
在生產環境中，即使禁用 JavaScript，CSS 仍會加載，但在開發環境中需要 JavaScript 來實現快速刷新
CSS 順序在開發環境中可能表現不同，請務必檢查建置結果 (next build) 以驗證最終的 CSS 順序

CSS 模組 (CSS Modules)

全域 CSS (Global CSS)

外部樣式表 (External stylesheets)

排序與合併 (Ordering and Merging)

建議

開發環境與生產環境 (Development vs Production)

Tailwind CSS

Sass

CSS-in-JS

On this page