Vue3 项目上手学习——V3 Admin

Start

学了那么久的 Vue3，终于到上手实战项目的时候了。之前一直是看视频教程，没有真正的上手打开 VSC 摸过项目，是时候写代码了。

这次选用的是 V3 Admin 这个项目，毕竟人家使用了主流技术 Vue3 + Pinia + Router + Vite + Element-Plus 。本文是在官网文档的基础上进一步抽丝剥茧分析这个项目，并提炼一些 通用写法。

reference：

1. GitHub v3-admin-vite
2. 项目对应老鸟中文文档：V3 Admin Vite 中文文档 - 掘金
3. 适用于小白的 step by step tutorial V3 Admin Vite - pany 的专栏 - 掘金

Technology Stack 技术栈

• Vue3：采用 Vue3 + script setup 最新的 Vue3 组合式 API
• Element Plus：Element UI 的 Vue3 版本
• Pinia: 传说中的 Vuex5
• Vite：真的很快，取代 webpack
• Vue Router：路由路由
• TypeScript：JavaScript 语言的超集
• PNPM：更快速的，节省磁盘空间的包管理工具
• Scss：和 Element Plus 保持一致
• CSS 变量：主要控制项目的布局和颜色
• ESlint：代码校验
• Prettier：代码格式化
• Axios：发送网络请求（已封装好）
• UnoCSS：具有高性能且极具灵活性的即时原子化 CSS 引擎
• 注释：各个配置项都写有尽可能详细的注释
• 兼容移动端: 布局兼容移动端页面分辨率

Prepare 准备

Install base Module

Proxy first，在 墙国，下个 npm 包前提是一个好用的代理：

npm config list
npm config set proxy=socks5://127.0.0.1:10808/
npm config delete proxy

Install module

npm install -g pnpm
# like npm insall xxx
pnpm add packageName

# initiate vite vue3
pnpm add vite -g
pnpm create vite@latest
pnpm install
pnpm add -D typescript ts-node @types/node less
pnpm add --save-dev prettier

Install ElementUI-Plus

pnpm install element-plus

In main.ts

// Element Plus
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";

const app = createApp(App);

app.use(ElementPlus);
app.mount("#app");

安装按需引入

pnpm install -D unplugin-vue-components unplugin-auto-import

向 vite.config.ts 添加插件：

import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

plugins: [
    // …
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],

configure：

AutoImport({
      // 自动导入 Vue 相关函数，如：ref, reactive, toRef 等
      imports: ["vue"],
      // eslint auto import
      eslintrc: {
        enabled: true, // 是否自动生成 eslint 规则，建议生成之后设置 false
        filepath: "./.eslintrc-auto-import.json", // 指定自动导入函数 eslint 规则的文件
      },
      //
      resolvers: [ElementPlusResolver(), IconsResolver({})],
      vueTemplate: true, // 是否在 vue 模板中自动导入
      dts: path.resolve(pathSrc, "types", "auto-imports.d.ts"), // 指定自动导入函数TS类型声明文件路径
    }),
    // 组件
    Components({
      resolvers: [
        // 自动导入 Element Plus 组件
        ElementPlusResolver(),
        // 自动注册图标组件
        IconsResolver({
          enabledCollections: ["ep"],
        }),
      ],
      dts: path.resolve(pathSrc, "types", "components.d.ts"), // 指定自动导入组件TS类型声明文件路径
    }),
    // 图标
    Icons({
      // 自动安装图标库
      autoInstall: true,
    }),

Configure 配置项

Vscode code snippets

vue3 code snippet：

{
  "Vue3 SFC template": {
    "prefix": "Vue3 SFC",
    "body": [
      "<template>",
      "\t<div class=\"app-container\">…</div>",
      "</template>\n",
      "<script lang=\"ts\" setup></script>\n",
      "<style scoped></style>",
      "$1"
    ],
    "description": "Vue3 SFC"
  }
}

vue3 hook code snippet:

{
  "Vue3 Hook 代码结构一键生成": {
    "prefix": "Vue3 Hook",
    "body": [
      "import { ref } from \"vue\"\n",
      "const refName1 = ref<string>(\"This is a ref variable\")\n",
      "export function useHookName() {",
      "\tconst refName2 = ref<string>(\"This is a ref variable\")\n",
      "\tconst fnName = () => {}\n",
      "\treturn { refName1, refName2, fnName }",
      "}",
      "$1"
    ],
    "description": "Vue3 Hook"
  }
}

Code specification 代码规范

命名规范

Components 组件和 Views 页面命名规范，这样做是为了更好的区分 component 和 view

1. Components 组件：都采用单词大写开头的  大驼峰  命名方式 (PascalCase)：@/components/Index.vue 、@/components/NotifyList.vue
2. Views 页面：页面由 components 组件组成，一律采用 短横线连接 (kebab-case)  的命名方式，比如：- @/views/fetch-select.vue

hook 命名：采用  **小驼峰 (camelCase)**，比如：@/hooks/useTheme.ts。

Prop 命名：在声明 prop 的时候，其命名应该始终采用  **小驼峰 (camelCase)**。

const props = defineProps({
  /** 打开全屏提示语 */
  openTips: { type: String, default: "全屏" },
  /** 关闭全屏提示语 */
  exitTips: { type: String, default: "退出全屏" },
});

代码规范

• prop 的定义应该尽量详细，至少需要指定其类型
• 在组件上总是必须用 key 配合 v-for，以便维护内部组件及其子树的状态。
• 避免 v-if 和 v-for 用在一起。

Annotation 注释规范

由于项目采用 TS 5.x 进行开发，为了获得更好的 TS 提示，项目采用了大量的  /** xxx */  注释，它的优点就是鼠标放上去会有注释显示出来。

Code format and verify 代码格式化和校验

.tsconfig

项目最重要的 ts 配置

.tsconfig

{
  "compilerOptions": {
    "target": "esnext",
    /** https://cn.vitejs.dev/guide/features.html#typescript-compiler-options */
    "useDefineForClassFields": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    /** TS 严格模式 */
    "strict": true,
    "jsx": "preserve",
    "jsxImportSource": "vue",
    "importHelpers": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    /** https://cn.vitejs.dev/guide/features.html#typescript-compiler-options */
    "isolatedModules": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "skipLibCheck": true,
    "types": [
      "node",
      "vite/client",
      /** Element Plus 的 Volar 插件支持 */
      "element-plus/global",
      "vitest"
    ],
    /** baseUrl 用来告诉编译器到哪里去查找模块，使用非相对模块时必须配置此项 */
    "baseUrl": ".",
    /** 非相对模块导入的路径映射配置，根据 baseUrl 配置进行路径计算 */
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "tests/**/*.ts",
    "types/**/*.d.ts",
    "vite.config.ts",
    "vitest.config.ts"
  ],
  /** 编译器默认排除的编译文件 */
  "exclude": ["node_modules", "dist"]
}

ESlint

• package.json 文件的 devDependencies 中有所需的 ESlint 依赖包。
• ESlint 的配置文件是根目录下的 .eslintrc.cjs，它里面定义了很多校验规则
• ESlint 的忽略文件是根目录下的 .eslintignore，它里面定义的目录和文件都不会被 ESlint 检查

.eslintrc.cjs

module.exports = {
  root: true,
  env: {
    browser: true,
    node: true,
    es6: true,
  },
  extends: [
    "plugin:vue/vue3-essential",
    "eslint:recommended",
    "@vue/typescript/recommended",
    "@vue/prettier",
    "@vue/eslint-config-typescript",
  ],
  parser: "vue-eslint-parser",
  parserOptions: {
    parser: "@typescript-eslint/parser",
    ecmaVersion: 2020,
    sourceType: "module",
    jsxPragma: "React",
    ecmaFeatures: {
      jsx: true,
      tsx: true,
    },
  },
  rules: {
    // TS
    "@typescript-eslint/no-explicit-any": "off",
    "no-debugger": "off",
    "@typescript-eslint/explicit-module-boundary-types": "off",
    "@typescript-eslint/ban-types": "off",
    "@typescript-eslint/ban-ts-comment": "off",
    "@typescript-eslint/no-empty-function": "off",
    "@typescript-eslint/no-non-null-assertion": "off",
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_",
      },
    ],
    "no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_",
      },
    ],
    // Vue
    "vue/no-v-html": "off",
    "vue/require-default-prop": "off",
    "vue/require-explicit-emits": "off",
    "vue/multi-word-component-names": "off",
    "vue/html-self-closing": [
      "error",
      {
        html: {
          void: "always",
          normal: "always",
          component: "always",
        },
        svg: "always",
        math: "always",
      },
    ],
    // Prettier
    "prettier/prettier": [
      "error",
      {
        endOfLine: "auto",
      },
    ],
  },
};

