全局css必须在_pages/_app.js或_app router的app/layout.tsx顶层静态导入;局部css须用.module.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 验证 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实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










