全局css必须在_pages/_app.js或_app.tsx_(pages router)或_app/layout.tsx_(app router)顶层静态导入,且仅限一次、纯css文件、不可动态或嵌套;组件级css须用.module.css后缀并在组件内按需导入,混用会报错或失效。

全局 CSS 必须在路由系统对应的根布局文件顶层静态导入,组件级 CSS(即 CSS Modules)必须用 .module.css 后缀并在组件内按需导入——混用或错位会直接报错或样式失效。
全局 CSS 只能在 _app.js 或 app/layout.tsx 顶层导入
Next.js 不允许从任意文件 import 全局 CSS,它只认两个“合法入口”:Pages Router 的 pages/_app.js,或 App Router 的 app/layout.tsx。其他任何位置(比如 pages/index.js、components/Button.js、甚至 _app.js 函数体内)都会触发 Global CSS cannot be imported from files other than your Custom _app.js 错误。
- Pages Router:确保项目有
pages/_app.js,且第一行就是import '../styles/globals.css',前面不能有注释、空行或任何其他语句 - App Router:删掉
pages/_app.js(它会被忽略),改用app/layout.tsx,同样在首行写import './globals.css'(推荐路径)或import '../styles/globals.css' - 如果同时存在
pages/和app/目录,得分别配置:Pages 页面走pages/_app.js,App 页面走app/layout.tsx,两者互不影响 - 该 CSS 文件必须是纯全局样式:不能含
:global、不能叫globals.module.css、不能被next.config.js配置为自动模块化(如cssModules: { auto: true })
.module.css 是组件级 CSS 的唯一合法形式
Next.js 对组件样式隔离只认 .module.css(或 .module.scss 等)后缀。只要文件名带 .module,Next.js 就自动启用 CSS Modules,类名会被哈希化,避免全局污染。
使用 JSON Schema 验证 JSON 数据,从示例 JSON 生成 schema,并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
- 正确命名:
Button.module.css,然后在组件中import styles from './Button.module.css' - 错误命名:
Button.css或Button.scss—— 这会被当作全局样式处理,一旦在组件里 import,就会报错 - 不能在
_app.js或app/layout.tsx中 import.module.css,否则构建失败:Module parse failed - 支持 Sass/Less:装好
sass或less,命名改为Button.module.scss即可,无需额外配置
Tailwind 和全局 CSS 的关系不是“引入”,而是“注入”
Tailwind 不是靠 import 加载的 CSS 文件,它是通过 PostCSS 插件在构建时把工具类编译进最终 CSS 的。所以你不能把它拆开放在多个文件里,也不能只在某个组件里 import tailwind.css。
- 必须把
@tailwind base、@tailwind components、@tailwind utilities全部写在那个全局 CSS 文件(如globals.css)里 - 这个文件本身需要被
_app.js或app/layout.tsx顶层 import,否则 Tailwind 类不会生效 - 如果用了
@layer,必须配好postcss.config.mjs,否则构建静默失败或样式丢失 - 不要在
.module.css里写@tailwind—— 它不支持,也没意义
常见报错和绕不开的坑
这些错误几乎都源于导入位置、文件命名或构建配置的微小偏差:
-
Global CSS cannot be imported from files other than your Custom _app.js:大概率是 App Router 项目却还在pages/_app.js里写 import,或者 import 没放在首行 - 样式刷新后消失:CSS 文件里用了
@layer或@import,但postcss.config.mjs缺失或插件没启用 - 页面空白或布局错乱:全局 CSS 里写了
body { display: none }或重置了html尺寸,影响所有路由 - 热更新不生效:改了
globals.css但没重启 dev server,尤其在启用了fastRefresh的旧项目中
最易被忽略的是:全局 CSS 的作用域完全由路由系统决定——App Router 的 app/layout.tsx 导入对 pages/ 下任何页面都无效,反之亦然。没有“一次配置,全站生效”这回事。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










