Menu

CSS

Next.js 支持多种处理 CSS 的方式，包括：

CSS Modules

Next.js 内置支持使用 .module.css 扩展名的 CSS Modules。

CSS Modules 通过自动创建唯一的类名来实现 CSS 的局部作用域。这使得你可以在不同文件中使用相同的类名而不用担心冲突。这种特性使 CSS Modules 成为引入组件级 CSS 的理想方式。

示例

CSS Modules 可以在 app 目录下的任何文件中导入：

app/dashboard/layout.tsx
TypeScript
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 Modules 仅对扩展名为 .module.css 和 .module.sass 的文件启用。

在生产环境中，所有 CSS Module 文件会自动合并成多个经过代码分割和压缩的 .css 文件。这些 .css 文件代表了应用程序中的热执行路径，确保只加载应用程序渲染所需的最少 CSS。

全局样式

全局样式可以在 app 目录下的任何布局、页面或组件中导入。

值得注意的是：

  • 这与 pages 目录不同，在 pages 目录中你只能在 _app.js 文件中导入全局样式。
  • Next.js 不支持使用全局样式，除非它们真的是全局的，意味着它们可以应用于所有页面并在应用程序的生命周期内存在。这是因为 Next.js 使用 React 内置的样式表支持来集成 Suspense。这种内置支持目前不会在路由导航时移除样式表。因此，我们建议使用 CSS Modules 而不是全局样式。

例如，考虑一个名为 app/global.css 的样式表：

app/global.css
body {
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}

在根布局 (app/layout.js) 中，导入 global.css 样式表以将样式应用到应用程序的每个路由：

app/layout.tsx
TypeScript
// 这些样式适用于应用程序中的每个路由
import './global.css'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

外部样式表

外部包发布的样式表可以在 app 目录下的任何位置导入，包括共同定位的组件：

app/layout.tsx
TypeScript
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 的顺序是由_你在应用程序代码中导入样式表的顺序_决定的。

例如，由于首先导入 <BaseButton>，base-button.module.css 的顺序会在 page.module.css 之前：

base-button.tsx
TypeScript
import styles from './base-button.module.css'
 
export function BaseButton() {
  return <button className={styles.primary} />
}
page.ts
TypeScript
import { BaseButton } from './base-button'
import styles from './page.module.css'
 
export function Page() {
  return <BaseButton className={styles.primary} />
}

为了保持可预测的顺序，我们建议以下做法：

  • 只在单个 JS/TS 文件中导入一个 CSS 文件。
    • 如果使用全局类名，在同一个文件中按照你想要应用的顺序导入全局样式。
  • 优先使用 CSS Modules 而不是全局样式。
    • 为你的 CSS modules 使用一致的命名约定。例如，使用 <name>.module.css 而不是 <name>.tsx。
  • 将共享样式提取到单独的共享组件中。
  • 如果使用 Tailwind，最好在文件顶部导入样式表，最好是在根布局中。
  • 关闭任何会自动对导入进行排序的 linters/formatters（例如，ESLint 的 sort-import）。这可能会无意中影响你的 CSS，因为 CSS 导入顺序_很重要_。

值得注意的是：

  • CSS 排序在开发模式下的行为可能不同，始终确保检查构建（next build）以验证最终的 CSS 顺序。
  • 你可以使用 next.config.js 中的 cssChunking 选项来控制 CSS 如何分块。

其他功能

Next.js 包含额外的功能来改善添加样式的编写体验：

  • 在使用 next dev 本地运行时，本地样式表（全局或 CSS modules）将利用 Fast Refresh 在保存编辑时立即反映更改。
  • 在使用 next build 构建生产版本时，CSS 文件将被打包成更少的经过压缩的 .css 文件，以减少获取样式所需的网络请求数量。
  • 如果你禁用 JavaScript，样式仍然会在生产构建（next start）中加载。但是，next dev 需要 JavaScript 来启用 Fast Refresh。