收下这份 Vue + TS + Vite 中后台系统搭建指南，从此不再害怕建项目

前言

本篇文章是系列文章的开篇之作，主要介绍搭建一个后台系统前期的准备工作，基建工程是如何做的

写在之前

在国内的前端圈中，写后台系统是一件烂大街，且毫无技术含量的活，大部分中小公司的前端，所面对的工作内容，都脱离不了写后台系统，写增删改查。这些重复、繁琐的工作，社区内也有着解决方案，比如 vue-element-admin、若依系统，特点是开箱即用，详细文档，也有一些较年轻的后台系统，特点是技术栈追新，更多样的解决方案等，它们也受到大家的欢迎，比如vue-vben-admin、vue-pure-admin

在自己写代码的过程中，很大程度上受到了它们的启发，在此表示感谢。

为什么要写这个后台系统

写这个后台系统的目的很简单，就是让理论知识应用到具体实践中，大家常常调侃"眼睛会了，手不会"，其实就是缺乏实战经验，我也是如此。

基于这样的目的，就能够预想到后台系统中一些可以写的内容，比如工程化中如何搭起一套代码风格规范，如何形成一套Git提交规范，我使用到了 Echarts 图表库，又该如何来封装它以便复用，权限该如何设计等...

实战中，会遇到一些平时理论上很难顾及到的部分，或者一些大的功能点需要记录
将这些历程记录下来，写点笔记，成一份学习笔记
把学习笔记加以润色，就成了一篇文章
笔记一多，稍加整理，就成了一份专栏

专栏介绍

《通俗易懂的中后台系统建设指南》系列文章旨在告诉你如何来构建一个优秀的中后台管理系统

系列专栏地址：GitHub 博客(推荐) | 掘金专栏 | 思否专栏

特点：

• 系列专栏：系列文章自成体系，从基础到深入探讨，每篇文章都配有丰富相关链接，帮助读者深入学习和掌握知识点
• 图文并茂：文章内容包含示例代码和实际操作截图。更直观地理解每个概念和步骤
• 实战 Admin：提供实战项目 vue-clean-admin，详见 源码。理论知识只是开始，真正理解需要亲自动手实践
• 高质量：结构清晰，层次分明，详解实践方法。建立全面认知，提供最佳实践

准备工作

开发环境的准备与配置

操作系统：Mac OS | Windows，我的 Mac 版本是 15.0.1(Sequoia)

Node 环境：推荐 Node 18.18.0 以上版本：官网下载，我的 Node 版本是 21.7.2。推荐使用 nvm 管理 node

项目提供 .nvmrc 并写入了 node 版本，可以使用 nvm use 来切换到项目指定版本

包管理器：强烈推荐使用 pnpm 来管理依赖包，我的 pnpm 版本是 9.7.1。后面的文章都是使用 pnpm 来安装依赖包等操作

如果你还没有，在这里安装它，或者看下面的示例：

# 全局安装pnpm
npm install pnpm -g

# 设置淘宝镜像
pnpm config set registry https://registry.npmmirror.com/

# 查看镜像
pnpm config get registry

# 查看 pnpm 版本
pnpm -v

浏览器：这一块没什么好建议的，无脑使用 Google Chrome 浏览器即可

版本控制：使用流行的 Git 即可，你还应该知道一些 git 的基本命令或者使用可视化软件来帮助你，这里不再列举，你可以自行搜索

IDE 的选择与配置建议

推荐使用 VS Code 作为开发工具，从这里下载它

VS Code 特色是轻量、高效、可扩展性强，同时也支持插件扩展，这里不会一一去列举插件，你可以在 vue-clean-admin 源码中找到 extensions.json 内容，里面写了一些推荐的插件：vue-clean-admin 推荐插件

如何将推荐插件安装到你的 VS Code 中？

• 第一种方式，克隆 vue-clean-admin 项目到本地，然后按下图操作即可
• 第二种方式，将本项目的 extensions.json 内容复制到你自己的项目同文件中，然后按下图操作即可

