基于 UmiJS 与 Ant Design Pro 搭建企业级中后台系统

搭建企业级中后台系统，核心目标是建立一套具备稳定约束、高度复用且支持多人高效协作的前端工程底座。Ant Design Pro 结合底层 UmiJS 框架，提供了从路由调度、数据请求、权限鉴权到高质量业务组件（ProComponents）的全链路方案，避免了团队自研脚手架时容易陷入的基础设施割裂与维护成本。本文将完整梳理从中后台工程初始化、配置分层、权限与路由设计、统一网络请求到生产部署交付的实施全过程，提供可直接验证并落地的工程范式。

一、工程初始化与基准目录建立

中后台系统对长期稳定性和依赖可靠性要求极高。在开始编码前，必须锁定 Node.js 运行时版本并统一团队的包管理工具。当前推荐使用 Node.js 18 LTS 或 Node.js 20 LTS 作为运行底座，包管理器推荐使用 pnpm。与传统的 npm 或 yarn 相比，pnpm 依赖符号链接（symlink）机制建立扁平化的虚拟存储树，能够彻底阻断“幽灵依赖”（Phantom Dependencies）被隐式引用的隐患，保证团队各成员机器上构建产物的一致性。

1. 搭建运行脚手架

在终端的工作目录下，使用官方提供的创建命令生成基于 Umi 4 的 Ant Design Pro 项目骨架。执行命令如下：

# 创建新项目目录并进入
mkdir pro-admin-platform && cd pro-admin-platform

# 使用 pnpm 调用官方脚手架
pnpm create umi

在脚手架交互提示中，根据中后台工程的实际需求选择对应项：

• Select the boilerplate type: 选择 Ant Design Pro
• Select language: 必须选择 TypeScript，强类型约束是大型中后台多人协作的基石
• Select package manager: 选择 pnpm
• Select template version: 初次搭建或业务定制要求较高时，建议选择 simple（精简模版），避免全量模版中附带的几十个演示页面增加后续清理成本

2. 工程结构瘦身与目录拓扑规范

脚手架初始化完成后，需要对工程进行规范化瘦身。默认模版通常包含演示用的 Mock 数据和业务范例页面，在对接真实生产服务端前，需将无关文件移除。清理后的推荐目录结构如下：

pro-admin-platform/
├── config/                  # 工程与编译配置目录
│   ├── config.ts            # 主配置文件（插件、主题、路由引入）
│   ├── routes.ts            # 声明式静态路由树
│   ├── proxy.ts             # 本地开发反向代理规则
│   └── defaultSettings.ts   # ProLayout 导航与品牌配色
├── src/
│   ├── access.ts            # 权限判定主函数（基于 InitialState）
│   ├── app.tsx              # 运行时生命周期（getInitialState / layout 钩子）
│   ├── requestConfig.ts     # 统一请求拦截与错误网关配置
│   ├── assets/              # 本地静态图片与字体资源
│   ├── components/          # 全局通用业务组件（业务搜索框、通用弹窗等）
│   ├── pages/               # 页面级领域组件
│   │   ├── User/            # 用户认证（登录/找回密码）
│   │   ├── Dashboard/       # 仪表盘与监控概览
│   │   └── System/          # 系统管理（用户管理、角色分配、操作审计）
│   ├── services/            # 领域接口与 TypeScript DTO 类型声明
│   └── utils/               # 无状态纯函数工具集
├── package.json             # 依赖与 scripts 指令
├── tsconfig.json            # TypeScript 编译配置
└── pnpm-lock.yaml           # 依赖锁定树（严格纳入版本控制）

3. 本地启动与基线检验

执行依赖安装并启动开发服务器：

# 安装项目完整依赖
pnpm install

# 启动本地开发服务
pnpm dev

终端控制台将给出本地监听端口与编译状态输出：

打开浏览器访问 http://localhost:8000。若页面能够正常渲染出左右分栏的 ProLayout 框架、面包屑及空白工作区，即代表基础环境和工程骨架已构建就绪。

二、核心配置分层与运行时架构

UmiJS 采用“配置时”与“运行时”双层分离的设计理念。理解这两层的权责划分，是灵活掌控 Ant Design Pro 系统的关键。

1. 配置时分层（config/ 目录）

config/config.ts 属于 Node.js 编译环境运行的配置。在该文件中，我们将路由配置、主题插件、多语言、本地代理等能力独立拆分引入，保持主配置的整洁与可读性：

// config/config.ts 核心配置示例
import { defineConfig } from '@umijs/max';
import routes from './routes';
import proxy from './proxy';

