Next.jsCSSSSR配置详解

Next.js 13+ 的 app 目录彻底重构了 CSS 处理机制：CSS 不再是“随处可导入”的资源，而是必须作为编译时确定的模块入口被顶层 layout 显式消费——仅 `app/layout.tsx` 中的 `import './globals.css'` 才能触发服务端样式注入，组件内导入非模块 CSS 会被静默忽略，CSS Modules 必须严格使用 `.module.css` 后缀并以对象形式应用类名，Tailwind 需精准配置 `content` 路径以防生产环境样式丢失，`next.config.js` 中冗余的 CSS 配置反而会破坏作用域，自定义 `_document` 完全失效，所有样式、字体、meta 信息都必须通过 layout 或 metadata 声明。理解这套“导入即声明、命名即契约、顶层即关键”的新范式，才能避开 FOUC、样式丢失、哈希失效等高频陷阱。

Next.js 13+ 中 app 目录下怎么让 CSS 生效

服务端渲染（SSR）时 CSS 不生效，不是你漏写了 import，而是 Next.js 的 app 目录强制要求 CSS 必须作为模块入口被“消费”——它不支持传统 link 或全局 import 注入。

• app/layout.tsx 里直接 import './globals.css' 是合法的，且是唯一推荐方式；其他位置（比如组件内部）import 非模块 CSS 会被忽略
• 如果用了 css_modules（Button.module.css），必须通过 import styles from './Button.module.css' + className={styles.xxx} 使用，不能靠文件名自动注入
• 动态 import() 加载的组件里写 import './xxx.css' 无效，CSS 不会随组件 SSR 到 HTML 中

为什么 next.config.js 里的 cssModules 配置没起作用

Next.js 默认已启用 CSS Modules 支持，next.config.js 中显式配置 cssModules: true 不仅多余，还可能触发旧版行为兼容逻辑，导致 .module.css 文件被当作普通 CSS 处理（类名不哈希、无作用域）。

• 删除 next.config.js 中所有与 css、cssModules、postcss 相关的自定义配置，除非你明确需要 PostCSS 插件或 CSS-in-JS 替代方案
• 确认文件名后缀是 .module.css（不是 .css 或 .modules.css），Next.js 只认这个命名约定
• 如果用了 Tailwind，确保 tailwind.config.js 的 content 字段包含 app/**/*.{js,ts,jsx,tsx}，否则 class 名在生产环境可能被 PurgeCSS 误删

Link 组件预加载 CSS 时样式闪动（FOUC）

用 next/link 跳转到新页面时，CSS 还没加载完就渲染了 HTML，用户看到未样式化的 DOM —— 这不是 JS 执行慢，而是 Next.js 默认不把 CSS 当作关键资源同步注入首屏 HTML。

• 确保所有 CSS 都通过 app/layout.tsx 或 app/[...]/layout.tsx 的顶层 import 引入，Next.js 会自动提取并内联关键 CSS 到
• 避免在 useEffect 或事件回调中动态 import('./async.css')，这种加载无法参与 SSR 流程，必然 FOUC
• 如果用了第三方 UI 库（如 MUI、Ant Design），检查它们是否提供 Next.js 适配的 ServerStyleSheets 或 extractCritical 方案；否则其 CSS 通常只在客户端注入

自定义 Document 还能用吗？

不能。在 app 目录下，pages/_document.tsx 完全失效；Next.js 不再允许你手动操作 或 结构 —— 所有 CSS 注入、字体预加载、meta 标签都必须走 app/layout.tsx 或 app/head.tsx（后者已废弃，仅支持 metadata 对象）。

• 想加全局 ？不行，必须用 import 引入本地 CSS 文件
• 想内联一段 critical CSS？只能写在 app/layout.tsx 的 里，但注意：该 是 React 组件，不是 HTML 模板，不支持原生