Next.js生产环境为何出现CSS chunk与style标签样式重复问题

问题描述 #

项目基于Next.js搭建，样式方案组合使用Tailwind CSS、SCSS Modules与PostCSS，未对webpack配置做任何自定义覆写。开发模式运行时Next.js会正常在<style>标签内注入样式，符合预期；但生产环境运行时会同时加载抽离后的*.css chunk文件、以及<style>标签内的同内容样式，引发样式重复加载、优先级冲突问题。
问题现象参考：

修复步骤 #

按优先级从高到低排查调整即可：

• 排查自定义Document/根布局的样式引入逻辑
  不要在pages/_document.tsx（Pages Router）或app/layout.tsx（App Router）中手动编写样式收集、注入逻辑，Next.js生产构建已经内置了CSS抽离、注入能力，旧版本手动收集style标签的逻辑在新版Next.js中会直接导致双份样式注入。如果_document.tsx中存在自定义getInitialProps拼接样式标签的代码，直接删除即可。
  全局样式（包括Tailwind入口样式文件、全局SCSS文件）仅允许在pages/_app.tsx（Pages Router）或根layout.tsx（App Router）中引入一次，禁止在_document、普通页面、业务组件中重复引入全局样式。
• 校验PostCSS与Tailwind配置
  检查根目录postcss.config.js，不要重复添加和Next.js内置能力冲突的插件（比如额外配置postcss-import、CSS抽离类插件），标准配置仅保留两项即可：

  // postcss.config.js
  module.exports = {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
  }
  

  同时检查tailwind.config.js的content字段，不要把.next、out等构建输出目录加入扫描路径，否则Tailwind会把已经编译完成的生产CSS重复扫描注入，造成样式重复。
• 规范SCSS Modules使用方式
  所有*.module.scss文件必须按模块化规则使用，非全局样式不要用:global包裹，全局样式统一收敛到全局样式入口文件中，不要散落在各个模块SCSS文件里。禁止把模块SCSS文件当做全局CSS直接import引入使用，否则会导致样式被同时处理到inline标签和抽离的CSS chunk中。
• 清理缓存重新构建验证
  配置调整完成后，先删除旧的构建缓存目录，再重新执行生产构建验证，缓存残留是很多偶发构建异常的诱因：

  # 删除缓存
  rm -rf .next node_modules/.cache
  # 重新构建
  npm run build
  # 启动生产环境验证
  npm run start
  

• App Router额外注意项
  如果使用Next.js 13+ App Router，不要同时在pages/_app.tsx和app/layout.tsx中重复引入全局样式，二选一即可，两边同时引入必然造成样式重复。

内容的提问来源于stack exchange，提问作者PianoRockCover