Next.js中styled-components配合MDX热重载className不匹配如何解决

这个className不匹配错误的核心原因是热重载场景下，服务端和客户端的styled-components生成的类名规则没有对齐，再加上next-mdx-remote传递的组件在热重载时会被重新实例化，导致两端类名生成不一致。你可以按以下步骤排查解决：

方案1：开启styled-components的SSR稳定类名配置 #

如果你使用Next.js的SWC编译器（Next.js 12+默认使用），直接在next.config.js中添加如下配置即可：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  compiler: {
    styledComponents: true,
    // 也可以显式配置更细粒度规则，确保开发环境类名稳定
    // styledComponents: {
    //   ssr: true,
    //   displayName: true,
    // },
  },
  reactStrictMode: true,
}

module.exports = nextConfig

如果你使用Babel编译，需要安装babel-plugin-styled-components，并在项目根目录的.babelrc或者babel.config.json中添加配置：

{
  "presets": ["next/babel"],
  "plugins": [["styled-components", { "ssr": true, "displayName": process.env.NODE_ENV !== 'production' }]]
}

配置完成后重启开发服务即可，该配置会强制styled-components在服务端和客户端生成一致的稳定类名，热重载时也不会随意变更类名前缀。

方案2：将自定义styled组件抽离为独立模块 #

不要在调用MDXRemote的页面文件中直接定义styled组件，将所有需要传入MDX的styled组件抽离到单独的公共组件文件中，比如src/components/mdx-components.ts：

// src/components/mdx-components.ts
import styled from 'styled-components';

export const Main = styled.div`
  display: flex;
  background-color: lightgray;
  padding: 12px;
`

// 所有MDX需要用到的自定义组件都在这里导出
export const mdxComponents = {
  Main
}

然后在页面中直接引入这个公共模块的组件：

// index.tsx
import { mdxComponents } from '@/components/mdx-components';

const Home: React.FC<any> = (props) => {
  return (
    <div>
      <MDXRemote {...props.source} components={mdxComponents}/>
    </div>
  )
}

抽离独立模块可以避免页面文件热重载时，styled组件被重复实例化生成新类名的问题。

方案3：开发环境临时禁用SSR渲染MDX内容 #

如果前两个方案还是有问题，可以在开发环境把MDXRemote的渲染放在客户端执行，避开两端类名校验：

import dynamic from 'next/dynamic';

// 关闭SSR的MDXRemote组件，仅在开发环境生效
const MDXRemoteNoSSR = dynamic(
  () => import('next-mdx-remote').then(mod => mod.MDXRemote),
  { ssr: process.env.NODE_ENV === 'production' }
)

const Home: React.FC<any> = (props) => {
  return (
    <div>
      <MDXRemoteNoSSR {...props.source} components={components}/>
    </div>
  )
}

生产环境还是会正常走SSR渲染，不会影响SEO和首屏性能。

内容的提问来源于stack exchange，提问作者b.lyte