如何在Next.js服务端渲染项目中使用Ant Design？

核心原因 #

Ant Design的所有组件本质都是客户端组件，依赖React的客户端API（比如状态管理、DOM操作），而Next.js的服务端组件（Server Components）禁止使用这类客户端特性——哪怕是<Row>、<Col>这类基础布局组件也不例外，直接在服务端组件里引入就会触发限制。

解决方案 #

1. 给使用Ant Design的文件加客户端标记 #

在用到Ant Design组件的文件顶部添加'use client'指令，明确告诉Next.js这个文件属于客户端组件，就能正常使用所有Ant Design组件：

'use client';

import { Row, Col, Button } from 'antd';

export default function MyPage() {
  return (
    <Row gutter={16}>
      <Col span={12}>
        <Button type="primary">测试按钮</Button>
      </Col>
    </Row>
  );
}

2. 拆分服务端逻辑与客户端UI #

如果页面需要服务端数据获取，建议把数据请求等服务端逻辑放在单独的服务端组件里，再把数据传递给包含Ant Design组件的客户端组件：

// 服务端组件：仅负责获取数据
export default async function Page() {
  const listData = await fetchServerData();
  return <AntdTable data={listData} />;
}

// 客户端组件：仅负责渲染Ant Design UI
'use client';

import { Table } from 'antd';

export function AntdTable({ data }) {
  const columns = [
    { title: '名称', dataIndex: 'name' },
    { title: '数量', dataIndex: 'count' }
  ];
  return <Table dataSource={data} columns={columns} />;
}

3. 绝对不要在服务端组件里直接导入Ant Design #

不管是组件本身还是类型定义，只要涉及Ant Design的代码，都必须放在带有'use client'标记的文件里，避免服务端组件触发客户端API限制。

补充说明 #

目前Ant Design官方还未针对Next.js服务端组件做完全适配，所有组件都需要在客户端环境运行。这种方式并非“无法服务端渲染”，而是让Ant Design的UI渲染在客户端正常执行，页面的服务端逻辑（比如数据获取）依然可以正常运行，不影响整体的服务端渲染流程。

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