🚀 Umi Max 项目从0到1：企业级 React 脚手架实战

🚀 Umi Max 项目从0到1：企业级 React 脚手架实战

👋 为什么选择 Umi Max？

你是否厌倦了从零配置 React 项目？

• 📦 配置繁琐：Webpack、Babel、ESLint... 配置项太多！
• ⏰ 重复劳动：每次新项目都要从头开始
• 🎯 缺少最佳实践：不知道如何组织项目结构

Umi Max 来拯救你！它是蚂蚁集团官方推出的企业级 React 框架，开箱即用，自带最佳实践。

---

🎯 学习目标

通过这篇文章，你将学会：

1. ✅ 使用官方脚手架初始化 Umi Max 项目
2. ✅ 理解 Umi Max 的目录结构
3. ✅ 配置路由和布局
4. ✅ 接入 Ant Design 组件库
5. ✅ 实现一个简单的增删改查功能

---

🛠️ 第一步：初始化项目

环境准备

确保你已经安装了 Node.js（推荐 LTS 版本）：

node -v  # 检查版本，推荐 >= 18.0.0
npm -v   # 检查 npm 版本

创建项目

使用官方脚手架一键创建：

# 使用 create-umi 初始化
npx create-umi@6.5.0 . --template max

执行过程说明：

1. 命令会自动下载脚手架
2. 选择模板为 max（企业级最佳实践）
3. 等待依赖安装完成

---

📂 项目结构解析

项目创建完成后，目录结构如下：

your-project/
├── src/                    # 源代码目录
│   ├── pages/              # 页面组件
│   │   └── index.tsx       # 首页
│   ├── layouts/            # 布局组件
│   ├── components/         # 公共组件
│   ├── services/           # 接口服务
│   ├── models/             # 状态管理
│   ├── utils/              # 工具函数
│   └── app.ts              # 运行时配置
├── .umirc.ts               # Umi 配置文件
├── package.json            # 项目依赖
└── tsconfig.json           # TypeScript 配置

核心文件说明

文件	作用	重要性
.umirc.ts	Umi 主配置文件	⭐⭐⭐
src/app.ts	运行时配置（布局、初始化）	⭐⭐⭐
src/pages/	页面组件存放目录	⭐⭐⭐
src/layouts/	全局布局组件	⭐⭐

---

⚙️ 第二步：配置路由

基础路由配置

在 .umirc.ts 中配置路由：

import { defineConfig } from '@umijs/max';

export default defineConfig({
  // ... 其他配置
  
  routes: [
    {
      path: '/',
      name: '首页',
      component: './pages/index',
    },
    {
      path: '/about',
      name: '关于我们',
      component: './pages/about',
    },
    {
      path: '/users',
      name: '用户管理',
      component: './pages/users',
    },
  ],
});

嵌套路由配置

routes: [
  {
    path: '/dashboard',
    name: '仪表盘',
    component: './layouts/dashboard',
    routes: [
      { path: '/dashboard/overview', component: './pages/dashboard/overview' },
      { path: '/dashboard/analytics', component: './pages/dashboard/analytics' },
    ],
  },
],

---

🎨 第三步：接入 Ant Design

安装依赖

Umi Max 已内置 Ant Design，直接使用即可！

# 如果没有自动安装，可以手动安装
npm install antd

使用组件

// src/pages/index.tsx
import { Button, Card, Space } from 'antd';
import { UserOutlined, MailOutlined } from '@ant-design/icons';

export default function Home() {
  return (
    <div style={{ padding: '24px' }}>
      <Card title="欢迎使用 Umi Max" bordered={false}>
        <Space wrap>
          <Button type="primary" icon={<UserOutlined />}>
            登录
          </Button>
          <Button icon={<MailOutlined />}>
            联系我们
          </Button>
        </Space>
      </Card>
    </div>
  );
}

---

💡 第四步：实现简单 CRUD

创建用户管理页面

// src/pages/users.tsx
import { useState } from 'react';
import { Table, Button, Modal, Form, Input, Space } from 'antd';
import { PlusOutlined, EditOutlined, DeleteOutlined } from '@ant-design/icons';