.eslintignore：

# Eslint 会忽略的文件

.DS_Store
node_modules
dist
dist-ssr
*.local
.npmrc

Prettier

• package.json 文件的 devDependencies 中有所需的 Prettier 依赖包
• Prettier 的配置文件是根目录下的 prettier.config.js，它里面定义了很多格式化规则
• Prettier 的忽略文件是根目录下的 .prettierignore，它里面定义的目录和文件都不会被 Prettier 格式化

prettier.config.js：

/**
 * 修改配置后重启编辑器
 * 配置项文档：https://prettier.io/docs/en/configuration.html
 * @type {import("prettier").Config}
 */

export default {
  /** 每一行的宽度 */
  printWidth: 120,
  /** 在对象中的括号之间是否用空格来间隔 */
  bracketSpacing: true,
  /** 箭头函数的参数无论有几个，都要括号包裹 */
  arrowParens: "always",
  /** 换行符的使用 */
  endOfLine: "auto",
  /** 是否采用单引号 */
  singleQuote: false,
  /** 对象或者数组的最后一个元素后面不要加逗号 */
  trailingComma: "none",
  /** 是否加分号 */
  semi: false,
  /** 缩进 */
  tabWidth: 2,
};

.prettierignore

# Prettier 会忽略的文件

.DS_Store
node_modules
dist
dist-ssr
*.local
.npmrc

vite.config.ts

项目 Vite 最重要的配置

vite.config.ts

/// <reference types="vitest" />

import { type ConfigEnv, type UserConfigExport, loadEnv } from "vite"
import path, { resolve } from "path"
import vue from "@vitejs/plugin-vue"
import { createSvgIconsPlugin } from "vite-plugin-svg-icons"
import svgLoader from "vite-svg-loader"
import UnoCSS from "unocss/vite"

/** 配置项文档：https://cn.vitejs.dev/config */
export default (configEnv: ConfigEnv): UserConfigExport => {
  // 从文件加载环境变量
  const viteEnv = loadEnv(configEnv.mode, process.cwd()) as ImportMetaEnv
  const { VITE_PUBLIC_PATH } = viteEnv
  return {
    /** 打包时根据实际情况修改 base */
    base: VITE_PUBLIC_PATH,
    resolve: {
      alias: {
        /** @ 符号指向 src 目录 */
        "@": resolve(__dirname, "./src")
      }
    },
    server: {
      /** 设置 host: true 才可以使用 Network 的形式，以 IP 访问项目 */
      host: true, // host: "0.0.0.0"
      /** 端口号 */
      port: 3333,
      /** 是否自动打开浏览器 */
      open: false,
      /** 跨域设置允许 */
      cors: true,
      /** 端口被占用时，是否直接退出 */
      strictPort: false,
      /** 接口代理 */
      proxy: {
        "/api/v1": {
          target: "https://mock.mengxuegu.com/mock/63218b5fb4c53348ed2bc212",
          ws: true,
          /** 是否允许跨域 */
          changeOrigin: true
        }
      },
      /** 预热常用文件，提高初始页面加载速度 */
      warmup: {
        clientFiles: []
      }
    },
    build: {
      /** 单个 chunk 文件的大小超过 2048KB 时发出警告 */
      chunkSizeWarningLimit: 2048,
      /** 禁用 gzip 压缩大小报告 */
      reportCompressedSize: false,
      /** 打包后静态资源目录 */
      assetsDir: "static",
      rollupOptions: {
        output: {
          /**
           * 分块策略
           * 1. 注意这些包名必须存在，否则打包会报错
           * 2. 如果你不想自定义 chunk 分割策略，可以直接移除这段配置
           */
          manualChunks: {
            vue: ["vue", "vue-router", "pinia"],
            element: ["element-plus", "@element-plus/icons-vue"],
            // vxe: ["vxe-table", "vxe-table-plugin-element", "xe-utils"]
          }
        }
      }
    },
    /** 混淆器 */
    esbuild: {
      /** 打包时移除 console.log */
      pure: ["console.log"],
      /** 打包时移除 debugger */
      drop: ["debugger"],
      /** 打包时移除所有注释 */
      legalComments: "none"
    },
    /** Vite 插件 */
    plugins: [
      vue(),
      // vueJsx(),
      /** 将 SVG 静态图转化为 Vue 组件 */
      svgLoader({ defaultImport: "url" }),
      /** SVG */
      // createSvgIconsPlugin({
        iconDirs: [path.resolve(process.cwd(), "src/icons/svg")],
        symbolId: "icon-[dir]-[name]"
      }),
      /** UnoCSS */
      UnoCSS()
    ],
    /** Vitest 单元测试配置：https://cn.vitest.dev/config */
    test: {
      include: ["tests/**/*.test.ts"],
      environment: "jsdom"
    }
  }
}

