从零打造基于vue3+ts+tsx+vite的antdv中后台管理系统(一)项目总览和环境搭建

站长

2022年11月21日 21:25 · 阅读数 16

一、前言

接触和使用 vue3 快 1 年了, 时至今日, vue3 的生态已经趋于成熟, 已结陆陆续续有不少公司开始使用 vue3 开发项目, 学习和使用 vue3 已是大势所趋. vue3-ts-antd-admin是基于 vue3、ts、tsx、vite 开发的一套中后台管理系统模板, 简洁轻量, 适合中小型中后台项目的开发.

本文会介绍该模板的功能和技术栈, 并从零开始介绍该系统的构造过程.

Github: 传送门

演示地址：传送门

编辑器预览：

从零打造基于vue3+ts+tsx+vite的antdv中后台管理系统(一)项目总览和环境搭建

二、技术栈

前端

vue3: 核心框架 pinia: 状态管理 less: css 预编译器 ant design: 组件库 ts/tsx: 开发和模板语言 vite2: 前端构建工具
服务端

koa2: 核心框架 mysql: 数据库 redis: 缓存 ts:开发语言

三、功能

本项目并不复杂, 只实现和保留了(我认为)最核心的部分. 后续会按重要程度和普适性增加功能, 如果有需要的功能也可以给我留言.

目前项目功能如下:

从业务上看, 系统包含:

登录注册
完整的权限管理模块, 包括用户管理、角色管理、菜单管理等
系统风格样式设置, 如主题色切换、布局切换、整体风格切换、色弱模式等等

从开发的角度上, 系统也对常见功能做了封装:

ts、tsx 支持
antdv 按需引入
基于 eslint、prettier、husky 的完整的校验和格式化支持
环境变量支持
vue-router 路由支持
pinia 状态管理
自定义 icon 引入
less 支持
表单封装
图片预览封装
常见筛选表单 + 按钮组 + 表格页面封装
axios 请求封装和全局拦截
gzip

四、目录结构

├── .husky husky # 脚本 
├── .vscode vscode # 配置
├── public
│ └── favicon.ico # 网站图标
├── src
│ ├── api # Api ajax 等
│ ├── assets # 本地静态资源
│ ├── config # 项目全局设置
│ ├── components # 通用组件
│ ├── core # 自定义指令等
│ ├── lib # 依赖包引入
│ ├── router # Vue-Router
│ ├── store # Pinia
│ ├── typings # .d.ts 描述文件
│ ├── utils # 工具库
│ ├── views # 业务页面入口和常用模板
│ └── App.vue # Vue 模板入口
│ └── env.d.ts # 环境变量定义文件
│ └── main.ts # Vue 入口 ts
│ └── permission.ts # 路由守卫(路由权限控制)
└── .env # 环境变量
└── .env.development # 开发环境变量
└── .env.production # 生产环境变量
└── .eslintrc.json # eslint 配置
└── .prettierrc.json # prettier 配置
└── deploy.sh # 部署脚本
└── index.html # Vue 入口模板
└── README.md
└── package.json
└── tsconfig.json
└── tsconfig.node.json
└── vite.config.ts

五、环境搭建

1. 项目创建

使用 vite 社区模板, 即可轻松创建基于 vue3 和 ts 的项目模板

npm init vite@latest

然后按照提示, 依次选择 vue 、 vue-ts , 即可创建 vue3 + ts + vite 项目

2. eslint、 prettier 和 husky 配置

安装依赖

yarn add eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-vue @typescript-eslint/eslint-plugin @typescript-eslint/parser prettier -D

配置 eslint 和 prettier

新增.eslintrc.json

// .eslintrc.json
{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true,
    "vue/setup-compiler-macros": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended"
  ],
  "parser": "vue-eslint-parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "parser": "@typescript-eslint/parser",
    "sourceType": "module"
  },
  "plugins": ["vue", "@typescript-eslint"],
  "rules": {
    "vue/comment-directive": "off",
    "prettier/prettier": "off",
    // 允许单字单词作为组件名
    "vue/multi-word-component-names": "off",
    "@typescript-eslint/no-non-null-assertion": "off"
  }
}

新增.prettierrc.json

// .prettierrc.js
{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true
}

安装 vscode 插件

安装下列 vscode 插件(已安装可跳过)

Vue Language Features (Volar)
Prettier - Code formatter

