使用vite创建vue3项目及项目的配置

1.环境准备

使用vite搭建项目，vite需要nodejs版本14.18+、16+

• node v18.16.1
• pnpm 8.7.4

pnpm:performant npm(高性能的npm)由npm/yarn衍生而来，解决了npm/yarn内部潜在的bug，极大的优化了性能，扩展了使用场景。

pnpm安装指令

npm i -g pnpm

创建项目

pnpm create vite
cd # 进入项目
pnpm install # 安装依赖 + @vitejs/plugin-vue 4.3.4 + typescript 5.2.2 + vite 4.4.9 + vue-tsc 1.8.10
pnpm run dev # 运行项目

打开项目，需要手动在浏览器输入地址。
修改package.json文件的字段 "dev": "vite --open"，这样使用pnpm run dev命令会自动打开浏览器。

2.项目配置

VSCode 有对应插件Prettier - Code formatter、ESlint、Stylelint可以实现相同的功能

以下配置适用于协同开发的大项目配置。

ESLint校验代码工具配置 - js代码检测工具

eslint:提供一个插件化的javaScript代码检测工具

1.安装ESLint到开发环境 devDependencies

//完整写法
pnpm  install --save-dev eslint 
//简写
pnpm i eslint -D

2.生成配置文件:.eslint.cjs**

npx eslint --init

.eslint.cjs文件

// 对外暴露的配置对象
module.exports = {
    "env": { // eslint的工作环境
        "browser": true,
        "es2021": true // 校验js语法
    },
    "extends": [ //规则的继承
    	//全部规则默认是关闭的，这个配置项会开启推荐规则(推荐需要遵守的规则)
        "eslint:recommended",
        //vue3语法规则
        "plugin:@typescript-eslint/recommended",
        //ts语法规则
        "plugin:vue/vue3-essential"
    ],
    "overrides": [ //为特定类型的文件指定处理器
        {
            "env": {
                "node": true
            },
            "files": [
                ".eslintrc.{js,cjs}"
            ],
            "parserOptions": {
                "sourceType": "script"
            }
        }
    ],
    //指定解析器选项
    "parserOptions": {
        "ecmaVersion": "latest", //校验ECMA最新版本
        "parser": "@typescript-eslint/parser",//指定解析器，当前表示ts解析器，还可以选择Babel=ESLint babel解析器、默认Esprima解析器
        "sourceType": "module"// 设置为
    },
    // ESLint支持使用第三方插件，在使用插件之前，必须使用npm安装
    "plugins": [
        "@typescript-eslint",
        "vue"
    ],
    //ESLint校验规则
    "rules": {
    }
}

3.安装vue3环境代码校验插件**

# 让所有与prettier规则存在冲突的Eslint rules失效，并使用prettier进行代码检查
"eslint-config-prettier": "^8.6.0",
"eslint-plugin-import": "^2.27.5",
"eslint-plugin-node": "^11.1.0",
# 运行更漂亮的Eslint，使prettier规则优先级更高，Eslint优先级低
"eslint-plugin-prettier": "^4.2.1",
# vue.js的Eslint插件（查找vue语法错误，发现错误指令，查找违规风格指南)
"eslint-plugin-vue": "^9.9.0",
# 该解析器允许使用Eslint校验所有babel code
"@babel/eslint-parser": "^7.19.1",

# 指令
pnpm install -D eslint-plugin-import eslint-plugin-vue eslint-plugin-node eslint-plugin-prettier eslint-config-prettier eslint-plugin-node @babel/eslint-parser

4. 修改.eslintrc.cjs配置文件

