# Ant Design Pro Cheatsheet
[](https://github.com/ant-design/ant-design-pro) [](https://github.com/ant-design/ant-design-pro) [](https://github.com/ant-design/ant-design-pro/releases) [](https://nodejs.org/) [](https://react.review/repo/ant-design/ant-design-pro)
## 🎉 v6 新特性
- **React 19 + antd 6 + Umi Max 4**：全面升级到最新技术栈，utoopack（Turbopack）构建
- **样式重构**：Less → Tailwind CSS v4 + antd-style + CSS Modules，启用 CSS 变量主题
- **AI 助手页面**：基于 Ant Design X 的聊天界面示例
- **React Query**：从 useRequest 迁移到 @tanstack/react-query
- **Biome**：替代 ESLint + Prettier，统一 lint 和格式化
- **Cloudflare Worker 后端**：演示 API 独立部署，基于 Hono 框架
- **更多**：路由预加载、骨架屏 Loading、D3 地图、Cheatsheet 速查文档、moment → dayjs、Class → 函数式组件
→ [查看完整更新日志](https://github.com/ant-design/ant-design-pro/releases/tag/v6.0.0)
## 快速开始
**创建项目：**
```bash
git clone --depth 1 https://github.com/ant-design/ant-design-pro.git my-project
cd my-project
npm install
```
项目提供两种模式：
- **完整模式**：包含所有示例页面（Dashboard、表单、列表、权限等），适合参考学习
- **精简模式**：仅保留登录页和基础布局，适合从零开发
切换精简模式：
```bash
git add -A && git commit -m "chore: save before simple" # 先提交，以便回退
npm run simple # 删除示例页面和多余依赖
npm install # 更新依赖
```
> 💡 建议先用完整模式熟悉项目结构，再切换精简模式开始开发。
**目录结构：**
```
├── config/ # 配置文件（路由、代理、主题）
│ ├── config.ts # 主配置
│ ├── routes.ts # 路由配置
│ ├── defaultSettings.ts # 布局主题设置
│ └── proxy.ts # 开发代理配置
├── mock/ # Mock 数据
├── src/
│ ├── components/ # 公共组件
│ ├── locales/ # 国际化资源
│ ├── models/ # 全局数据模型
│ ├── services/ # API 服务层
│ ├── utils/ # 工具函数
│ ├── access.ts # 权限定义
│ └── app.tsx # 运行时配置
├── docs/ # 项目文档
└── types/ # 类型声明
```
**常用命令：**
| 命令 | 说明 |
|------|------|
| `npm start` | 启动开发服务器（UMI_ENV=dev，带 Mock） |
| `npm run dev` | 启动开发服务器（UMI_ENV=dev，无 Mock） |
| `npm run start:no-mock` | 无 Mock 启动 |
| `npm run start:pre` | 预发布环境启动 |
| `npm run start:test` | 测试环境启动 |
| `npm run build` | 构建生产产物 |
| `npm run preview` | 预览已构建产物（需先 `npm run build`，端口 8000） |
| `npm run preview:build` | 构建并本地预览（端口 8000） |
| `npm run deploy` | 构建并部署到 GitHub Pages |
| `npm run analyze` | 构建产物体积分析 |
| `npm run lint` | 代码检查（Biome + TypeScript） |
| `npm run biome` | Biome 自动修复 |
| `npm test` | 运行测试 |
| `npm run test:coverage` | 测试覆盖率 |
| `npm run test:update` | 更新测试快照 |
| `npm run tsc` | 类型检查（不生成文件） |
| `npm run i18n-remove` | 移除国际化（locale=zh-CN） |
| `npm run record` | 录制登录场景请求数据 |
| `npm run openapi` | 根据 OpenAPI 生成 API 代码 |
| `npm run simple` | 精简模式（删除示例页面和多余依赖） |
> 💡 `UMI_ENV` 用于切换环境配置，对应 `config/proxy.ts` 中的不同代理规则。
> 💡 `npm run simple` 会删除示例页面（dashboard、form、list 等）和多余依赖（plots 等），替换为精简路由，适合从零开始开发。**建议先提交代码，以便需要时回退。**
**构建工具：** 本项目使用 [utoopack](https://github.com/utooland/utoo)（基于 Turbopack 的新一代打包器）作为默认构建工具，通过 `config/config.ts` 中的 `utoopack` 字段配置。utoopack 兼容 Webpack 配置格式，支持 `module.rules` 配置自定义加载器。
→ 更多内容见 [umi 入门指南](https://umijs.org/docs/guides/getting-started)、[utoo 文档](https://utoo.land)
## 路由与菜单
**路由配置** 位于 `config/routes.ts`：
```ts
// File: config/routes.ts
export default [
{
path: '/welcome',
name: 'welcome', // 对应 menu.welcome 国际化 key
icon: 'home',
component: './Welcome',
},
{
path: '/admin',
name: 'admin',
icon: 'crown',
access: 'canAdmin', // 路由级权限控制
routes: [...],
},
{ path: '/', redirect: '/dashboard/analysis' },
{ component: '404', path: './*' },
];
```
**路由导航：**
```tsx
import { useNavigate, useParams, useLocation } from '@umijs/max';
const navigate = useNavigate();
navigate('/dashboard'); // 跳转
navigate(-1); // 后退
const { id } = useParams(); // 获取动态参数 /user/:id
const location = useLocation(); // 当前路由信息
```
**菜单与权限联动：** 路由配置中 `access` 字段控制菜单可见性，未授权路由不会出现在菜单中。
> 💡 `name` 字段自动映射为 `menu.xxx` 国际化 key，在 `src/locales/` 中配置翻译。
→ 更多内容见 [umi 路由文档](https://umijs.org/docs/guides/routes)、[Umi Max 布局与菜单](https://umijs.org/docs/max/layout-menu)
## 布局
**ProLayout 配置** 位于 `config/defaultSettings.ts`：
```ts
// File: config/defaultSettings.ts
export default {
navTheme: 'light', // 导航主题：light / dark
colorPrimary: '#1890ff', // 主题色
layout: 'mix', // 布局模式：side / top / mix
contentWidth: 'Fluid', // 内容宽度：Fluid / Fixed
fixedHeader: false, // 固定顶部导航
fixSiderbar: true, // 固定侧边栏
colorWeak: false, // 色弱模式
title: 'Ant Design Pro', // 站点标题
logo: 'https://...', // Logo URL
iconfontUrl: '', // 图标字体 URL
token: {}, // ProLayout token，用于细粒度样式定制
};
```
**布局模式：**
- `side` — 左侧导航
- `top` — 顶部导航
- `mix` — 顶部 + 侧边混合导航
**页面容器：**
```tsx
import { PageContainer } from '@ant-design/pro-components';
const Page = () => (
{/* 页面内容 */}
);
```
**自定义区域：** 右上角 `src/components/RightContent`，底部 `src/components/Footer`。
→ 更多内容见 [Umi Max 布局与菜单](https://umijs.org/docs/max/layout-menu)
## 数据流
**useModel — 轻量全局状态：** 在 `src/models/` 下创建文件即自动注册：
```ts
// File: src/models/counter.ts
import { useState } from 'react';
export default function useCounter() {
const [count, setCount] = useState(0);
const increment = () => setCount(c => c + 1);
return { count, increment };
}
```
```tsx
// 任意组件中使用
import { useModel } from '@umijs/max';
const { count, increment } = useModel('counter');
```
**useRequest — 数据请求：**
```tsx
import { useRequest } from '@umijs/max';
const { data, loading, error } = useRequest(getUserInfo);
```
**React Query — 服务端状态管理：**
```tsx
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
// 查询
const { data, isLoading } = useQuery({
queryKey: ['user', id],
queryFn: () => getUser(id),
});
// 变更
const mutation = useMutation({
mutationFn: updateUser,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['user'] });
},
});
```
**初始状态 — getInitialState：** 在 `src/app.tsx` 中定义，全局可访问：
```tsx
// File: src/app.tsx
export async function getInitialState() {
const currentUser = await fetchUserInfo();
return { currentUser };
}
// 组件中使用
import { useModel } from '@umijs/max';
const { initialState } = useModel('@@initialState');
```
> 💡 `getInitialState` 在应用启动时执行一次，适合获取全局信息（如用户身份、权限）。
→ 更多内容见 [Umi Max 数据流](https://umijs.org/docs/max/data-flow)
## 请求
**请求配置** 位于 `src/app.tsx`：
```ts
// File: src/app.tsx
export const request: RequestConfig = {
baseURL: 'https://api.example.com',
timeout: 10000,
requestInterceptors: [], // 请求拦截器
responseInterceptors: [], // 响应拦截器
};
```
**错误处理** 位于 `src/requestErrorConfig.ts`，可自定义错误码映射和提示逻辑。
**使用请求：**
```tsx
import { request } from '@umijs/max';
// GET
const data = await request('/api/users', { params: { page: 1 } });
// POST
await request('/api/users', { method: 'POST', data: { name: 'test' } });
```
**OpenAPI 代码生成：**
```bash
npm run openapi
```
根据 `config/oneapi.json` 自动生成 `src/services/` 下的 API 调用代码。
> 💡 生成后的代码直接用 `import { request } from '@umijs/max'` 发起请求，无需手动封装。
→ 更多内容见 [Umi Max 请求](https://umijs.org/docs/max/request)
## 权限
**定义权限** 在 `src/access.ts`：
```ts
// File: src/access.ts
export default function access(initialState: { currentUser?: API.CurrentUser }) {
const { currentUser } = initialState;
return {
canAdmin: currentUser?.access === 'admin',
canUser: !!currentUser,
};
}
```
**路由级权限：** 在路由配置中添加 `access` 字段：
```ts
{ path: '/admin', access: 'canAdmin' }
```
**组件级权限：**
```tsx
import { Access, useAccess } from '@umijs/max';
// 声明式
// 命令式
const access = useAccess();
if (access.canAdmin) { /* ... */ }
```
→ 更多内容见 [Umi Max 权限](https://umijs.org/docs/max/access)
## 国际化
**配置** 在 `config/config.ts`：
```ts
locale: {
default: 'zh-CN',
antd: true, // 同步 antd 组件语言
baseNavigator: true, // 跟随浏览器语言
},
```
**文件结构：**
```
src/locales/
├── zh-CN.ts # 中文入口
├── zh-CN/
│ ├── menu.ts # 菜单翻译
│ ├── pages.ts # 页面翻译
│ └── ...
├── en-US.ts # 英文入口
└── en-US/
└── ...
```
**使用方式：**
```tsx
import { useIntl, FormattedMessage } from '@umijs/max';
// Hook 方式
const intl = useIntl();
intl.formatMessage({ id: 'menu.welcome' });
// 组件方式
```
**切换语言：**
```tsx
import { setLocale } from '@umijs/max';
setLocale('en-US', false); // false = 不刷新页面
```
→ 更多内容见 [Umi Max 国际化](https://umijs.org/docs/max/i18n)
## 样式
**CSS Modules：** 文件命名为 `*.module.less` 或 `*.module.css`：
```css
/* example.module.less */
.container { padding: 24px; }
.title { font-size: 16px; }
```
```tsx
import styles from './example.module.less';
```
**antd-style（CSS-in-JS）：**
```tsx
import { createStyles } from 'antd-style';
const useStyles = createStyles(({ token, css }) => ({
card: css`
background: ${token.colorBgContainer};
border-radius: ${token.borderRadiusLG}px;
`,
}));
const { styles } = useStyles();
```
**Tailwind CSS（v4）：** 直接在 className 中使用：
```tsx
```
**动态主题：** 在 `config/config.ts` 的 `antd` 配置中设置：
```ts
antd: {
configProvider: {
theme: {
token: {
colorPrimary: '#1890ff',
borderRadius: 6,
},
},
},
},
```
开发环境可通过右下角 SettingDrawer 实时切换主题。
> 💡 三种样式方案可以共存：Tailwind 适合布局、CSS Modules 适合组件样式、antd-style 适合需要消费主题 token 的场景。
→ 更多内容见 [umi 样式文档](https://umijs.org/docs/guides/styling)、[Umi Max antd 动态主题](https://umijs.org/docs/max/antd#动态切换全局配置)
## 测试 & 调试
**Jest 测试：**
```bash
npm test # 运行所有测试
npm run test:coverage # 带覆盖率报告
npm run test:update # 更新快照
```
测试文件放在对应组件目录下，命名为 `*.test.ts(x)`。
**Mock 数据：** 在 `mock/` 目录下创建文件：
```ts
// File: mock/user.ts
export default {
'GET /api/currentUser': { name: 'Serati Ma', access: 'admin' },
'POST /api/login': (req, res) => { res.end('ok'); },
};
```
Umi 自动注册 mock，开发模式下生效。
**代理配置** 位于 `config/proxy.ts`：
```ts
// File: config/proxy.ts
export default {
dev: {
'/api/': {
target: 'http://localhost:8080',
changeOrigin: true,
},
},
};
```
> 💡 用 `MOCK=none` 启动可跳过 Mock，直接代理到后端：`npm run start:no-mock`。
→ 更多内容见 [umi 测试](https://umijs.org/docs/guides/test)、[umi Mock](https://umijs.org/docs/guides/mock)
## FAQ
**Q: 如何关闭 Mock？**
`npm run start:no-mock` 或 `cross-env MOCK=none max dev`
**Q: 如何修改主题色？**
修改 `config/defaultSettings.ts` 的 `colorPrimary`，开发时可用 SettingDrawer 实时调整。
**Q: 如何添加新页面？**
1. 在 `src/pages/` 下创建组件 2. 在 `config/routes.ts` 添加路由 3. 在 `src/locales/` 添加菜单翻译（如需）
**Q: 如何添加全局状态？**
在 `src/models/` 下创建文件，导出自定义 Hook，组件中通过 `useModel('文件名')` 使用。
**Q: 如何升级项目？**
先将 pro-upgrade skill 安装到项目中：
```bash
npx skills add ant-design/ant-design-pro
```
然后在项目根目录用 Claude Code 运行 `/pro-upgrade`，AI 会自动对比最新模板并辅助完成升级（依赖、配置、代码模式等），遇到冲突时会保守处理并询问确认。如使用其他 AI 助手，可将 `.claude/skills/pro-upgrade/SKILL.md` 中的内容提供给它。
**Q: 如何部署？**
`npm run build` 生成 `dist/` 目录，部署到任意静态服务器。配置 `publicPath` 处理非根目录部署。`npm run deploy` 会自动构建并发布到 GitHub Pages（推送到 gh-pages 分支）。
**Q: 如何使用 OpenAPI 代码生成？**
1. 在 `config/config.ts` 配置 `openAPI` 2. 运行 `npm run openapi` 3. 自动生成 `src/services/` 下的代码
→ 更多内容见 [umi FAQ](https://umijs.org/docs/introduce/faq)
## 常见任务
### 添加新页面
```bash
# 1. 创建页面组件
# 文件路径：src/pages/my-page/index.tsx
# 2. 在路由配置中注册
# 文件路径：config/routes.ts
# { path: '/my-page', name: 'myPage', icon: 'file', component: './my-page' }
# 3. 添加国际化翻译（如需菜单显示）
# 文件路径：src/locales/zh-CN/menu.ts → menu.myPage: '我的页面'
# 文件路径：src/locales/en-US/menu.ts → menu.myPage: 'My Page'
```
### 添加全局状态
```bash
# 1. 创建 model 文件（文件名即 model key）
# 文件路径：src/models/myModel.ts
# 导出自定义 Hook：export default function useMyModel() { ... }
# 2. 在组件中使用
# import { useModel } from '@umijs/max';
# const { data } = useModel('myModel'); // 'myModel' 对应文件名
```
### 添加 Mock 接口
```bash
# 全局 Mock：mock/api.ts（匹配所有环境）
# 页面级 Mock：src/pages/my-page/_mock.ts（Umi 自动发现）
# Mock 格式：
# export default { 'GET /api/my-data': { data: [] } }
```
### 生成 API 服务代码
```bash
# 1. 编辑 OpenAPI 配置：config/oneapi.json
# 2. 运行生成命令（覆盖 src/services/ant-design-pro/）
npm run openapi
# 3. 不要手动编辑生成代码，改 oneapi.json 重新生成
```
### 切换到精简模式
```bash
git add -A && git commit -m "chore: save before simple" # 必须先提交
npm run simple # 不可逆操作
npm install # 更新依赖
```
## AI Skills（Claude Code）
本项目内置两个 [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills)（位于 `.claude/skills/`）：
### `/pro-upgrade` — 项目升级助手
自动升级到最新 Ant Design Pro 版本。对比最新模板差异，合并框架变更并保留业务代码。
```bash
# 在 Claude Code 中直接运行：
/pro-upgrade
```
执行流程：
1. 克隆最新 Pro 模板
2. 将文件分类为框架文件和业务文件
3. 合并依赖更新、配置变更和代码模式迁移
4. 运行 `npx antd lint` 检查 antd 相关问题
5. 通过 `npm run lint && npm run build` 验证
### `/antd` — Ant Design CLI 助手
查询 antd 组件 API、调试问题、检查废弃用法、辅助版本迁移 — 基于 `@ant-design/cli`，离线元数据，无需网络。
```bash
# 在 Claude Code 中直接运行：
/antd
```
常用命令：
- `npx antd info ` — props、类型、版本信息
- `npx antd demo ` — 可运行的代码示例
- `npx antd lint ./src` — 检查废弃或有问题的用法
- `npx antd migrate ` — 版本迁移清单
- `npx antd doc ` — 完整组件文档
### 安装与更新
> 💡 如果你的项目是从本仓库克隆的，这些 skill 已经内置，无需额外安装。
获取最新 skill 定义（或将其添加到已有项目）：
```bash
npx skills add ant-design/ant-design-pro
```
如使用其他 AI 助手（Cursor 等），可将 `.claude/skills/pro-upgrade/SKILL.md` 或 `.claude/skills/antd/SKILL.md` 的内容提供给它。
## 注意事项
- **`src/services/ant-design-pro/`** 为自动生成代码，禁止手动编辑。修改 `config/oneapi.json` 后执行 `npm run openapi` 重新生成
- **`npm run simple` 不可逆**：会删除示例页面和多余依赖，执行前务必提交代码
- **`.umi` 临时目录**：`src/.umi` 由 Umi 自动生成，遇到异常可删除后重启开发服务器
- **Biome 代替 ESLint**：项目使用 Biome 进行 lint 和格式化，不要安装 ESLint 或 Prettier 插件
- **Commit 规范**：必须遵循 [Conventional Commits](https://www.conventionalcommits.org/)，如 `feat:`, `fix:`, `chore:` 等
- **`npx antd lint ./src`**：提交前必须零错误零警告
- **Mock 优先级**：`mock/` 目录为全局 Mock，`src/pages/**/_mock.ts` 为页面级 Mock，两者都会被 Umi 自动注册
- **样式优先级**：Tailwind（布局）> antd-style（主题 token）> CSS Modules（组件样式）> Less（仅遗留全局样式）
- **路径别名**：`@/*` → `./src/*`，`@@/*` → `./src/.umi/*`