详细的如何从零开始用Vite+Vue+TypeScript搭建一个企业级的项目

本文记录了详细的如何从零开始用Vite+Vue+TypeScript搭建一个企业级的项目的方法以及搭建路上遇到的问题及解决办法,如果你刚好也需要搭建这样一个项目的话我们就开始吧！

初始化项目

初始化的方法有很多种,可以根据实际情况选择不同的方式。

方法1

通过这个方法可以创建出一个vite1.x版本的项目,vite构建的项目默认为Vue3

// 快速搭建起一个Vue3项目
npm init vite-app <项目名称>   // 创建的是Vite 1.0版本

方法2

按照官网提示一步一步操作,通过这个命令构建出来的是Vite最新版的项目,执行完如下命名,按照提示步骤操作即可。

npm create vite@latest // 通过这个命令构建出来的是Vite最新版的项目

# 兼容性注意
Vite 需要 Node.js 版本 14.18+，16+。然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。

方法3 (推荐使用)

通过附加的命令行选项直接指定项目名称和你想要使用的模板。例如，要构建一个 Vite + Vue + ts 项目,运行如下命令即可:

npm init vite@latest <项目名称> --template vue-ts

启动项目如下图：

@types/node

由于typescript自身的机制,需要一份xx.d.ts声明文件,来说明模块对外公开的方法和属性的类型以及内容,所以在我们代码中出现如下代码可能会报错无法找到模块,但是声明又很麻烦。

import http from 'http'
let http = require('http')

所以在TypeScript 2.0以上的版本,为保证 node 的使用,我们可以安装官方提供的@types/node包，这个包包含Node.js的类型定义 (nodejs.org/).

npm i @types/node -s
// -D会安装在 devDependencies 开发环境所需要的
// -S会安装在 dependencies 生产环境所需要的

tsconfig.json

修改tsconfig.json文件,可以参考官网配置项,根据实际项目进行配置。

