怎么在Next.js中正确引入全局与局部CSS?

夏杰吖_9721

夏杰吖_9721

2026-10-02

671人浏览

原创

全局css必须在_pages/_app.js或_app router的app/layout.tsx顶层静态导入;局部css须用.module.css后缀并对象解构使用,混用路径、后缀或位置将直接报错或失效。

怎么在next.js中正确引入全局与局部css?

全局 CSS 必须在路由系统顶层静态导入,局部 CSS 必须用 .module.css 后缀 + 对象解构使用——混用路径、后缀或导入位置,直接报错或样式失效。

全局 CSS 只能在 _app.js 或 app/layout.tsx 顶层导入

Next.js 把全局样式当作“服务端注入的公共资源”,只认两个入口:Pages Router 的 pages/_app.js(或 .tsx),或 App Router 的 app/layout.tsx(或 .js)。其他任何地方 import 都会触发 Global CSS cannot be imported from files other than your Custom _app.js 错误。

  • 必须是文件第一行语句,前面不能有注释、import React、use client 等任何内容
  • 路径必须正确:pages/_app.js 里写 import '../styles/global.css';app/layout.tsx 里推荐 import './globals.css'(文件放在 app/globals.css)
  • 不能动态导入:import('./global.css')、require()、useEffect 里加载全无效
  • 如果项目同时存在 pages/ 和 app/ 目录,两套全局样式互不干扰——pages 页面只走 _app.js,app 页面只走 layout.tsx

.module.css 是局部 CSS 的唯一合法形式

Next.js 不允许普通 .css 文件在组件中直接 import 作为局部样式。它强制你用 .module.css 后缀,且必须通过对象解构方式使用类名,否则样式不会作用于组件,甚至可能被当成全局 CSS 处理而报错。

Json Schema Toolkit
Json Schema Toolkit

使用 JSON Schema 验证 JSON 数据,从示例 JSON 生成 schema,并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。

下载
  • 文件命名必须含 .module.css(不是 .css、.modules.css 或 .less)
  • 导入写法固定:import styles from './Button.module.css',然后 className={styles.button}
  • 不能靠 className="button" 直接写类名——类名会被哈希化,如 button_abc123,硬写无效
  • 支持嵌套、:global() 包裹穿透、@apply(配合 Tailwind)等,但所有规则都基于模块化解析链

App Router 下别碰 next.config.js 的 CSS 配置

Next.js 13+ App Router 已移除对第三方 CSS 插件(如 withLess)的支持,也默认禁用自定义 cssModules 配置。你在 next.config.js 里加 cssModules: { auto: false } 或 postcss 规则,不仅没用,还可能触发构建警告或样式丢失。

  • 删掉 next.config.js 中所有与 css、postcss、webpack 相关的自定义配置(除非你明确需要 PostCSS 插件)
  • 想用 Sass?直接改后缀为 .module.scss,无需安装 loader,开箱即用
  • 想用 Less?官方已弃用,next-with-less 在 v14 兼容性极差,构建常报 Unexpected character '@' 或 Selector is not pure —— 改用 Sass 是唯一稳妥路径
  • Tailwind 用户注意:tailwind.config.js 的 content 字段必须包含 app/**/*.{js,ts,jsx,tsx},否则生产环境 class 名可能被 PurgeCSS 删除

第三方库样式(如 Ant Design、Bootstrap)怎么引入

它们本质也是全局 CSS,引入逻辑和自定义全局 CSS 完全一致:只在 _app.js(Pages Router)或 app/layout.tsx(App Router)顶层 import,不能在组件里 import。

  • Pages Router:import 'antd/dist/reset.css'(v5 推荐 reset.css,非 antd.min.css)
  • App Router:import 'bootstrap/dist/css/bootstrap.min.css',但必须确保该 import 在 app/layout.tsx 第一行
  • Ant Design v4 的 :global(.ant-menu-sub) 写法在 App Router 下大概率报错,需手动剥离或升级到 v5
  • 不要在组件里 import 'xxx.css',哪怕加了 'use client'——Next.js 服务端不解析组件内的全局 CSS 导入

最容易被忽略的是:全局样式的作用域严格绑定路由系统。App Router 页面永远看不到 pages/_app.js 里的样式,Pages Router 页面也永远用不到 app/layout.tsx 里 import 的 CSS——双路由并存时,你得维护两套独立的全局样式入口,而不是指望一个文件管全部。

前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!

相关专题

更多
css
css

css是层叠样式表,用来表现HTML或XML等文件样式的计算机语言,不仅可以静态地修饰网页,还可以配合各种脚本语言动态地对网页各元素进行格式化。php中文网还为大家带来html的相关下载资源、相关课程以及相关文章等内容,供大家免费下载使用。

2023.06.15

4176

6

css居中
css居中

css居中:1、通过“margin: 0 auto; text-align: center”实现水平居中;2、通过“display:flex”实现水平居中;3、通过“display:table-cell”和“margin-left”实现居中。本专题为大家提供css居中的相关的文章、下载、课程内容,供大家免费下载体验。

2023.07.27

917

5

css如何插入图片
css如何插入图片

cssCSS是层叠样式表(Cascading Style Sheets)的缩写。它是一种用于描述网页或应用程序外观和样式的标记语言。CSS可以控制网页的字体、颜色、布局、大小、背景、边框等方面,使得网页的外观更加美观和易于阅读。php中文网给大家带来了相关的教程以及文章,欢迎大家前来阅读学习。

2023.07.28

1778

6

css超出显示...
css超出显示...

在CSS中,当文本内容超出容器的宽度或高度时,可以使用省略号来表示被隐藏的文本内容。本专题为大家提供css超出显示...的相关文章,相关教程,供大家免费体验。

2023.08.01

3286

7

css字体颜色
css字体颜色

CSS中,字体颜色可以通过属性color来设置,用于控制文本的前景色,字体颜色在网页设计中起到很重要的作用,具有以下表现作用:1、提升可读性;2、强调重点信息;3、营造氛围和美感;4、用于呈现品牌标识或与品牌形象相符的风格。

2023.08.10

6525

11

什么是css
什么是css

CSS是层叠样式表(Cascading Style Sheets)的缩写,是一种用于描述网页(或其他基于 XML 的文档)样式与布局的标记语言,CSS的作用和意义如下:1、分离样式和内容;2、页面加载速度优化;3、实现响应式设计;4、确保整个网站的风格和样式保持统一。

2023.08.10

5551

7

css三角形怎么写
css三角形怎么写

CSS可以通过多种方式实现三角形形状,本专题为大家提供css三角形怎么写的相关教程,大家可以免费体验。

2023.08.21

1917

9

css设置文字颜色
css设置文字颜色

CSS(层叠样式表)可以用于设置文字颜色,这样做有以下好处和优势:1、增加网页的可视化效果;2、突出显示某些重要的信息或关键字;3、增强品牌识别度;4、提高网页的可访问性;5、引起不同的情感共鸣。

2023.08.22

2631

5

css禁止点击事件
css禁止点击事件

实现css禁止点击事件的方法有使用CSS的pointer-events属性和使用JavaScript禁用点击事件。本专题为大家提供点击事件相关的文章、下载、课程内容,供大家免费下载体验。

2023.08.23

2273

5

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
Sass 教程
Sass 教程

共14课时 | 1.5万人学习

Bootstrap 5教程
Bootstrap 5教程

共46课时 | 5.8万人学习

CSS教程
CSS教程

共754课时 | 95.4万人学习