Umi.js 4 项目中使用 Ant Design 的正确姿势

问题现象

在使用 Umi.js 4 框架（非 Max 版本）开发项目时，开发者可能会遇到一个典型问题：虽然按照官方文档配置了 Ant Design 插件，页面上的 Ant Design 组件能够正常渲染，但 VSCode 编辑器却持续报出类型错误提示："Cannot find module 'antd' or its corresponding type declarations"。

问题根源

这个问题的根本原因在于项目依赖的不完整性。Umi.js 的插件系统设计理念是将功能模块化，@umijs/plugins 中的 antd 插件主要负责：

1. 自动引入 Ant Design 的样式
2. 提供主题配置能力
3. 集成 babel-plugin-import 实现按需加载

然而，插件本身并不包含 Ant Design 的核心代码。这就像你买了一台游戏主机（Umi.js），配了手柄（antd 插件），但忘记买游戏光盘（antd 库）一样。

解决方案

正确的做法是在项目中显式安装 Ant Design 依赖：

pnpm add antd

或者使用 npm/yarn：

npm install antd
# 或
yarn add antd

深入理解

1. 依赖关系：Umi.js 的 antd 插件和 antd 库是两个独立的包，前者是配置工具，后者是组件库实现

2. TypeScript 支持：安装 antd 后，其自带的类型声明文件会自动被 TypeScript 编译器识别，解决 VSCode 的类型错误

3. 版本兼容性：建议保持 antd 插件和 antd 库版本的同步更新，避免潜在的兼容性问题

最佳实践

1. 初始化项目时就安装所有必要依赖
2. 定期检查并更新依赖版本
3. 使用 pnpm 时，可以添加 --shamefully-hoist 参数提升依赖（针对某些特殊场景）
4. 对于大型项目，考虑按需引入组件以优化打包体积

总结

在 Umi.js 生态中，理解插件与实际库的区别至关重要。antd 插件提供了便捷的配置和优化能力，而 antd 库则是实际功能的提供者。两者配合使用，才能获得完整的开发体验和类型支持。