全局css只能在_app.tsx或app/layout.tsx顶层第一行导入,不可包裹逻辑或动态加载;文件须为纯css(非module)、不含:global;tailwind指令需同文件顶部声明;路径、路由结构与postcss配置须严格匹配。

全局CSS只能在_app.tsx或app/layout.tsx顶层导入
Next.js 14 不允许在页面、组件或任何非根布局文件中 import 全局 CSS,否则会报错 Global CSS cannot be imported from files other than your Custom _app。这个限制不是“建议”,而是构建阶段的硬性检查——Webpack/Next 编译器必须在 SSR 前静态提取样式,而只有 _app.tsx(Pages Router)或 app/layout.tsx(App Router)被识别为合法入口。
判断该用哪个文件,只看项目结构:
- 有
app/目录(哪怕只有app/layout.tsx),就用app/layout.tsx;pages/_app.tsx被完全忽略 - 只有
pages/目录、无app/,才用pages/_app.tsx - 两者共存?Pages 路由走
pages/_app.tsx,App 路由走app/layout.tsx,互不干扰
import 必须是文件第一行,且不能包裹在任何逻辑里
哪怕前面多一个空行、一个注释、或 import React from 'react',都会导致构建失败或样式丢失。Next.js 的样式收集机制只认“真正顶层”的静态 import。
- ✅ 正确:
import '../styles/globals.css';是pages/_app.tsx的第一行 - ✅ 正确:
import './globals.css';是app/layout.tsx的第一行(推荐把文件放在app/globals.css) - ❌ 错误:写在
function MyApp()函数体内、useEffect里、或if (process.browser)条件中 - ❌ 错误:用
import('./styles/globals.css')动态导入——它不会生成<link rel="stylesheet">
globals.css 文件本身不能是模块,也不能含 :global
Next.js 默认把 .module.css 当作局部样式,而全局 CSS 必须是“纯” CSS 文件。一旦文件名带 .module.css 后缀,或内容里写了 :global{},或者 next.config.js 里启用了 cssModules: { auto: true },就会被当成模块处理,导致全局规则失效。
- 文件名必须是
globals.css(或类似reset.css),不能是globals.module.css - 内容里不能出现
:global—— 那是 CSS Modules 的语法,和全局 CSS 冲突 - 如果用了 Tailwind,
@tailwind base、@tailwind components、@tailwind utilities必须都在同一个 CSS 文件里,且放在最顶部,不能拆开再分别 import - PostCSS 配置(如
postcss.config.mjs)必须启用@tailwindcss/postcss,否则@tailwind指令解析失败
开发时看着正常,build 后样式消失?先查这三处
热更新常掩盖路径、路由模式或配置问题,导致你误以为“已经好了”。实际构建后样式全丢,往往卡在这几个点:
-
_app.tsx或app/layout.tsx没被实际加载:比如 App Router 项目里还留着pages/_app.tsx,但 Next.js 根本不读它 - 路径写错:在
app/layout.tsx里写import '../styles/globals.css'(多了一级 ../),正确应是import './globals.css'(假设文件在同目录) - Tailwind 的
content配置没覆盖到实际使用 className 的文件——比如用了src/app结构,但tailwind.config.js里只写了./app/**/*,漏了src/前缀
改完 tailwind.config.js 或新增全局 CSS 文件后,必须重启 npm run dev,热更新不会重新扫描 content 路径。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