export default defineConfig({
  antd: {},
  access: {},
  model: {},
  initialState: {},
  request: {},
  layout: {
    title: '企业资产中枢',
    locale: true,
  },
  routes,
  proxy: proxy['dev'],
  fastRefresh: true,
  npmClient: 'pnpm',
});

为了规避跨域并打通本地开发与测试联调环境，在 config/proxy.ts 中配置反向代理规则。如下配置将本地前端发送的 /api 接口统一转发至后端测试网关，并覆写 Origin 请求头：

// config/proxy.ts
export default {
  dev: {
    '/api/': {
      target: 'https://test-gateway.internal.company.com',
      changeOrigin: true,
      pathRewrite: { '^/api': '/api/v1' },
    },
  },
};

2. 运行时生命周期（src/app.tsx）

src/app.tsx 运行在用户浏览器上下文中，负责控制页面的初始化流程与布局挂载。其中最重要的两个导出是 getInitialState 与 layout。

// src/app.tsx 核心运行时实现
import type { RunTimeLayoutConfig } from '@umijs/max';
import { history } from '@umijs/max';
import { queryCurrentUser } from '@/services/auth';

// 1. 全局初始化状态加载：在所有页面渲染前执行
export async function getInitialState(): Promise<{
  currentUser?: API.CurrentUser;
  permissions?: string[];
  fetchUserInfo?: () => Promise<API.CurrentUser | undefined>;
}> {
  const fetchUserInfo = async () => {
    try {
      const response = await queryCurrentUser();
      return response.data;
    } catch (error) {
      // 登录态失效时重定向至登录页
      history.push('/user/login');
      return undefined;
    }
  };

  // 处于非登录页时，主动获取当前登录人信息与权限
  const { location } = history;
  if (location.pathname !== '/user/login') {
    const currentUser = await fetchUserInfo();
    return {
      fetchUserInfo,
      currentUser,
      permissions: currentUser?.permissions || [],
    };
  }
  return { fetchUserInfo };
}

// 2. 运行时 Layout 布局定制
export const layout: RunTimeLayoutConfig = ({ initialState }) => {
  return {
    logo: 'https://gw.alipayobjects.com/zos/rmsportal/KDpgvguMpGfqaHPjicRK.svg',
    menu: {
      locale: false,
    },
    logout: () => {
      localStorage.removeItem('token');
      history.push('/user/login');
    },
    onPageChange: () => {
      // 页面路由切换时的鉴权前置守卫
      const { location } = history;
      if (!initialState?.currentUser && location.pathname !== '/user/login') {
        history.push('/user/login');
      }
    },
  };
};

三、路由设计与企业级 RBAC 权限控制

企业级中后台的核心能力之一是 RBAC（Role-Based Access Control，基于角色的访问控制）。在前端体系中，权限控制包含两层含义：路由层访问守卫与UI 元素级细粒度显示控制。

1. 权限映射定义（src/access.ts）

Umi 的 plugin-access 插件会读取 src/access.ts 导出的函数。该函数接收 getInitialState 返回的对象，并产出一个布尔值键值表：

// src/access.ts
export default function access(initialState: { currentUser?: API.CurrentUser; permissions?: string[] } | undefined) {
  const { currentUser, permissions = [] } = initialState ?? {};
  const roles = currentUser?.roles || [];

  return {
    // 超级管理员角色拥有全局权限
    canAdmin: roles.includes('ADMIN'),
    // 审计人员权限
    canAudit: roles.includes('AUDITOR') || roles.includes('ADMIN'),
    // 基于原子权限编码校验
    canUserCreate: permissions.includes('sys:user:create'),
    canUserDelete: permissions.includes('sys:user:delete'),
    canUserExport: permissions.includes('sys:user:export'),
  };
}

2. 静态路由树配置（config/routes.ts）

在静态路由树中，通过在路由对象上声明 access 属性，直接与 src/access.ts 中的属性进行绑定。若当前登录用户不具备该权限，ProLayout 会自动在左侧菜单中隐藏该项；若用户通过手动输入 URL 强行访问，Umi 路由层会自动阻断并呈现 403 页面。

// config/routes.ts
export default [
  {
    path: '/user',
    layout: false,
    routes: [
      { name: '登录', path: '/user/login', component: './User/Login' },
    ],
  },
  {
    path: '/welcome',
    name: '工作台',
    icon: 'dashboard',
    component: './Welcome',
  },
  {
    path: '/system',
    name: '系统管理',
    icon: 'setting',
    access: 'canAdmin', // 仅管理员可见
    routes: [
      {
        path: '/system/user',
        name: '用户管理',
        component: './System/UserList',
      },
      {
        path: '/system/audit',
        name: '安全审计',
        access: 'canAudit', // 需要审计员权限
        component: './System/AuditLogs',
      },
    ],
  },
  {
    path: '/',
    redirect: '/welcome',
  },
  {
    path: '*',
    layout: false,
    component: './404',
  },
];

