Ant Design 在 Next.js 中编译失败的解决方案

在使用 Ant Design 5.23.4 与 Next.js 15.1.6 结合开发时，开发者可能会遇到编译失败的问题。控制台报错显示无法找到 rc-util 等依赖模块，特别是当使用 yarn 或 npm 作为包管理器时。本文将深入分析问题原因并提供完整的解决方案。

问题现象

当项目同时使用 Ant Design 和 Next.js 框架时，构建过程中会出现模块找不到的错误。错误信息通常指向 rc-util 等内部依赖的路径问题，例如：

Error: Cannot find module 'rc-util/es/utils/get'

根本原因

这个问题主要由以下几个因素共同导致：

1. Next.js 的特殊处理机制：Next.js 对 Ant Design 做了特殊的加速 hook，导致通过路径直接引入非 TypeScript 定义的代码时会出现兼容性问题。

2. 路径引用方式不当：项目中直接使用了 /es 或 /lib 路径引用 Ant Design 的子模块，这种引用方式在 Next.js 环境下不稳定。

3. 包管理器差异：不同包管理器（yarn、npm、pnpm）对依赖的处理方式不同，导致问题表现不一致。

完整解决方案

1. 修正导入路径

将所有从 Ant Design 直接引用 /es 或 /lib 子模块的代码改为从主入口导入：

// 错误写法
import zhCN from 'antd/es/locale/zh_CN';
import { StyleProvider } from '@ant-design/cssinjs/lib';

// 正确写法
import zhCN from 'antd/locale/zh_CN';
import { StyleProvider } from '@ant-design/cssinjs';

2. 清理构建缓存

删除项目中的以下目录和文件：

• .next 目录
• node_modules 目录
• package-lock.json 或 yarn.lock

然后重新安装依赖：

npm install
# 或
yarn install

3. 类型导入规范

对于仅用作类型的导入，使用 TypeScript 的类型导入语法：

// 错误写法
import { ThemeConfig } from "antd/es/config-provider/context";

// 正确写法
import type { ThemeConfig } from "antd/es/config-provider/context";

4. 依赖管理优化

避免在项目中直接声明 Ant Design 的间接依赖（如 rc-util），这些应该由 Ant Design 自动管理：

{
  "dependencies": {
    // 移除这些行
    "rc-util": "^5.44.3",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

最佳实践建议

1. 统一包管理器：建议团队统一使用 pnpm，它在处理依赖关系方面表现更为稳定。

2. 版本兼容性：确保使用的 Ant Design 版本与 React 版本兼容，特别是使用 React 19 时。

3. 构建环境检查：在 CI/CD 流程中加入构建环境检查步骤，确保构建环境干净。

4. 类型安全：全面使用 TypeScript 的类型导入语法，避免运行时问题。

通过以上措施，可以彻底解决 Ant Design 在 Next.js 中的编译问题，并建立起更健壮的前端工程化实践。