Ant Design Vue3 Admin 零基础入门实战教程：从项目搭建到核心功能避坑指南

【免费下载链接】ant-design-vue3-admin 一个基于 Vite2 + Vue3 + Typescript + tsx + Ant Design Vue 的后台管理系统模板，支持响应式布局，在 PC、平板和手机上均可使用 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vue3-admin

Ant Design Vue3 Admin 是基于 Vite2 + Vue3 + TypeScript + Ant Design Vue 的企业级后台管理系统模板，支持响应式布局和多语言切换。本文将带你从项目架构到核心功能，手把手掌握这个强大框架的使用技巧，让你快速上手企业级后台开发！

项目概览：核心技术栈与架构设计

技术栈亮点解析

💡 你知道吗？ 这个项目采用了当前最流行的前端技术组合：

• Vite2：比 Webpack 快 10-100 倍的构建工具，实现秒级热更新
• Vue3 + TypeScript：提供更好的类型安全和代码提示
• JSX 语法：在 Vue 中使用类 React 的写法，适合复杂组件开发
• Ant Design Vue：阿里出品的企业级 UI 组件库，美观且功能完备

核心目录功能对比表

目录路径	主要功能	重要性
src/layouts	页面布局组件（默认布局/空布局）	⭐⭐⭐⭐⭐
src/pages	业务页面组件（登录/仪表盘等）	⭐⭐⭐⭐⭐
src/components	通用组件（面包屑/通知等）	⭐⭐⭐⭐
src/store	Vuex 状态管理（用户/菜单数据）	⭐⭐⭐⭐
src/plugins	插件配置（Axios 请求等）	⭐⭐⭐
vite.config.ts	项目构建配置	⭐⭐⭐

核心文件解析：从入口到渲染流程

1. 项目入口文件分析

src/App.tsx 是应用的根组件，主要负责国际化配置和路由视图渲染：

import { defineComponent } from 'vue';
import { useI18n } from 'vue-i18n';
import { a-config-provider } from 'ant-design-vue';

export default defineComponent({
  setup() {
    const { locale } = useI18n();
    return () => (
      // 根据当前语言切换 Ant Design 组件的国际化配置
      <a-config-provider locale={locale.value === 'en-US' ? enUS : zhCN}>
        <router-view></router-view> {/* 路由出口，渲染匹配的页面组件 */}
      </a-config-provider>
    );
  },
});

⚠️ 注意：router-view 是路由匹配组件的出口，所有页面都会在这里渲染。

2. 布局组件工作原理

src/layouts/default.tsx 实现了后台系统的经典布局：

// 响应式布局核心代码
export default defineComponent({
  setup() {
    const [collapsed, { toggle: toggleSider }] = useToggle(false);
    const isMobile = ref<boolean>(false);
    
    // 监听屏幕尺寸变化，自动切换移动端/桌面端布局
    queryMedia((data: string) => {
      isMobile.value = data === 'xs'; // xs 对应移动端尺寸
    });

    const toggle = () => {
      // 移动端显示抽屉菜单，桌面端折叠侧边栏
      isMobile.value ? toggleDrawer() : toggleSider();
    };

    return () => (
      <a-layout class={isMobile.value ? 'mobile' : 'desk'}>
        {/* 侧边栏和主内容区域 */}
      </a-layout>
    );
  },
});

💡 试试看这样操作：调整浏览器窗口大小，观察布局如何自动切换移动端视图。

配置指南：从基础设置到高级优化

环境变量配置详解

虽然项目中没有 .env 文件，但你可以创建以下环境配置文件：

文件名	用途	优先级
.env.development	开发环境配置	高
.env.production	生产环境配置	高
.env	默认配置	低

配置示例：

# API 基础路径
VITE_API_BASE_URL=/api
# 项目标题
VITE_APP_TITLE=Ant Design Vue3 Admin

在代码中使用环境变量：

// 通过 import.meta.env 获取
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

Vite 配置优化技巧

vite.config.ts 是项目构建的核心配置文件，这里分享几个优化技巧：