图示：

初始化项目

拉起一个初始项目，请参考 搭建第一个 Vite 项目

或者在你的文件夹下运行以下命令：

pnpm create vite test-admin --template vue-ts
# test-admin - 你的项目名称

执行 pnpm i 后，你的目录应该是这样的

启动项目 pnpm dev 后，应该是：

如果项目启动是如上页面，那么你已经完成了项目的起步搭建

下面，我们来往里面添加一些工程依赖来满足我们的后续开发需要

技术栈选择

• Vue 3
• Vite
• TypeScript
• Element Plus
• Pinia
• Vue Router
• Tailwind css || UnoCss
• VueUse
• ...

在 Vue 生态下，后台系统的技术栈选择大同小异

这些基础性的安装及配置方式，你首先应该是去到它们的官方文档中进行查阅，所以下面的安装示例中，我会给出它们的官方链接

下面列举一些基本依赖安装：

Pinia 状态管理

Pinia 是Vue 的状态管理库，Vue2 中我们使用 VueX，Vue3中推荐使用 Pinia ，在这里查看两者的差异

pnpm add pinia

router 路由

Vue Router 为 Vue.js 提供富有表现力、可配置的、方便的路由。如果你对 Vue2 有了解的话，那么你对 Router 路由也不会陌生

pnpm add vue-router@4

Router 路由及 Pinia 状态管理，是项目中相对重要的部分，这里只是简单的安装，在下一篇文章中，我们会来详细配置它们

VueUse 安装

VueUse 是 Vue 生态中基于 Composition API 的实用函数集合。React 生态与之相对的是 ahooks

pnpm add @vueuse/core

里面有很多 hook 供你使用，比如获取元素内容或边框尺寸的更改

<script setup>
import { ref } from 'vue'
import { useResizeObserver } from '@vueuse/core'

const el = ref(null)
const text = ref('')

useResizeObserver(el, (entries) => {
  const entry = entries[0]
  const { width, height } = entry.contentRect
  text.value = `width: ${width}, height: ${height}`
})
</script>

<template>
  <div ref="el">
    {{ text }}
  </div>
</template>

原子化CSS

这里演示 UnoCss 和 Tailwind Css 的安装配置方式，选其一即可

UnoCss 安装

UnoCss 是一个即时按需原子 CSS 引擎，比 Tailwind css 更轻量

pnpm add -D unocss

在 vite.config.ts 中配置它

// vite.config.ts
import UnoCSS from "unocss/vite";
import { defineConfig } from "vite";

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

在根目录下新建一个 uno.config.ts 文件，表示 UnoCss 的配置文件

// uno.config.ts
import { defineConfig } from "unocss";

export default defineConfig({
  // ...UnoCSS options
});

在 main.ts 入口引入

// main.ts
import "virtual:uno.css";

这些配置都是官网所示例的，我只是转述了一遍，所以，很多时候我会推荐先去看文档

在 VS Code 中安装 UnoCss 插件来帮助你更好的使用

Tailwind css 安装

Tailwind css 无需离开 HTML 即可快速构建现代网站。

pnpm add -D tailwindcss postcss autoprefixer

• autoprefixer 自动补全 CSS 前缀，兼容浏览器(需要进一步配置)

接下来，我们运行初始化脚本，它会在当前目录(放在根目录)生成 tailwind.config.js 文件和 postcss.config.js 文件

npx tailwindcss init -p
pnpm dlx tailwindcss init -p

在你的 tailwind.config.js 文件中配置 content，作用是扫描路径文件的类名，然后为这些样式生成所有相应的 CSS：

注意，路径是相对于项目根目录的

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

然后新建一个 css 文件，可以放在 styles 文件夹下，命名为 tailwind.css

然后写入以下内容

/* tailwind.css */

/* 注入Tailwind 的基本样式 */
@tailwind base;

/* 注入 Tailwind 的组件类和任何组件类 */
@tailwind components;