.env

环境变量

.env

# 所有环境自定义的环境变量（命名必须以 VITE_ 开头）

## 项目标题
VITE_APP_TITLE = V3 Admin Vite

##  打包路径（就是网站前缀，例如部署到 https://whaleluo.top/v3-admin-vite/ 域名下，就需要填写 /v3-admin-vite/）
VITE_PUBLIC_PATH = '/'

.editorConfig

editorConfig 是一个适用于 多语言，多 IDE 的代码格式化工具。有利于各种项目 形成统一的代码格式风格。
建议在所有项目中启动 editorConfig 因为真的很好用。

.editorConfig

# 修改配置后重启编辑器
# 配置项文档：https://editorconfig.org/

# 告知 EditorConfig 插件，当前即是根文件
root = true

# python format config
[*.py]
indent_style = space
indent_size = 4

# 适用全部文件
[*]
## 设置字符集
charset = utf-8
## 缩进风格 space | tab，建议 space（会自动继承给 Prettier）
indent_style = space
## 缩进的空格数（会自动继承给 Prettier）
indent_size = 2
## 换行符类型 lf | cr | crlf，一般都是设置为 lf
end_of_line = lf
## 是否在文件末尾插入空白行
insert_final_newline = true
## 是否删除一行中的前后空格
trim_trailing_whitespace = true

# 适用 .md 文件
[*.md]
insert_final_newline = false
trim_trailing_whitespace = false

.npmrc

npm、cnpm 包管理工具的配置项，设置代理之类的。

.npmrc

# 通过该配置兜底解决组件没有类型提示的问题
shamefully-hoist = true
# Proxy
# registry = https://registry.npm.taobao.org
https-proxy = socks5://127.0.0.1:10808
http-proxy = socks5://127.0.0.1:10808

Vscode

settings.json

{
  "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" },
  "[vue]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[jsonc]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[html]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[css]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[scss]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }
}

Git commit 规范

• feat: 增加新的业务功能
• fix: 修复业务问题/BUG
• perf: 优化性能
• style: 更改代码风格, 不影响运行结果
• refactor: 重构代码
• revert: 撤销更改
• test: 测试相关, 不涉及业务代码的更改
• docs: 文档和注释相关
• chore: 更新依赖/修改脚手架配置等琐事
• workflow: 工作流改进
• ci: 持续集成相关
• types: 类型定义文件更改
• wip: 开发中

完成一件事情，就提交一次 commit。而不是等到你写完一整天的代码后，才在下班前只提交一次。

vue-router 路由

CH Document：安装 | Vue Router

Install

pnpm add vue-router@4