vue3+vite+ts+template 从零搭建项目脚手架

内容持续更新可查看 Notion 链接
推荐开发工具

VSCode + Volar

集成说明

• 技术栈：vue 3.x、vite 2.x、pinia 2.x、Vue Router 4.x、TypeScript 等
• 代码风格检查约束：ESLint + Prettier、husky + lint-staged
• 环境相关配置
• 浏览器兼容性
• …

搭建步骤

创建项目

1. yarn create vite
2. 选择 vue
3. 选择 vue-ts

代码风格约束

配置 ESLint

相关插件：

• eslint
• eslint-plugin-vue
• typescript-eslint/eslint-plugin]
• @typescript-eslint/parser

1. 安装插件

yarn add eslint --dev
# vue 官方 ESLint 插件，检查 .vue 文件中 <template>、<script>中的语法错误、指令等
yarn add eslint-plugin-vue --dev
# 让 Eslint 支持 TypeScript
yarn add @typescript-eslint/eslint-plugin --dev
# typescript parser
yarn add @typescript-eslint/parser --dev

2. 根目录新建 .eslintrc.js 文件，完整配置见最后。
3. 新建 .eslintignore 文件

ESLint默认忽略 /node_modules/* 和 /bower_components/* 中的文件

/dist

配置 Prettier

相关插件：

• prettier
• eslint-plugin-prettier
• eslint-config-prettier

1. 安装插件

yarn add prettier --dev
# 该插件将 prettier 配置的规则作为 eslint 的规则来检查我们的代码
yarn add eslint-plugin-prettier --dev

2. 新建 prettierrc.js，完整配置见最后。
3. 解决 prettier 与 eslint 冲突的规则

安装 eslint-config-prettier 插件，该插件可以禁用 prettier 与 eslint 冲突的相关规则

参考 eslint-plugin-prettier Recommended Configuration

3.1 安装 eslint-config-prettier

yarn add eslint-config-prettier --dev

3.2 .eslintrc.js 文件配置 extends，注意一定要把该条配置放置在 extends 最后面！！！

我们安装的 eslint-plugin-prettier 插件附带了一个 plugin:prettier/recommended 配置，帮我们配置好了 prettier 和解决了prettier 与 eslint 冲突的问题，所以我们只需要直接使用该配置就行，无需在再去配置 eslint-plugin-prettier 和 eslint-config-prettier

{
   "extends": [
      // ...其他配置
      "plugin:prettier/recommended" // 放在最后
   ]
}

配置 git commit 时检查

husky + lint-staged

参考：lint-staged Installation and setup

husky：它的主要作用就是关联git的钩子函数，在执行相关git hooks时进行自定义操作，比如在提交前执行eslint校验，提交时校验commit message等等。

lint-staged: 对暂存的 git 文件运行检测

直接运行命令，会生成一个 .husky 文件夹，会在package.json 文件 sciprts 添加一条 “prepare” 命令和 “lint-staged” 配置项

npx mrm@2 lint-staged

配置环境变量

加载的环境变量暴露 import.meta.env 对象上；vite官方文档-环境变量和模式

默认情况下，vite 提供两种环境模式

• dev 命令：development (开发) 模式
• build 以及 serve 命令：production (生产) 模式

我们在通过 --mode 参数定义 3 种模式来加载对应的.env 文件环境变量，运行/构建不同环境包：

• development => .env.development
• sit => .env.sit
• production => .env.production

步骤：

1. 新建.env 文件

• .env.development

# 本地开发环境变量
NODE_ENV=development
# 接口地址
VITE_API_URL='http://dev.com'

• .env.sit

# 测试环境变量
NODE_ENV=sit

VITE_API_URL='http://test.com'

• .env.production

# 生产环境变量
NODE_ENV=production

VITE_API_URL='http://production.com'

2. env.d.ts 文件添加声明，支持 TypeScript 的智能提示

interface ImportMetaEnv {
  readonly VITE_API_URL: string
  // 更多环境变量...
}

浏览器兼容性

默认情况下，Vite 的目标浏览器是指能够 支持原生 ESM script 标签 和 支持原生 ESM 动态导入 的。

若需要兼容传统浏览器，可以使用 vite 插件@vitejs/plugin-legacy 来支持。

它将自动生成传统版本的 chunk 及与其相对应 ES 语言特性方面的 polyfill。兼容版的 chunk 只会在不支持原生 ESM 的浏览器中进行按需加载。

1. 安装插件

yarn add @vitejs/plugin-legacy -D

2. vite.config.js 配置

// vite.config.js
export default defineConfig({
  // 根据需要兼容的浏览器自定义，示例：兼容 IE11
  plugins: [
    legacy({
      targets: ['ie >= 11'],
      additionalLegacyPolyfills: ['regenerator-runtime/runtime']
    })
  ]
})

css 相关

建议使用原生 css 变量 和实现 CSSWG 草案的 PostCSS 插件（例如 postcss-nesting）来编写简单的、符合未来标准的 CSS。

• https://github.com/jonathantneal/postcss-nesting 遵循 CSS 嵌套规范
• ‣ 跟 sass 一样的嵌套规则写法

若不听劝仍然要使用 css 预处理，Vite 也同时提供了对 .scss, .sass, .less, .styl 和 .stylus 文件的内置支持，只需要安装相应的依赖即可。例如使用 sass

# .scss and .sass
yarn add sass -D

路由配置

1. src 目录下新建 router 文件夹
2. router 文件夹下新建 index.ts 文件

import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'
const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'HelloWorld',
    // 注意导入要带上文件后缀.vue，否则 ts 会报错找不到相应模块
    component: () => import('@/views/HelloWorld.vue')
  }
]

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

export default router

3. main.ts 导入路由

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

const app = createApp(App)

app.use(router)

app.mount('#app')

Axios 请求封装

文件路径 src/utils/request.ts

状态管理 Pinia

官方文档

特点：

• 直观，像定义组件一样地定义 store，并且能够更好地组合它们；
• 完整的 Typescript 支持；
• 关联 Vue Devtools 钩子，提供更好地开发体验；
• 模块化设计，能够构建多个 stores 并实现自动地代码拆分；
• 极其轻量（1kb），甚至感觉不到它的存在 ；
• 同时支持同步和异步 actions；

使用步骤：

1. 安装 yarn add pinia
2. 在 src/main.ts 下定义引用 pinia 插件

import { createPinia } from 'pinia'

app.use(createPinia())

3. 新建 store 文件夹，在 store 下新建 index.ts，state 必须是箭头函数，保证 ts 能完成的进行类型推断

import { defineStore } from 'pinia'
export default defineStore({
  id: 'app', // store id, 必填且必须唯一
  state: () => {
    return {
      title: 'vue3-vite-ts'
    }
  }
})

就可以在组件中使用了

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

<script setup lang="ts">
import useAppStore from "@/store"
const store = useAppStore()
</script>

修改 store 数据，可以直接 store.xxx = xxx, 也可以使用 store.$patch、actions

其他配置

vite 常用配置

配置别名

import { defineConfig } from 'vite'
import { resolve } from 'path'

export default defineConfig({
  ...
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src')
    }
  }
})

配置代理

示例：

// vite.config.ts
{
    // ...
    server: {
        proxy: {
            target: 'http://api.xxx',
            changeOrigin: true,
            rewrite: (path) => path.replace(/^\/api/, '')
        }
    }
}

sourcemap & console\debugger

构建打包时，vite 配置项 build.sourcemap 默认为 false，即不会生成 source map 文件，如果我们需要根据环境去判断构建后是否生成 source map 文件，可以如下示例配置：

// vite.config.js
export default defineConfig(({ mode }) => {
   const IS_PROD = mode === 'production'
    return {
        build: {
          // 生产环境关闭 sourcemap
          sourcemap: !IS_PROD,
          terserOptions: {
            compress: {
              // 去除 console、debugger
              drop_console: !IS_PROD,
              drop_debugger: true
            }
          }
        }
    }
})

可视化打包结果

rollup-plugin-visualizer

推荐

工具库

• VueUse: vue3 hooks 库，提供了一些常用的基于 Composition API 的函数集合。

vite 插件

@vitejs/plugin-legacy

为打包后的文件提供传统浏览器兼容性支持

完整文件

.eslintrc.js

module.exports = {
  env: {
    browser: true,
    node: true,
    es2021: true,
    'vue/setup-compiler-macros': true
  },
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: '@typescript-eslint/parser',
    ecmaVersion: 2021,
    sourceType: 'module',
    ecmaFeatures: {
      jsx: true
    }
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended'
  ],
  // eslint-plugin-vue @typescript-eslint/eslint-plugin 的缩写
  plugins: ['vue', '@typescript-eslint'],
  rules: {}
}

.prettierrc.js

module.exports = {
  semi: false, // 结尾分号
  trailingComma: 'none', // 在对象或数组最后一个元素后面是否加逗号
  arrowParens: 'always', // 箭头函数，单个参数添加括号
  endOfLine: 'lf', // 行尾符
  tabWidth: 2, // tab键缩进宽度
  singleQuote: true, // 使用单引号
  printWidth: 100, // 指定代码长度，超出换行
  jsxSingleQuote: true,
  jsxBracketSameLine: true
}

问题解决

1. eslint 报错：prettier 配置好后，eslint 检查不生效报错

排除 eslint 跟 prettier 的配置冲突的原因之外，可以关闭重新打开项目。

2. ts 报错 ：找不到模块“xxx”或其相应的类型声明

tsconfig.json 配置，配置基本目录 baseUrl 以及 paths，解析非绝对模块路径

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/": ["src/*"]
    }
}

参考：tsconfig.json - paths

github仓库地址

https://github.com/jizai1125/vue3-vite2-ts-template