3. 按钮与操作列细粒度鉴权

在页面组件内部，可以使用 useAccess Hook 或 <Access> 组件实现操作按钮的条件渲染：

// 页面内部操作列控制示例
import React from 'react';
import { useAccess, Access } from '@umijs/max';
import { Button, Space } from 'antd';

export const UserActionColumn: React.FC<{ record: API.UserItem }> = ({ record }) => {
  const access = useAccess();

  return (
    <Space size="middle">
      <Button type="link" size="small">详情</Button>

      <Access accessible={access.canUserDelete} fallback={<span style={{ color: '#ccc' }}>无删除权限</span>}>
        <Button type="link" danger size="small" onClick={() => handleDelete(record.id)}>
          删除
        </Button>
      </Access>
    </Space>
  );
};

四、统一网络请求与业务组件标准化

中后台系统由大量的数据表格、表单和详情页构成。规范网络请求网关与统一业务组件的使用标准，能够直接决定开发效率与系统质量。

1. 网络请求拦截网关配置（src/requestConfig.ts）

基于 @umijs/max 的 plugin-request，我们可以在全局请求管道中注入认证 Token，并在响应拦截器中对业务状态码进行归一化处理：

// src/requestConfig.ts
import type { RequestConfig } from '@umijs/max';
import { message, notification } from 'antd';

export const request: RequestConfig = {
  timeout: 10000,
  errorConfig: {
    // 错误接收及全局通知策略
    errorThrower: (res: any) => {
      const { code, msg, success } = res;
      if (!success) {
        const error: any = new Error(msg);
        error.name = 'BizError';
        error.info = { code, msg };
        throw error;
      }
    },
    errorHandler: (error: any, opts: any) => {
      if (opts?.skipErrorHandler) return;
      if (error.name === 'BizError') {
        message.error(error.info.msg || '业务操作异常');
      } else if (error.response) {
        // HTTP 状态码非 2xx
        const status = error.response.status;
        if (status === 401) {
          message.error('登录凭证已过期，请重新登录');
          localStorage.removeItem('token');
          window.location.href = '/user/login';
        } else if (status === 403) {
          notification.error({ message: '越权访问', description: '您没有权限执行该操作' });
        } else if (status >= 500) {
          message.error('服务端网关繁忙，请稍后重试');
        }
      } else {
        message.error('网络连接异常，请检查网络设置');
      }
    },
  },
  requestInterceptors: [
    (config: any) => {
      const token = localStorage.getItem('token');
      if (token) {
        config.headers = {
          ...config.headers,
          Authorization: `Bearer ${token}`,
        };
      }
      return config;
    },
  ],
};

2. ProTable 高阶表格标准化实践

中后台 70% 以上的业务界面是“筛选表单 + 数据表格 + 分页栏”。使用传统的 Ant Design Table 需要手动维护 loading、pagination、filters、form.submit 等十余个状态变量，而 ProTable 将上述行为完全封装，代码量缩减 60% 以上：

// src/pages/System/UserList/index.tsx
import React, {{ useRef }} from 'react';
import type {{ ActionType, ProColumns }} from '@ant-design/pro-components';
import {{ ProTable }} from '@ant-design/pro-components';
import {{ Button, Tag, Popconfirm }} from 'antd';
import {{ PlusOutlined }} from '@ant-design/icons';
import {{ queryUserPageList, deleteUserRecord }} from '@/services/user';

