CSS 模組與全域樣式

Next.js 支援不同類型的樣式表，包括：

CSS 模組
全域樣式
外部樣式表

CSS 模組

Next.js 內建支援使用 .module.css 副檔名的 CSS 模組。

CSS 模組透過自動建立唯一類別名稱來實現 CSS 的本地作用域。這讓您可以在不同檔案中使用相同的類別名稱，而無需擔心衝突。此特性使 CSS 模組成為包含元件級 CSS 的理想方式。

範例

CSS 模組可以導入到 app 目錄中的任何檔案：

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

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section className={styles.dashboard}>{children}</section>
}

app/dashboard/styles.module.css

.dashboard {
  padding: 24px;
}

CSS 模組僅對副檔名為 .module.css 和 .module.sass 的檔案啟用。

在生產環境中，所有 CSS 模組檔案將自動串接成多個經過最小化和程式碼分割的 .css 檔案。這些 .css 檔案代表您應用程式中的熱執行路徑，確保載入最少的 CSS 以繪製您的應用程式。

全域樣式

全域樣式可以導入到 app 目錄中的任何布局、頁面或元件。

須知：這與 pages 目錄不同，在 pages 目錄中，您只能在 _app.js 檔案中導入全域樣式。

例如，考慮一個名為 app/global.css 的樣式表：

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

在根布局 (app/layout.js) 中，導入 global.css 樣式表以將樣式套用到應用程式中的每個路由：

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

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

外部樣式表

外部套件發布的樣式表可以導入到 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>
  )
}

須知：外部樣式表必須直接從 npm 套件導入或下載並與您的程式碼庫共置。您不能使用 <link rel="stylesheet" />。

排序與合併

Next.js 在生產建置時透過自動分塊（合併）樣式表來優化 CSS。CSS 的順序由您將樣式表導入應用程式程式碼的順序決定。

例如，base-button.module.css 將排在 page.module.css 之前，因為 <BaseButton> 在 <Page> 中首先導入：

import styles from './base-button.module.css'

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

為了保持可預測的順序，我們建議以下做法：

僅在單一 JS/TS 檔案中導入 CSS 檔案。
- 如果使用全域類別名稱，請按照您希望它們被套用的順序在同一檔案中導入全域樣式。
優先使用 CSS 模組而非全域樣式。
- 為您的 CSS 模組使用一致的命名慣例。例如，使用 <name>.module.css 而非 <name>.tsx。
將共享樣式提取到單獨的共享元件中。
如果使用 Tailwind，請在檔案頂部導入樣式表，最好是在根布局中。

須知：CSS 排序在開發模式下的行為不同，請務必檢查預覽部署以驗證生產建置中的最終 CSS 順序。

附加功能

Next.js 包含附加功能以改善添加樣式的撰寫體驗：

當使用 next dev 本地運行時，本地樣式表（全域或 CSS 模組）將利用快速刷新 (Fast Refresh) 在保存編輯時立即反映變更。
當使用 next build 建置生產版本時，CSS 檔案將被捆綁成更少的最小化 .css 檔案，以減少獲取樣式所需的網路請求數量。
如果禁用 JavaScript，樣式仍將在生產建置 (next start) 中載入。然而，next dev 仍需要 JavaScript 以啟用快速刷新 (Fast Refresh)。

CSS 模組

範例

全域樣式

外部樣式表

排序與合併

附加功能

On this page