Next.js集成Ant Design后按钮初始加载无样式、需刷新才生效的原因及解决方法

嘿，我之前也碰到过一模一样的问题，这其实是Next.js SSR/SSG模式下，Ant Design的CSS-in-JS样式提取机制和局部主题配置冲突导致的，咱们一步步拆解解决：

问题根源 #

你在组件内部嵌套了ConfigProvider来定制按钮主题，但服务端渲染时，这部分局部主题的样式没有被正确捕获并注入到初始HTML里。页面首次加载时，客户端 hydration 阶段也没能同步生成这部分样式，所以按钮会显示无样式状态；而刷新页面后，客户端重新完整渲染，CSS-in-JS才会生成并注入对应的样式，按钮就正常显示了。

解决方法 #

根据你的代码，我推荐几个从优到次的解决方案：

方案1：统一全局主题配置（最推荐）

把组件内的局部主题配置合并到全局的themeConfig.ts中，避免在组件内嵌套ConfigProvider——这不仅能解决样式缺失问题，还能减少组件渲染开销：

1. 修改你的theme/themeConfig.ts，把按钮的主题配置加进去：

// theme/themeConfig.ts
export default {
  token: {
    colorPrimary: "#444690",
    colorTextLightSolid: "#ffffff",
    borderRadius: 4,
  },
  components: {
    Button: {
      fontWeight: "medium",
    },
  },
};

2. 组件里直接使用按钮，删掉嵌套的ConfigProvider：

<Form.Item
  wrapperCol={{ span: 24, offset: 0 }}
  className=" text-center"
>
  <Button type="primary">Register</Button>
</Form.Item>

这样服务端渲染时，全局主题的所有样式都会被一次性提取并注入到初始HTML中，初始加载时按钮样式就正常了。

方案2：优化_document.tsx的样式提取逻辑

如果你必须保留局部ConfigProvider，可以检查并确保_document.tsx的样式提取逻辑能覆盖所有嵌套的主题配置：
你的_document.tsx已经有基础的StyleProvider和extractStyle配置，但可以确认以下两点：

• 确保StyleProvider包裹了整个App（你的代码里enhanceApp已经做了这一步，没问题）
• 确认extractStyle的第二个参数为true（你已经设置了，这个参数会提取所有静态主题样式）

如果还是有问题，可以尝试清空.next缓存后重新构建：

rm -rf .next
npm run build
npm run start

方案3：强制客户端渲染按钮（临时方案）

如果以上方法都不适用，你可以让按钮组件只在客户端渲染，避开SSR的样式提取问题：

import dynamic from 'next/dynamic';

// 动态导入按钮组件，禁用SSR
const ClientButton = dynamic(() => import('antd/es/button'), { ssr: false });

// 使用时替换原Button组件
<Form.Item
  wrapperCol={{ span: 24, offset: 0 }}
  className=" text-center"
>
  <ConfigProvider
    theme={{
      token: {
        colorPrimary: "#444690",
        colorTextLightSolid: "#ffffff",
        borderRadius: 4,
      },
      components: {
        Button: {
          fontWeight: "medium",
        },
      },
    }}
  >
    <ClientButton type="primary">Register</ClientButton>
  </ConfigProvider>
</Form.Item>

不过这个方法会失去SSR的优势，只建议作为临时应急方案。

验证 #

修改完成后，重新执行构建和启动命令：

npm run build
npm run start

现在打开页面，按钮应该在初始加载时就显示正确的样式了，不需要再刷新。

备注：内容来源于stack exchange，提问作者Kishore Sundharam