module.exports = {
  //....
  /* 规则的状态
   * "off" 或 0    ==>  关闭规则
   * "warn" 或 1   ==>  打开的规则作为警告（不影响代码执行）
   * "error" 或 2  ==>  规则作为一个错误（代码不能执行，界面报错）
   */
  "rules": {
   // eslint（https://eslint.bootcss.com/docs/rules/）
   // key为规则，右侧为规则的状态
    'no-var': 'error', // 要求使用 let 或 const 而不是 var
    'no-multiple-empty-lines': ['warn', { max: 1 }], // 不允许多个空行
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
    'no-unexpected-multiline': 'error', // 禁止空余的多行
    'no-useless-escape': 'off', // 禁止不必要的转义字符

    // typeScript (https://typescript-eslint.io/rules)
    '@typescript-eslint/no-unused-vars': 'error', // 禁止定义未使用的变量
    '@typescript-eslint/prefer-ts-expect-error': 'error', // 禁止使用 @ts-ignore
    '@typescript-eslint/no-explicit-any': 'off', // 禁止使用 any 类型
    '@typescript-eslint/no-non-null-assertion': 'off',
    '@typescript-eslint/no-namespace': 'off', // 禁止使用自定义 TypeScript 模块和命名空间。
    '@typescript-eslint/semi': 'off',

    // eslint-plugin-vue (https://eslint.vuejs.org/rules/)
    'vue/multi-word-component-names': 'off', // 要求组件名称始终为 “-” 链接的单词
    'vue/script-setup-uses-vars': 'error', // 防止<script setup>使用的变量<template>被标记为未使用
    'vue/no-mutating-props': 'off', // 不允许组件 prop的改变
    'vue/attribute-hyphenation': 'off', // 对模板中的自定义组件强制执行属性命名样式
  },
}

5.生成ESLint忽略文件

文件名：.eslintignore
作用：设置不需要进行校验的文件夹

dist  // 打包文件
node_modules // 依赖文件

6.在package.json新增运行脚本

// 新增运行脚本
"scripts": {
	// ....
    "lint": "eslint src",  // 运行lint指令时，eslint校验src文件夹里面的文件
    "fix": "eslint src --fix", // 对于不符合规则的语法进行纠正
}

prettier配置 - 格式化检测工具

1.安装prettier依赖包

pnpm install -D eslint-plugin-prettier prettier eslint-config-prettier

2.prettierrc.json添加规则

创建prettierrc.json配置文件

{
  "singleQuote": true, // 使用单引号
  "semi": true,   //语句最后方的分号
  "bracketSpacing": true,
  "htmlWhitespaceSensitivity": "ignore",
  "endOfLine": "auto",
  "trailingComma": "all",
  "tabWidth": 2 //缩进占2个位置
}

3. 新建.prettierignore忽略文件

设置不需要格式化的文件夹

/dist/*
/html/*
.local
/node_modules/**
**/*.svg
**/*.sh
/public/*

4. 在package.json新增运行脚本

"scripts": {
	// ....
    "lint": "eslint src",  // 运行lint指令时，eslint校验src文件夹里面的文件
    "fix": "eslint src --fix", // 对于不符合规则的语法进行纠正
    "format": "prettier --write \"./**/*.{html,vue,ts,js,json,md}\"",
}

husky配置 提交代码前进行的操作

利用husky在代码提交之前触发git hook(git在客户端的钩子)，然后执行pnpm run format来自动的格式化我们的代码。

安装husky

pnpm install -D husky

执行npx husky-init 会在根目录下生成个一个.husky目录，在这个目录下面会有一个pre-commit文件，这个文件里面的命令在我们执行commit时执行。

前提是文件夹先git init 创建git追踪

在.husky/pre-commit文件添加如下命令

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
pnpm run format

配置commitlint 统一提交规范

利用commitlint统一commit信息的规范

pnpm add @commitlint/config-conventional @commitlint/cli -D

添加配置文件，新建commitlint.config.cjs(注意是cjs)，然后添加下面的代码：

module.exports = {
  extends: ['@commitlint/config-conventional'],
  // 校验规则
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',//新特性、新功能
        'fix',//修改bug
        'docs',//文档修改
        'style',//代码格式修改, 注意不是 css 修改
        'refactor',//代码重构
        'perf',//优化相关，比如提升性能、体验
        'test',//测试用例修改
        'chore',//其他修改, 比如改变构建流程、或者增加依赖库、工具等
        'revert',//回滚到上一个版本
        'build',//编译相关的修改，例如发布版本、对项目构建或者依赖的改动
      ],
    ],
    'type-case': [0],
    'type-empty': [0],
    'scope-empty': [0],
    'scope-case': [0],
    'subject-full-stop': [0, 'never'],
    'subject-case': [0, 'never'],
    'header-max-length': [0, 'always', 72],
  },
}

在package.json中配置scripts命令

# 在scrips中添加下面的代码
{
"scripts": {
    "commitlint": "commitlint --config commitlint.config.cjs -e -V"
  },
}

