Next.js 13+React 18搭配Styled Components出现异常问题求助

遇到的问题 #

• 样式继承偶现冲突：通过如下方式扩展样式时，生产构建启动后偶尔会出现样式错误（比如示例里Card本该显示绿色，结果还是红色）

const CardWrapper = styled.div`
  color: red
`
const Card = styled(CardWrapper)`
  color: green
`

• Dev 环境类名不符合预期：开发模式下得到的是压缩后的短类名，但文档说明应该显示带组件名的完整类名
• 类名不匹配警告：时不时弹出Warning: Prop className did not match. Server: "sc-fSRBKe btBFdf" Client: "sc-bCfvAP haamXM"的提示

当前配置情况 #

Next.js 配置文件：

const nextConfig = {
  images: {
    domains: ['images.ctfassets.net'],
  },
  compiler: {
    // ssr and displayName are configured by default
    styledComponents: true,
  },

  output: 'standalone',

  async redirects() {
    ...
  }
}
module.exports = nextConfig

另外项目还保留了.babelrc.js文件，用来适配内部包。

解决方法 #

1. 消除 Babel 和 Next.js 内置编译器的冲突 #

Next.js 13+ 自带的编译器已经原生支持 Styled Components，继续保留.babelrc.js中的 Styled Components 插件配置，会导致服务端和客户端编译逻辑不一致，这是类名不匹配、样式冲突的核心原因。

• 修改.babelrc.js，移除其中与 Styled Components 相关的插件配置，仅保留内部包所需的必要配置
• 显式配置 Next.js 编译器的styledComponents参数（虽然默认已开启，显式配置可避免环境差异）：

compiler: {
  styledComponents: {
    displayName: true, // 确保生成带组件名的完整类名
    ssr: true, // 保证服务端渲染样式同步
  },
},

2. 修复 Dev 环境类名压缩问题 #

完成上述displayName: true的配置后，Dev 模式下会自动生成带组件标识的完整类名。如果问题仍存在，检查是否有自定义 Webpack 配置覆盖了该设置。

3. 解决样式继承的偶发冲突 #

样式继承出现异常，是因为服务端与客户端生成的类名哈希或顺序不一致，需注意：

• 组件文件避免使用动态导入打乱编译顺序
• 服务端渲染的组件中不要使用异步加载样式的逻辑
• 确保所有 Styled Components 在服务端和客户端的编译逻辑完全同步

额外提醒 #

• 将 Styled Components 升级到最新稳定版，保证与 React 18、Next.js 13 版本兼容
• 检查next.config.js中是否有自定义 Webpack 配置干扰了 Styled Components 的编译流程
• 如果内部包必须保留 Babel 配置，需保证其中的 Styled Components 插件版本与项目依赖的版本完全一致

内容的提问来源于stack exchange，提问作者Alexander Freyr Sveinsson