// 模拟数据
const initialUsers = [
  { id: 1, name: '张三', email: 'zhangsan@example.com' },
  { id: 2, name: '李四', email: 'lisi@example.com' },
];

export default function Users() {
  const [users, setUsers] = useState(initialUsers);
  const [isModalOpen, setIsModalOpen] = useState(false);
  const [editingUser, setEditingUser] = useState<typeof initialUsers[0] | null>(null);
  const [form] = Form.useForm();

  // 添加/编辑用户
  const handleSubmit = (values: { name: string; email: string }) => {
    if (editingUser) {
      // 编辑模式
      setUsers(prev => prev.map(u => 
        u.id === editingUser.id ? { ...u, ...values } : u
      ));
    } else {
      // 添加模式
      setUsers(prev => [...prev, { ...values, id: Date.now() }]);
    }
    setIsModalOpen(false);
    form.resetFields();
    setEditingUser(null);
  };

  // 删除用户
  const handleDelete = (id: number) => {
    setUsers(prev => prev.filter(u => u.id !== id));
  };

  // 打开编辑弹窗
  const handleEdit = (user: typeof initialUsers[0]) => {
    setEditingUser(user);
    form.setFieldsValue(user);
    setIsModalOpen(true);
  };

  const columns = [
    { title: 'ID', dataIndex: 'id' },
    { title: '姓名', dataIndex: 'name' },
    { title: '邮箱', dataIndex: 'email' },
    { 
      title: '操作', 
      render: (_, record) => (
        <Space>
          <Button 
            icon={<EditOutlined />} 
            onClick={() => handleEdit(record)}
          />
          <Button 
            icon={<DeleteOutlined />} 
            danger 
            onClick={() => handleDelete(record.id)}
          />
        </Space>
      )
    },
  ];

  return (
    <div style={{ padding: '24px' }}>
      <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '16px' }}>
        <h2>用户管理</h2>
        <Button 
          type="primary" 
          icon={<PlusOutlined />}
          onClick={() => setIsModalOpen(true)}
        >
          添加用户
        </Button>
      </div>
      
      <Table 
        dataSource={users} 
        columns={columns} 
        rowKey="id" 
        bordered 
      />

      {/* 弹窗表单 */}
      <Modal
        title={editingUser ? '编辑用户' : '添加用户'}
        open={isModalOpen}
        onCancel={() => {
          setIsModalOpen(false);
          setEditingUser(null);
          form.resetFields();
        }}
        footer={null}
      >
        <Form form={form} onFinish={handleSubmit}>
          <Form.Item label="姓名" name="name" rules={[{ required: true }]}>
            <Input placeholder="请输入姓名" />
          </Form.Item>
          <Form.Item label="邮箱" name="email" rules={[{ required: true, type: 'email' }]}>
            <Input placeholder="请输入邮箱" />
          </Form.Item>
          <Form.Item>
            <Button type="primary" htmlType="submit">
              保存
            </Button>
          </Form.Item>
        </Form>
      </Modal>
    </div>
  );
}

---

🔧 常用命令

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产版本
npm run preview

# 代码检查
npm run lint

# 运行测试
npm run test

---

⚡ 实用技巧

1. 配置路径别名

在 tsconfig.json 中配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

使用方式：

import { Button } from '@/components/Button';

2. 环境变量

创建 .env.development 文件：

API_BASE_URL=http://localhost:3000

使用方式：

const apiUrl = process.env.API_BASE_URL;

---

📝 总结

🎉 恭喜你！你已经学会了：

1. ✅ 使用 Umi Max 脚手架初始化项目
2. ✅ 配置路由和布局
3. ✅ 接入 Ant Design 组件库
4. ✅ 实现基础 CRUD 功能
5. ✅ 掌握常用开发命令

---

互动时间

如果这篇文章对你有帮助，请：

• 👍 点赞支持
• ⭐ 收藏备用
• 👀 关注我，获取更多前端教程

有任何问题，欢迎在评论区留言！