export default () => {{
  const actionRef = useRef<ActionType>();

  const columns: ProColumns<API.UserItem>[] = [
    {{
      title: '用户名',
      dataIndex: 'username',
      copyable: true,
      ellipsis: true,
      formItemProps: {{ rules: [{{ required: true, message: '此项必填' }}] }},
    }},
    {{
      title: '角色标识',
      dataIndex: 'role',
      valueType: 'select',
      valueEnum: {{
        ADMIN: {{ text: '管理员', status: 'Error' }},
        AUDITOR: {{ text: '审计员', status: 'Warning' }},
        OPERATOR: {{ text: '操作员', status: 'Processing' }},
      }},
    }},
    {{
      title: '状态',
      dataIndex: 'status',
      valueType: 'select',
      render: (_, record) => (
        <Tag color={{record.status === 1 ? 'green' : 'volcano'}}>
          {{record.status === 1 ? '正常' : '禁用'}}
        </Tag>
      ),
    }},
    {{
      title: '创建时间',
      dataIndex: 'createTime',
      valueType: 'dateTime',
      sorter: true,
      search: false,
    }},
    {{
      title: '操作',
      valueType: 'option',
      key: 'option',
      render: (_, record) => [
        <a key="editable" onClick={{() => handleEdit(record)}}>编辑</a>,
        <Popconfirm
          key="delete"
          title="确认删除该用户？"
          onConfirm={{async () => {{
            await deleteUserRecord(record.id);
            actionRef.current?.reload();
          }}}}
        >
          <a style={{{ color: '#ff4d4f' }}}>删除</a>
        </Popconfirm>,
      ],
    }},
  ];

  return (
    <ProTable<API.UserItem>
      headerTitle="用户账户矩阵"
      actionRef={{actionRef}}
      rowKey="id"
      search={{{ labelWidth: 80 }}}
      toolBarRender={{() => [
        <Button key="button" icon={{<PlusOutlined />}} type="primary" onClick={{handleCreate}}>
          新建账号
        </Button>,
      ]}}
      request={{async (params, sort, filter) => {{
        const { current, pageSize, ...searchParams } = params;
        const res = await queryUserPageList({{
          page: current,
          pageSize,
          ...searchParams,
          sortField: Object.keys(sort)[0],
          sortOrder: Object.values(sort)[0],
        }});
        return {{
          data: res.data.list,
          success: res.success,
          total: res.data.total,
        }};
      }}}
      pagination={{{ defaultPageSize: 10, showSizeChanger: true }}}
    />
  );
}};

五、构建调优、容器化交付与上线检查

中后台系统虽然对 SEO 不敏感，但对于首屏白屏时间以及生产版本更新时的缓存命中率有极高要求。在完成功能开发后，必须进行生产交付治理。

1. 依赖拆分优化（splitChunks）

大型中后台系统引用的 Ant Design、ProComponents、React 核心库体积较大。在 config/config.ts 中配置分包策略，将通用基础依赖沉淀到独立缓存块中：

// config/config.ts 中的拆包配置
export default defineConfig({
  extraBabelPlugins: [],
  chainWebpack(config) {
    config.optimization.splitChunks({
      chunks: 'all',
      minSize: 30000,
      maxAsyncRequests: 10,
      maxInitialRequests: 5,
      cacheGroups: {
        antdesigns: {
          name: 'antdesigns',
          test: /[\/]node_modules[\/](@ant-design|antd)[\/]/,
          priority: 20,
        },
        vendors: {
          name: 'vendors',
          test: /[\/]node_modules[\/]/,
          priority: 10,
        },
      },
    });
  },
});

2. Docker 多阶段构建与 Nginx 路由兜底

生产环境交付采用 Docker 容器化方案。通过多阶段构建（Multi-stage Build），编译阶段产生的几百兆依赖缓存不会带入最终运行时镜像，确保基础运行镜像体积小于 30MB：

# Dockerfile 生产构建定义
# 阶段 1：构建产物
FROM node:18-alpine AS builder
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

# 阶段 2：轻量 Nginx 运行底座
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

由于 UmiJS 默认使用 Browser History（HTML5 History API），当用户在内页刷新或直接输入深层路由时，Nginx 必须将所有非文件请求转发至 index.html，否则将出现 404 错误：

# nginx.conf 核心配置
server {
    listen 80;
    server_name localhost;

    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
        # 必须配置 try_files 支持前端路由跳转
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend-gateway.production:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源缓存策略
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        root /usr/share/nginx/html;
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }
}

六、典型故障排查与关键边界说明

在实际落地与维护过程中，有若干边界问题发生率极高，需在团队开发规范中明确约束：

• 页面刷新后权限丢失或跳转 403：
  根因分析： src/app.tsx 中的 getInitialState 执行为异步 Promise，若某些自定义页面内过早触发了权限判定，此时 initialState 尚未挂载完毕。
  解决办法： 依赖 initialState 的子组件应在外层包裹 initialState?.currentUser ? <Children /> : <PageLoading />，或确保所有受限页面均在 routes.ts 的守卫机制下运行。
• 生产环境重新发版后 ChunkLoadError：
  根因分析： 生产环境持续发布时，旧版本 HTML 仍在客户端保持，用户点击新菜单请求已被服务器清理的旧 hash js 文件，导致加载失败。
  解决办法： 在 src/app.tsx 的 onRouteChange 中监听脚本加载错误，捕获 ChunkLoadError 并弹窗提示或执行 window.location.reload(true) 强制刷新获取最新 HTML 入口。
• Mock 接口外溢导致生产异常：
  根因分析： 开发期间启用了 mock: {}，若在构建命令中未显式传入 MOCK=none，部分脚手架机制可能会将虚拟 Mock 代码带入测试环境，掩盖真实接口契约问题。
  解决办法： 在 package.json 构建脚本中明确加入 "build": "cross-env MOCK=none max build"，从源头杜绝非真实接口逻辑。