Volar 可以简单理解为是 vue3 的 Vetur, 如果是既有 vue2 项目又有 vue3 项目的, 可在工作区修改设置

新建.vscode 文件夹, 在.vscode 新建 extensions.json 和 settings.json

// .vscode/extensions.json
{
  "recommendations": ["johnsoncodehk.volar"]
}

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  },
  "vetur.format.enable": true,
  "vetur.validation.script": false,
  "vetur.validation.style": false,
  "vetur.validation.template": false
}

安装 husky

husky 支持所有 git 钩子, 可以用来在提交校验代码

安装 husky

husky 是一款 git-hooks 执行工具, 帮助我们在提交代码时执行一些代码检查或其他的操作, 这里只用到 pre-commit 钩子。

yarn add husky -D

husky 配置

在根目录新建 .husky 文件夹, 在 .husky 下新建 pre-commit 文件

# pre-commit

#!/bin/sh#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install lint-staged

配置 lint 相关命令

修改 package.json

// package.json
...
"scripts": {
  "dev": "vite --mode development",
  "build": "vue-tsc --noEmit && vite build --mode production",
  "preview": "vite preview",
  "lint": "eslint . --ext .vue,.ts,.jsx,.tsx --fix",
  "format": "prettier --write ./**/*.{vue,ts,tsx,js,jsx,css,less,scss,json,md}",
  "prepare": "husky install"
}

执行 npm run prepare 或者当每次执行 npm install 时, 会初始化 husky, 即在.husky 目录生成*_*文件夹

当我们提交代码时, 会对代码进行全量检查

配置 lint-staged

// package.json

"lint-staged": {
  "*.{js,vue,ts,jsx,tsx}": [
    "prettier --write",
    "eslint --fix"
  ],
  "*.{html,css,less,scss,md}": [
    "prettier --write"
  ]
}

lint-staged 的作用在于可以只对 git staged(暂存区) 中要提交的代码进行检查

3. 路径别名配置和文件后缀省略

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": resolve("./src"),
      "~@": resolve("./src"),
    },
    // 省略文件后缀
    extensions: [".js", ".ts", ".json", ".jsx", ".tsx"],
  },
});

4. 添加 css 预处理器 less

安装 less

yarn add less -D

自定义全局 less 变量

在 assets 新建 styles 目录存放样式, 在 styles 下新建 common 目录存放公共样式和变量, 在 common 下新建 common.less、var.css 和 var.less

/* src/assets/styles/common/var.css 存放css变量 */
:root {
  --ant-primary-color: #18a058;
}

/* src/assets/styles/common/var.less 存放less变量 */
@primary-color: var(--ant-primary-color, #18a058);

/* src/assets/styles/common/common.less 存放公共样式 */
a {
  color: @primary-color;
}

在 vite.config.ts 引入 var.less, var.less 里定义的 less 变量便可以在全局使用

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";

function resolve(url: string): string {
  return path.resolve(__dirname, url);
}

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      "@": resolve("./src"),
      "~@": resolve("./src"),
    },
  },
  css: {
    preprocessorOptions: {
      less: {
        // 全局添加less
        additionalData: `@import '@/assets/styles/common/var.less';`,
        javascriptEnabled: true,
      },
    },
  },
});

此时 ts 并不能识别 nodejs 的模块, path 会报错, 需要安装@types/node

yarn add @types/node -D

然后修改 tsconfig.node.json

// tsconfig.node.json
{
  "compilerOptions": {
    "composite": true,
    "module": "esnext",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts"]
}

在 App.vue 里引入 var.css 和 common.less

<!-- src/App.vue -->
<script setup lang="ts">
// This starter template is using Vue 3 <script setup> SFCs
// Check out https://vuejs.org/api/sfc-script-setup.html#script-setup
import HelloWorld from "./components/HelloWorld.vue";
</script>

<template>
  <HelloWorld msg="Hello Vue 3 + TypeScript + Vite" />
</template>

<style>
@import url("@/assets/styles/common/var.css");
@import url("@/assets/styles/common/common.less");
</style>

5. 开发服务器配置

// vite.config.ts

export default defineConfig({
  ...
  server: {
    port: 8001, // 端口
    proxy: { // 请求转发
      '/api': {
        target: 'http://localhost:9002',
        ws: false,
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '/api/v1'),
      },
      '/resource': {
        target: 'https://static.fhtwl.cc',
        ws: false,
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/resource/, ''),
      },
    },
  },
});

