next.js 中 scss 文件需以 .module.scss 命名才启用 css modules，否则会全局污染或报错；必须安装 sass（非 node-sass），且在 app router 中仅限 client component 或 layout/page 文件中导入。
SCSS 文件未被正确识别为模块
Next.js 默认不自动处理 .scss 文件的 CSS Modules 行为，除非显式启用或命名规范不匹配。常见现象是：开发时样式正常，构建后类名丢失、全局污染或 Module not found 报错。
- 确保文件名以
.module.scss结尾（如Button.module.scss），否则 Next.js 不会启用 CSS Modules 模式 - 若用普通
.scss文件做全局样式，必须在_app.tsx或layout.tsx中显式import，且不能出现在客户端组件顶层（避免 SSR 时window相关报错） - 检查
next.config.js是否误加了自定义css-loader配置——Next.js 13.4+ 内置 Sass 支持，额外配置反而破坏默认行为
node-sass 与 sass 包冲突或缺失
Next.js 官方只支持 sass（Dart Sass），不兼容已废弃的 node-sass。生产构建失败常因 package.json 中同时存在两者，或 sass 未安装。
- 运行
npm ls sass确认是否已安装且版本 ≥1.70.0；若输出为空或报错，执行npm install sass - 执行
npm uninstall node-sass—— 即使没直接依赖，某些旧版 UI 库（如 antd@4）可能间接拉取，引发构建时Cannot find module 'node-sass' - CI/CD 环境中注意：Docker 或 Netlify 构建缓存可能残留旧
node_modules，建议加cache: false或清缓存重试
SCSS 变量或函数在服务端解析失败
当 SCSS 中使用了仅浏览器环境可用的 JS 函数（如 env()、theme() 非标准函数），或依赖未声明的变量，next build 会直接中断并报 SassError。
- 避免在
.scss中调用calc()外的运行时函数；CSS 自定义属性（--color）应在 JS 中注入，而非 SCSS 中动态读取 - 检查
@use或@import路径是否含绝对路径（如@use 'src/styles/vars';）——Next.js 不支持裸路径，应改用相对路径或配置sassOptions.includePaths - 若用
postcss插件（如autoprefixer），确认其版本与 Next.js 内置 PostCSS 兼容（Next.js 14+ 使用 PostCSS 8.x，postcss-preset-env需 ≥9.0）
App Router 下的样式作用域混乱
在 app/ 目录中，Next.js 要求样式文件必须与组件同级且命名一致（如 page.tsx 对应 page.module.scss），否则构建时无法关联，导致样式不生效或重复注入。
-
app/layout.tsx中的全局样式需单独import './globals.scss'，且该文件不能是.module.scss - 不要在 Server Component 中
import任何.scss—— 这会触发构建错误；所有样式导入必须位于'use client'组件内或layout.tsx/page.tsx等路由文件中 - 若使用 CSS-in-JS 库（如 Emotion），注意其 SSR 支持配置；Next.js App Router 的流式渲染下，Emotion 需配合
@emotion/server和CacheProvider才能保证服务端样式正确注入
@import 的路径，或者 sass 包被 node-sass 的残留文件干扰。先跑 npx sass --version 确认 CLI 可用，再看构建日志里第一个 SassError 行——它指向的文件，就是破局起点。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
