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 模块）将利用快速刷新在保存编辑时即时反映更改。
使用 next build 构建生产环境时，CSS 文件将被捆绑为更少的压缩 .css 文件，以减少获取样式所需的网络请求数量。
如果禁用 JavaScript，在生产构建 (next start) 中样式仍会被加载。然而，next dev 仍需要 JavaScript 以启用快速刷新。

CSS 模块

示例

全局样式

外部样式表

排序与合并

附加特性

On this page