export default ({ command }: ConfigEnv): UserConfigExport => {
  return {
    base: '/ant-design-vue3-admin', // 部署基础路径
    css: {
      preprocessorOptions: {
        less: {
          // 自定义 Ant Design 主题色
          modifyVars: {
            'primary-color': '#5B8FF9', // 全局主色
            'text-color': 'rgba(0, 0, 0, .65)', // 文本色
          },
        },
      },
    },
    build: {
      outDir: './docs', // 输出目录
      sourcemap: false, // 生产环境关闭 sourcemap
    },
  };
};

⚠️ 常见问题：修改主题色不生效？确保 javascriptEnabled: true 已设置，且 Less 版本兼容。

状态管理与路由控制

Vuex 状态管理最佳实践

src/store/index.ts 实现了用户、菜单等核心数据的管理：

// 核心代码片段
export default {
  state, // 存储数据
  mutations, // 同步修改数据
  actions: {
    // 异步登录 action
    async ActionTypes.LOGIN {
      const { data } = await this.$request.post('/login', payload);
      if (data) {
        commit(MutationTypes.SET_USERINFO, data); // 提交 mutation 更新状态
        Cookies.set(userToken, data.id.toString()); // 保存 token
      }
    },
  },
};

💡 最佳实践：使用常量定义 Action 和 Mutation 类型，避免拼写错误。

权限控制实现原理

src/middleware/permission.ts 实现了基于路由的权限控制：

export default ({ route, store, redirect }: any) => {
  // 白名单页面直接放行
  if (!whiteList.includes(route.path)) {
    // 检查用户是否有权限访问当前页面
    if (!store.state.userInfo.permissions?.includes(route.meta.permissionCode)) {
      redirect('/403'); // 无权限跳转到 403 页面
    }
  }
};

实用技巧与避坑指南

1. Axios 请求封装与错误处理

src/plugins/axios.ts 封装了网络请求：

const request = axios.create({
  baseURL: '/api',
});

// 请求拦截器
request.interceptors.request.use(
  config => {
    // 添加认证 token
    const token = Cookies.get(userToken);
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  error => Promise.reject(error)
);

// 响应拦截器
request.interceptors.response.use(
  response => {
    if (response?.data?.code !== "S_00000") {
      message.error(t(`ApiError.${response?.data?.code}`));
      return Promise.reject(response);
    }
    return response?.data;
  }
);

2. 路由跳转与标签页管理

在项目中使用路由跳转非常简单：

// 登录成功后跳转到首页
router.push({ path: '/' });

// 在标签页组件中切换页面
router.push(activeKey);

💡 小技巧：visited-tags 组件实现了类似浏览器标签页的功能，可在 src/components/visited-tags/index.tsx 中自定义其行为。

3. 多语言配置与切换

项目支持中英文切换，核心配置在：

• src/locales/en-US.ts - 英文语言包
• src/locales/zh-CN.ts - 中文语言包

使用方法：

const { t } = useI18n();
// 在模板中使用
<div>{t('Login.Username')}</div>

项目部署与常见问题解决

快速部署步骤

1. 克隆项目代码：

git clone https://gitcode.com/gh_mirrors/an/ant-design-vue3-admin

2. 安装依赖：

cd ant-design-vue3-admin
yarn install

3. 本地开发：

yarn dev

4. 构建生产版本：

yarn build

常见问题解决方案

1. 启动报错：检查 Node.js 版本是否 >= 14.0.0
2. 依赖安装失败：尝试使用 yarn install --registry=https://registry.npm.taobao.org
3. 构建体积过大：在 vite.config.ts 中配置 rollupOptions 进行代码分割

总结

通过本文的学习，你已经掌握了 Ant Design Vue3 Admin 的核心架构和使用技巧。这个框架不仅提供了丰富的组件和功能，还采用了现代化的前端技术栈，非常适合企业级后台系统开发。

💡 最后一个小建议：在实际开发中，建议先熟悉 src/config/constants.ts 中的全局常量配置，这将帮助你更快地理解项目结构和定制化开发。

现在，就开始你的 Ant Design Vue3 Admin 实战之旅吧！如有问题，欢迎在评论区留言讨论~

【免费下载链接】ant-design-vue3-admin 一个基于 Vite2 + Vue3 + Typescript + tsx + Ant Design Vue 的后台管理系统模板，支持响应式布局，在 PC、平板和手机上均可使用 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vue3-admin