/* 注入 Tailwind 的实用程序类 */
@tailwind utilities;

最后将这个 css 文件引入到 main.ts 中

import "./styles/tailwind.css";

在 VS Code 中安装 Tailwind CSS IntelliSense 插件来帮助你更好的使用

Element Plus 组件库

Element Plus 是基于 Vue 3，面向设计师和开发者的组件库

Element UI 是国内 Vue 生态中经典的组件库，尽管它一直被人诟病 UI 难看，但这不妨碍它成为Vue 组件库的老大哥

pnpm add element-plus

在官网介绍了 Element Plus 在项目中的多种用法，这里使用手动按需引入，其他方式请看快速开始

在后续的 Vite 配置篇中，我们会通过 unplugin-vue-components、unplugin-auto-import 来实现组件库的自动按需引入，敬请期待！

sass

Sass 是一个 CSS 的预编译扩展语言，官网介绍是世界上最成熟、最稳定、最强大的专业级 CSS 扩展语言
同类型的预编译语言还有Less，这里选择 Sass 原因主要是

• 比 Less 更强大，更丰富的能力

• 与组件库 Element Plus 所使用 CSS 预编译保持一致

  pnpm add sass -D
  
  pnpm add element-plus

不用安装 sass-loader 等解析器

lodash-es

lodash 是一个JS实用工具集

我们这里使用 lodash-es ，它是 lodash 的 ES 模块化实现

@types/lodash-es 是 lodash-es 的TS类型包

pnpm add lodash-es
pnpm add --save-dev @types/lodash-es

Mitt

Mitt 是一个事件处理依赖，用于解决部分场景下的组件通信事件，比如兄弟组件，不相干的组件。代替 Vue2 中的 evenBus

pnpm add --save mitt

可视化图表 Echarts

Echarts 是一个基于 JavaScript 的开源可视化图表库

pnpm add --save echarts

同时，提供全量引入和按需引入两种方式，这里使用按需引入，官网介绍很详细，参阅在项目中引入 Echarts

在后续篇章中，我们将另开一篇文章来介绍如何封装 Echarts

网络请求库 axios

axios 是一个基于 Promise 的网络请求库

pnpm add axios

进度条 nprogress

nprogress 用来实现进度条，一般用于路由切换时在顶部展示的进度条

@types/nprogress 是 nprogress 的 TS 类型包

pnpm add --save nprogress
pnpm add --save-dev @types/nprogress

注意，这里只介绍了部分依赖，其他的依赖及配置，我们会在后续篇章中详细来讲述，比如 ESLint、Prettier、Stylelint、Husky...等

目录结构的设计

目录结构设计及命名，这一块基本上是大家默契且通用的命名，比如

• components 代表组件目录
• views 代表页面目录
• store 代表状态管理目录
• hooks 代表自定义 hook
• utils 代表工具目录
• ...

这里你不用去纠结，可以查看 vue-clean-admin 的目录结构并跟着创建即可，后面也会在项目 README.md 给到一个 Tree 目录树结构说明

我的其他工具

• 网易云音乐
• 网易有道翻译
• Chat GPT
• 魔法
• Obsidian

其他准备

• 保持兴趣，保持热情，且有耐心
• 善用搜索引擎，具备良好搜索能力是程序员的必修课

FAQ

找不到模块“./App.vue”或其相应的类型声明

因为未定义 vue 文件的类型，让 ts 无法处理，需要在 .d.ts 文件下加入声明

解决方法 1：在 vite-env.d.ts 中写入

解决方法 2：根据自己的项目文件结构，新建一个.d.ts 后缀的类型声明文件，写入以下代码，比如 types/global.d.ts

declare module "*.vue" {
  import type { DefineComponent } from "vue";
  const vueComponent: DefineComponent<{}, {}, any>;
  export default vueComponent;
}

交流讨论

文章如有错误或需要改进之处，欢迎指正

更多高质量文章请关注 GitHub 博客，喜欢请 star