配置husky

npx husky add .husky/commit-msg 

在生成的commit-msg文件中添加下面的命令

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
pnpm commitlint

当 commit 提交信息时，必须是git commit -m 'type: xxx' 符合类型的才可以，需要注意的是类型的后面需要用英文的 :，并且冒号后面是需要空一格的，这个是不能省略的

3.项目集成

3.1 集成element-plus ui组件库

安装命令

#  @element-plus/icons-vue 为element-plus提供的图标组件库
pnpm install element-plus @element-plus/icons-vue

在main.ts入口文件引入element-plus ui组件库插件

import { createApp } from 'vue';
import App from './App.vue';

//引入element-plus插件与样式
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';


//获取应用实例对象
const app = createApp(App)

//安装ElementPlus插件
app.use(ElementPlus);

app.mount('#app');

全局配置国际化，在main.ts入口添加

// 以下的import会有波浪线，在build打包的时候会报错，所以添加@ts-ignore忽略当前文件ts类型的检测
//@ts-ignore
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
app.use(ElementPlus, {
    locale: zhCn
})

3.2 src文件夹别名配置

在正常项目下，文件的结构非常复杂。为了寻找文件简单，可以给src文件夹设置别名。利用src文件夹的别名，每次从src开始。

// vite.config.ts
import {defineConfig} from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
export default defineConfig({
    plugins: [vue()],
    resolve: {
        alias: {
            "@": path.resolve("./src") // 相对路径别名配置，使用 @ 代替 src
        }
    }
})

TypeScript 编译配置

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./", // 解析非相对模块的基地址，默认是当前目录
    "paths": { //路径映射
      "@/*": ["src/*"] 
    }
  }
}

在使用别名引入文件时，可能会有红色波浪线。这是因为vs code的Vetur插件对vue3兼容性不是太好，可以使用vue language feature替换

3.3 环境变量的配置

• 开发环境（development）：开发使用的环境，每位开发人员在自己的dev分支上干活，开发到一定程度，同事会合并代码，进行联调。
• 测试环境（testing）：测试同事干活的环境，一般会由测试同事自己来部署，然后在此环境进行测试。
• 生产环境（production）：生产环境是指正式提供对外服务的，一般会关掉错误报告，打开错误日志。(正式提供给客户使用的环境。)

注意:一般情况下，一个环境对应一台服务器。

项目根目录分别添加 开发、生产和测试环境的文件。

.env.development
.env.production
.env.test

配置环境变量

// .env.development
// 变量必须以 VITE_ 为前缀才能暴露给外部读取
NODE_ENV = 'development'
VITE_APP_TITLE = '后台管理系统'
VITE_APP_BASE_API = '/dev-api'

// .env.production
NODE_ENV = 'production'
VITE_APP_TITLE = '后台管理系统'
VITE_APP_BASE_API = '/prod-api'

通过import.meta.env获取环境变量

我这里可以打印，但是波浪线报错 没有env属性？

配置运行命令：package.json

 "scripts": {
    "dev": "vite --open",
    "build:pro": "vue-tsc && vite build --mode production",
  },

3.4 SVG图标配置

在开发项目的时候经常会用到svg矢量图，对页面性能有很大的提升。而且SVG文件比img要小的很多，放在项目中几乎不占用资源。

安装SVG管理插件

• 预加载 在项目运行时就生成所有图标,只需操作一次 dom
• 高性能 内置缓存,仅当文件被修改时才会重新生成

pnpm install vite-plugin-svg-icons -D

在vite.config.ts中配置插件

//引入svg需要用到插件
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'
export default () => {
  return {
    plugins: [
      // .....
      createSvgIconsPlugin({
        // svg图标的存储位置
        iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
        // Specify symbolId format
        symbolId: 'icon-[dir]-[name]',
      }),
    ],
  }
}

入口文件导入

import 'virtual:svg-icons-register'

测试：在vue文件中使用svg

// svg 标签相当于容器 use表示使用svg图标，xlink:href的属性值标识执行哪一个图标 #icon-xxx 这里的xxx是svg的图标名。fill属性表示填充的颜色。
// 这里不用引入，会去配置的src/assets/icons下找文件。
  <svg> //svg的width和height属性可以调节图标的大小
    <use xlink:href="#icon-phone" fill='red'></use>
  </svg>