6. ts/tsx 配置

在创建项目时, 我们选择 ts - vue-ts ,此时项目已经支持 ts , 支持 tsx 还需要安装插件

yarn add @vitejs/pugin-vue-jsx

配置插件

// vite.config.ts

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";

export default defineConfig({
  plugins: [vue(), vueJsx()],
});

7. antdv 按需引入

安装 antdv

yarn add ant-design-vue
yarn add @ant-design/icons-vue -D

按需加载

安装按需加载插件

yarn add unplugin-vue-components -D

引入插件

// vite.config.ts
import Components from "unplugin-vue-components/vite";
import { AntDesignVueResolver } from "unplugin-vue-components/resolvers";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";

export default defineConfig({
  plugins: [
    vue(),
    vueJsx(),
    // 按需加载
    Components({
      include: [/\.vue$/, /\.tsx$/], // 支持 vue和tsx
      resolvers: [
        AntDesignVueResolver({
          // 不加载css, 而是手动加载css. 通过手动加载less文件并将less变量绑定到css变量上, 即可实现动态主题色
          importStyle: false,
          // 加载所有icon
          resolveIcons: true,
        }),
      ],
    }),
  ],
});

unplugin-vue-components 在监测到项目使用 ts 后, 会在项目根目录生成一个 components.d.ts, 里面即是根据组件内容生成的类型声明, 为 volar 提供类型提示, 他会自动根据文件变动进行更新(注意: compnents.d.ts 文件会在 vue-tsc 运行的时候进行更新，建议把他加入 gitignore 中，以免出现频繁更改导致 git 监测到项目内容一直变动的问题)

unplugin-vue-components 还支持项目中开发的公共组件的自动引入, 即 dirs 配置, 其默认值就是 src/components, 也就是说, src/components 下的组件同样会被自动引入

挂载全局变量

在 src/lib 下新建 ant-design-vue 目录, 在 ant-design-vue 下新建 index.ts

// src/lib/ant-design-vue/index.ts

import { message, Modal, notification } from "ant-design-vue";

import { App } from "vue";

export default function setupAtnd(app: App<Element>) {
  app.config.globalProperties.$message = message;
  app.config.globalProperties.$confirm = Modal.confirm;
  app.config.globalProperties.$notification = notification;
}

然后在 main.ts 里执行

// main.ts

import { createApp } from "vue";
import App from "./App.vue";
import setupAtnd from "@/lib/ant-design-vue";

const app = createApp(App);

setupAtnd(app);

app.mount("#app");

此时使用 this.message_ 会报错, 提示不存在 _message 这个属性, 因此还需要对这些自定义全局变量进行声明

// src/typings/common/index.d.ts
import { MessageApi } from "ant-design-vue/lib/message";
import { ModalFunc } from "ant-design-vue/lib/modal/Modal";
import { NotificationApi } from "ant-design-vue/lib/notification";

declare module "@vue/runtime-core" {
  // 定义绑定在全局vue示例上的变量
  interface ComponentCustomProperties {
    $message: MessageApi;
    $confirm: ModalFunc;
    $notification: NotificationApi;
  }
}

总结

本文是 从零打造基于 vue3+ts+tsx+vite 的 antdv 中后台管理系统 系列的第一篇, 主要对项目进行了一个整体的介绍以及对开发环境的搭建, 下一步就可以正常开始开发

文中若有错误或者可优化之处, 望请不吝赐教. 如果对你有帮助的话, 麻烦点个赞

从零打造基于vue3+ts+tsx+vite的antdv中后台管理系统(一)项目总览和环境搭建

一、前言

二、技术栈

三、功能

四、目录结构

五、环境搭建

1. 项目创建

2. eslint、 prettier 和 husky 配置

安装依赖

配置 eslint 和 prettier

安装 husky

husky 配置

配置 lint 相关命令

配置 lint-staged

3. 路径别名配置 和 文件后缀省略

4. 添加 css 预处理器 less

安装 less

自定义全局 less 变量

5. 开发服务器配置

6. ts/tsx 配置

7. antdv 按需引入

安装 antdv

按需加载

挂载全局变量

总结

3. 路径别名配置和文件后缀省略