Ant Design服务端渲染教程：Next.js集成实现方案
项目地址: https://gitcode.com/gh_mirrors/ant/ant-design Ant Design（简称antd）是企业级UI设计语言和React组件库，Next.js则是流行的React服务端同构框架。本文将详细介绍如何在Next.js项目中集成Ant Design并实现服务端渲染（SSR），解决首屏样式缺失和页面闪动问题。
安装和初始化
首先需要创建Next.js项目。确保已安装yarn、pnpm或bun，然后执行以下命令：
npx create-next-app antd-demo
cd antd-demo
npm run dev
访问http://localhost:3000/，看到NEXT的logo即表示项目初始化成功。接下来安装Ant Design：
npm install antd --save
基础使用与样式问题
修改src/app/page.tsx，引入Ant Design的按钮组件：
import React from 'react';
import { Button } from 'antd';
const Home = () => (
<div className="App">
<Button type="primary">Button</Button>
</div>
);
export default Home;
此时页面上会显示Ant Design的蓝色按钮，但细心的开发者会发现首屏加载时组件可能没有样式。这是因为Next.js的服务端渲染模式下，需要特殊处理Ant Design的样式。
使用App Router集成方案
如果项目使用Next.js的App Router，推荐使用@ant-design/nextjs-registry来处理样式：
- 安装依赖：
npm install @ant-design/nextjs-registry --save
- 修改
app/layout.tsx：
import React from 'react';
import { AntdRegistry } from '@ant-design/nextjs-registry';
const RootLayout = ({ children }: React.PropsWithChildren) => (
<html lang="en">
<body>
<AntdRegistry>{children}</AntdRegistry>
</body>
</html>
);
export default RootLayout;
这种方式会自动处理样式的服务端渲染，避免页面闪动。官方文档：docs/react/use-with-next.zh-CN.md
使用Pages Router集成方案
如果项目使用Pages Router，则需要通过@ant-design/cssinjs来处理样式：
- 安装依赖：
npm install @ant-design/cssinjs --save
注意：安装时必须确保
@ant-design/cssinjs的版本与antd依赖的版本一致，可通过npm ls @ant-design/cssinjs命令查看本地版本。
- 改写
pages/_document.tsx：
import React from 'react';
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import Document, { Head, Html, Main, NextScript } from 'next/document';
import type { DocumentContext } from 'next/document';
const MyDocument = () => (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
MyDocument.getInitialProps = async (ctx: DocumentContext) => {
const cache = createCache();
const originalRenderPage = ctx.renderPage;
ctx.renderPage = () =>
originalRenderPage({
enhanceApp: (App) => (props) => (
<StyleProvider cache={cache}>
<App {...props} />
</StyleProvider>
),
});
const initialProps = await Document.getInitialProps(ctx);
const style = extractStyle(cache, true);
return {
...initialProps,
styles: (
<>
{initialProps.styles}
<style dangerouslySetInnerHTML={{ __html: style }} />
</>
),
};
};
export default MyDocument;
自定义主题配置
Ant Design支持自定义主题，通过修改主题变量可以轻松定制组件样式。创建theme/themeConfig.ts：
import type { ThemeConfig } from 'antd';
const theme: ThemeConfig = {
token: {
fontSize: 16,
colorPrimary: '#52c41a',
},
};
export default theme;
在pages/_app.tsx中应用主题：
import React from 'react';
import { ConfigProvider } from 'antd';
import type { AppProps } from 'next/app';
import theme from './theme/themeConfig';
const App = ({ Component, pageProps }: AppProps) => (
<ConfigProvider theme={theme}>
<Component {...pageProps} />
</ConfigProvider>
);
export default App;
完整示例与最佳实践
完成上述配置后，就可以在页面中正常使用Ant Design组件了。例如，在pages/index.tsx中：
import React from 'react';
import { Button, Card, Space } from 'antd';
const Home = () => (
<div className="App" style={{ padding: '20px' }}>
<Card title="Ant Design SSR示例" bordered={true}>
<Space>
<Button type="primary">主要按钮</Button>
<Button>默认按钮</Button>
<Button type="dashed">虚线按钮</Button>
<Button type="text">文本按钮</Button>
<Button type="link">链接按钮</Button>
</Space>
</Card>
</div>
);
export default Home;
更多详细示例可参考：
- App Router示例：with-nextjs-app-router-inline-style
- Pages Router示例：with-nextjs-inline-style
常见问题与解决方案
-
样式闪烁：确保正确配置了
AntdRegistry或StyleProvider，这是解决SSR样式问题的关键。 -
版本不一致：
@ant-design/cssinjs的版本必须与antd保持一致，否则可能出现React实例冲突。 -
子组件导入：在App Router中，不支持直接使用
<Select.Option />这样的子组件，需要从路径单独引入。 -
自定义主题不生效：检查
ConfigProvider是否正确包裹了应用根组件，以及主题配置是否符合Ant Design的主题规范。
通过以上步骤，你已经成功在Next.js项目中集成了Ant Design并实现了服务端渲染。这种方案既能充分利用Next.js的服务端渲染能力，又能享受Ant Design丰富的组件库，为企业级应用开发提供强有力的支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