{
  "compilerOptions": {
    // 允许从没有设置默认导出的模块中默认导入。这并不影响代码的输出，仅为了类型检查。
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    // 解析非相对模块名的基准目录
    "baseUrl": ".",
    // 指定ECMAScript目标版本:最新版本
    "target": "ESNext",
    // 指定生成哪个模块系统代码:最新版本
    "module": "ESNext",
    // 决定如何处理模块:node
    "moduleResolution": "Node",
    // 启用所有严格类型检查选项。
    "strict": true,
    // 在 .tsx文件里支持JSX："React"或 "Preserve"
    "jsx": "preserve",
    // 将每个文件作为单独的模块
    "isolatedModules": true,
    // 编译过程中需要引入的库文件的列表可能的值
    "lib": ["ESNext", "DOM"],
    // 忽略所有的声明文件（ *.d.ts）的类型检查
    "skipLibCheck": true,
    // 模块名到基于 baseUrl的路径映射的列表。
    "paths": {
      "@/*": ["src/*"]
    },
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"]
}

vite.config.ts

当以命令方式运行 vite 时，vite 会自动解析项目根目录下 vite.config.js 的文件。配置不全时，在开发环境下运行都是正常的，但是打包上线的时候就会出现各种问题。更多详细的配置可以参考官网的配置项

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import * as path from "path";

export default defineConfig({
  resolve: {
    //设置别名
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  // 需要用到的插件数组
  plugins: [vue()],
  server: {
    // 项目启动时，是否在浏览器中在打开应用城区
    open: true,
    //启动端口
    port: 8080,
    // 热模块替换
    hmr: {
      host: "127.0.0.1",
      port: 8080,
    },
    // 设置 https 代理
    proxy: {
      "/api": {
        target: "你的http地址",
        changeOrigin: true,
        rewrite: (path: string) => path.replace(/^\/api/, ""),
      },
    },
  },
});

格式化代码

eslint

在实际开发中,由于是多人共同开发,每个人的编码习惯不同,为了编码的统一规范,所以就需要用到eslint(比如不能用var声明变量)。

插件安装

npm i eslint eslint-plugin-vue -D

由于 ESLint 默认使用 Espree (解析es6语法的解析器)进行语法解析,无法识别 TypeScript 的一些语法，故我们需要安装 @typescript-eslint/parser 替代掉默认的解析器。

npm i @typescript-eslint/parser -D

安装对应插件@typescript-eslint/eslint-plugin作为 eslint 默认规则的补充，提供了一些额外的适用于 ts 语法的规则。

npm i @typescript-eslint/eslint-plugin -D

插件配置

创建配置文件： .eslintrc.js 或 .eslintrc.json

module.exports = {
  parser: "vue-eslint-parser",
  parserOptions: {
    parser: "@typescript-eslint/parser",
    ecmaVersion: 2020,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,
    },
  },

  extends: [
    "plugin:vue/vue3-recommended",
    "plugin:@typescript-eslint/recommended",
  ],

  rules: {},
};

创建忽略文件：.eslintignore,这样在eslint在进行代码检查时会忽略这些文件

node_modules/
dist/

prettier

prettier规范的是代码偏向于排版层面上的风格,比如缩进长度,每句代码结束的分号使用等

安装

npm i prettier eslint-config-prettier eslint-plugin-prettier -D   

配置

创建配置文件： prettier.config.js 或 .prettierrc.js

module.exports = {
  printWidth: 120, //单行长度
  tabWidth: 2, //缩进长度
  useTabs: false, //使用空格代替tab缩进
  semi: false, //句末使用分号
  singleQuote: true, //使用单引号
  quoteProps: "as-needed", //仅在必需时为对象的key添加引号
  jsxSingleQuote: true, // jsx中使用单引号
  trailingComma: "all", //多行时尽可能打印尾随逗号
  bracketSpacing: true, //在对象前后添加空格-eg: { foo: bar }
  jsxBracketSameLine: true, //多属性html标签的‘>’折行放置
  arrowParens: "always", //单参数箭头函数参数周围使用圆括号-eg: (x) => x
  requirePragma: false, //无需顶部注释即可格式化
  insertPragma: false, //在已被preitter格式化的文件顶部加上标注
  proseWrap: "preserve", //默认值。因为使用了一些折行敏感型的渲染器（如GitHub comment）而按照markdown文本样式进行折行
  htmlWhitespaceSensitivity: "strict", //对HTML全局空白不敏感
  vueIndentScriptAndStyle: false, //不对vue中的script及style标签缩进
  endOfLine: "lf", //结束行形式
  embeddedLanguageFormatting: "auto", //对引用代码进行格式化
};

修改.eslintrc.js:增加如下配置

plugins: [ '@typescript-eslint', 'prettier'],

启动项目如果出现如下情况可以对package.json中的type值进行修改或者删除,重启项目/关闭项目重新打开。

pinia

安装pinia

npm i pinia

使用

新建 src/store/index.ts 目录

import { createPinia } from 'pinia'
const store = createPinia()
export default store

在main.js中引入并使用

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

// 创建vue实例
const app = createApp(App)
// 挂载pinia
app.use(store)
// 挂载实例
.mount('#app');

定义state: 在 src/store 下面创建一个 user.ts

import { defineStore } from 'pinia'
export const useUserStore = defineStore({
  id: 'user', // id必填，且需要唯一
  state: () => {
    return {
      name: '张三'
    }
  },
  actions: {
  updateName(name:string) {
    this.name = name
    }
  }
})

获取state在组件中使用

<template>
<div>{{ userStore.name }}</div>
</template>

<script lang="ts" setup>
import { useUserStore } from '@/store/user'
const userStore = useUserStore()
console.log(userStore.name);
// userStore.updateName('王五') 修改状态中的内容
</script>

vue-router

安装vue-router

npm i vue-router -S

使用vue-router

新建 src/router 目录并在其下面创建 index.ts，导出 router

import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'

const routes: Array<RouteRecordRaw> = [
  {
    path: '/login',
    name: 'login',
    meta: {
      title: '登录',
      keepAlive: true,
      requireAuth: false,
    },
    component: () => import('@/views/login/index.vue'),
  },
  {
    path: '/home',
    name: 'home',
    meta: {
      title: '首页',
    },
    component: () => import('@/views/home/index.vue'),
  },
]

const router = createRouter({
  history: createWebHistory(),
  routes,
})
export default router

在main.js中引入并使用

import router from '@/router'
....
app.use(router) // 挂载router

在App.vue中添加路由出口

<template>
  <router-view></router-view>
</template>

错误解决

在添加完src/router/index.js之后会出现报错如下图,这是因为找不到相应的类型声明,这个时候只需要在项目根目录或者src下创建一个.d.ts的类型注释文件,将如下代码粘贴进去即可,表示声明所有模块的.vue文件返回类型为defineComponent。

declare module '*.vue' {
  import { App, defineComponent } from 'vue'
  const component: ReturnType<typeof defineComponent>
  export default component
}

axios

Axios是一个基于promise的网络请求库,本质上也是对原生XHR的封装，只不过它是Promise的实现版本，符合最新的ES规范。

安装axios

npm i axios -D

使用axios

新建 src/utils/request.ts

import axios from 'axios'

const service = axios.create({
  headers: {},
  // 请求时长
  timeout: 1000 * 30,
  // 请求的base地址
  baseURL: 'http:xxx',
  // 表示跨域请求时是否需要使用凭证
  withCredentials: false,
})

// 接口请求拦截
service.interceptors.request.use(
  (config) => {
    return config
  },
  (error) => {
    return Promise.reject(error)
  },
)

// 接口响应拦截
service.interceptors.response.use(
  (config) => {
    return config.data
  },
  (error) => {
    return Promise.reject(error)
  },
)
export default service

定义接口新建src/api/index.ts,导入request开始定义接口

import request from '@/utils/request'

export function interfaceName(data?: any) {
  return request({
    url: '/api/xxxx', // url会和request中定义的baseURL拼接成地址
    method: 'get',
    params: data,
  })
}

定义完成就可以在页面进行使用了

<script lang="ts" setup>
import { interfaceName } from '@/api/index'
const clickFn = () => {
  interfaceName({ name: '测试一下接口' })
}
</script>

element-plus

安装插件

element-plus：UI样式库 unplugin-auto-import：为 Vite、Webpack、Rollup 和 esbuild 按需自动导入 API。支持 TypeScript。 unplugin-vue-components：Vue 的按需组件自动导入。

npm i element-plus -S
// 第三方包样式按需引入
npm i vite-plugin-style-import -D
npm i unplugin-vue-components unplugin-auto-import -D

使用

修改vite.config.ts,注意引入的顺序,也会导致项目无法启动等错误

......
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { createStyleImportPlugin, ElementPlusResolve } from 'vite-plugin-style-import'
......
plugins: [
  vue(),
  AutoImport({
    resolvers: [ElementPlusResolver()],
  }),
  Components({
    resolvers: [ElementPlusResolver()],
  }),
  // 自动导入element-plus样式，不配置的话，会出现ElMessage样式不生效问题
  createStyleImportPlugin({
    resolves: [ElementPlusResolve()],
    libs: [
      {
        libraryName: 'element-plus',
        esModule: true,
        resolveStyle: (name) => `element-plus/theme-chalk/${name}.css`,
      },
    ],
  }),
],
......

完成配置之后发现报错Error: Cannot find module 'consola',解决方案为安装如下插件,安装完成重启项目即可

npm i consola -D

husky和lint-staged

husky在进行代码的commit时,如果出现不规范的代码,commit就会自动停止报错,但是husky会将所有的代码都检查一遍,所以还需要安装lint-staged,作用是排除没有修改且被检查过的文件,让husky只检测修改了要提交的文件。

安装

npm i husky lint-staged -D
npx husky install // 手动启动,会生成一个.husky文件夹
npx husky add .husky/pre-commit // 生成.husky/pre-commit文件

配置

在package.json文件中添加如下配置:

"lint-staged": {
  "*.{js,vue,ts}": [
    "prettier --write"
  ],
  "*.{html,css,scss}": [
    "prettier --write"
  ]
}

修改pre-commit

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

npx --no-install lint-staged

使用

如果commit的时候出错,会出现如下图报错(SourceTree不行...)

项目地址

Git仓库地址,有什么需要改进的地方，敬请不吝赐教。

结语

至此,就完整的完成一个Vite + Vue + TypeScript的企业级项目的搭建,如果需要其他功能还可以按需进行增加,通过此次搭建还是学到了很多平时开发并不关注的内容！加油！