【Vite+Vue3+TS】基于Vite+Vue3+TypeScript+ESLint+Prettier+Stylelint搭建项目（亲测超详细）

'# 【Vite+Vue3+TS】基于Vite+Vue3+TypeScript+ESLint+Prettier+Stylelint搭建项目（亲测超详细）

一、背景与问题

在现代前端开发中，项目构建效率、代码规范性和可维护性是决定开发质量的关键因素。传统基于Webpack的Vue2项目存在冷启动慢、配置复杂等痛点，而Vite通过原生ES模块的按需加载机制，实现了接近原生开发体验的构建速度。结合TypeScript的类型安全、ESLint的代码规范、Prettier的格式化以及Stylelint的CSS规范，可以构建一个全栈式开发环境。

本文将深入解析这一技术栈的协同机制，结合真实项目场景，展示如何通过合理配置实现零配置开发体验、自动代码规范校验、多环境适配等高级功能。

二、基本原理

1. Vite 架构原理

Vite 的核心思想是利用浏览器原生的ESM模块加载能力，在开发阶段无需打包即可直接使用模块。当需要构建时，才进行代码分割和打包。这种设计带来三个关键优势：

冷启动速度提升：无需等待打包，直接加载代码
热更新效率提升：仅更新修改的模块
多环境支持：支持浏览器、Node.js等不同运行环境

2. Vue3 响应式系统

Vue3 的响应式系统基于 Proxy 实现，相比 Vue2 的 Object.defineProperty 有三大改进：

深层响应性：自动追踪嵌套属性
性能优化：通过 Trackable 和 Triggerable 机制减少无效更新
API 简化：使用 ref 和 reactive 简化响应式数据处理

3. TypeScript 类型系统

TypeScript 通过类型注解和类型检查，在开发阶段提供以下保障：

类型安全：防止运行时类型错误
智能提示：IDE 自动补全和错误提示
代码可维护性：通过类型注解明确接口定义

4. ESLint + Prettier + Stylelint 协同机制

这三者形成完整的代码规范体系：

ESLint：语法检查和代码规范（如禁用 console.log）
Prettier：代码格式化（缩进、换行等）
Stylelint：CSS/SCSS 规范检查（如禁用未使用的样式）

三者通过 eslint-config-prettier 和 stylelint-config-prettier 实现规则兼容，避免格式化冲突。

三、环境准备

1. 系统要求

操作系统：Windows/Linux/macOS
Node.js：18.x（推荐 LTS 版本）
安装依赖：npm install -g typescript eslint prettier stylelint

2. 创建项目结构

mkdir vite-vue3-ts
cd vite-vue3-ts
npm init vite@latest

选择以下配置：

Framework: Vue
Language: TypeScript
UI Framework: None
CSS Preprocessor: None

四、核心实现

1. 项目配置文件

1.1 `tsconfig.json`（TypeScript 配置）

{
  "compilerOptions": {
    "target": "ES2021",
    "module": "ESNext",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "types": ["vite/client", "vite/server"]
  },
  "include": ["src"]
}

关键点解释：

target 设置为 ES2021 以支持现代 JS 特性
strict 启用严格模式，强制类型检查
outDir 指定输出目录，与 Vite 构建输出保持一致

1.2 `eslint.config.js`

import { defineConfig } from 'eslint-define-config';
import pluginVue from 'eslint-plugin-vue';

export default defineConfig({
  plugins: [pluginVue],
  rules: {
    'vue/multi-word-component-names': 0, // 允许单单词组件名
    'no-console': 'warn', // 警告 console.log 使用
    'no-debugger': 'error', // 禁止 debugger
  }
});

关键点解释：

使用 eslint-define-config 简化配置
no-console 规则可配置为 warn 或 error
no-debugger 强制禁用调试语句

1.3 `prettier.config.js`

module.exports = {
  printWidth: 80,
  tabWidth: 2,
  useTabs: false,
  semiColons: false,
  singleQuote: true,
  trailingComma: 'es5',
  bracketSpacing: true,
  arrowParens: 'always',
  endOfLine: 'auto'
}

关键点解释：

printWidth 控制每行最大字符数
singleQuote 使用单引号
trailingComma 控制尾随逗号

1.4 `stylelint.config.js`

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-prettier',
    'stylelint-config-sass-variables'
  ],
  rules: {
    'max-nesting-depth': 3, // 最大嵌套深度
    'no-empty-source': true,
    'no-duplicate-at-imports': true
  }
}

关键点解释：

使用 stylelint-config-standard 作为基础配置
stylelint-config-prettier 兼容 Prettier 格式
max-nesting-depth 控制 CSS 嵌套深度

五、完整案例

1. 创建一个完整项目结构

mkdir src
cd src
touch main.ts
touch App.vue

1.1 `src/main.ts`

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

createApp(App).mount('#app')

关键点解释：

使用 Vue3 的 createApp API
挂载到 #app 元素
遵循 Vue3 的模块化开发模式

1.2 `src/App.vue`

<template>
  <div id="app">
    <h1>{{ message }}</h1>
    <button @click="toggle">Toggle</button>
    <pre>{{ code }}</pre>
  </div>
</template>

<script lang="ts">
export default {
  data() {
    return {
      message: 'Hello Vite + Vue3 + TS',
      code: 'console.log("Hello World");'
    }
  },
  methods: {
    toggle() {
      this.message = this.message === 'Hello' ? 'Welcome' : 'Hello'
    }
  }
}
</script>

<style scoped>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  text-align: center;
  margin-top: 60px;
}
</style>

关键点解释：

使用 scoped 样式实现组件作用域
@click 事件绑定
data 返回对象，符合 Vue3 的响应式系统
使用 pre 标签展示代码片段

2. 配置文件整合

2.1 `.eslintrc.cjs`

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'prettier'
  ],
  rules: {
    'no-console': 'warn',
    'no-debugger': 'error'
  }
}

2.2 `.prettierrc`

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semiColons": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "auto"
}

2.3 `stylelint.config.js`

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-prettier',
    'stylelint-config-sass-variables'
  ],
  rules: {
    'max-nesting-depth': 3,
    'no-empty-source': true,
    'no-duplicate-at-imports': true
  }
}

六、源码解析

1. Vite 构建流程

Vite 的构建流程分为三个阶段：

开发服务器启动：通过 vite dev 命令启动开发服务器
模块加载：利用浏览器原生 ESM 加载模块
构建阶段：通过 vite build 生成生产环境代码

1.1 开发服务器启动

// node_modules/vite/dist/index.cjs
import { createServer } from 'vite'

const server = createServer({
  app: {
    // 配置项
  }
})

server.listen(3000, () => {
  console.log('Server is running on http://localhost:3000')
})

关键点解释：

使用 createServer 创建开发服务器
自动处理热更新和模块加载
支持多种插件系统

2. ESLint 集成机制

ESLint 与 Vite 的集成通过 @vitejs/plugin-eslint 插件实现：

// vite.config.ts
import vue from '@vitejs/plugin-vue'
import eslint from '@vitejs/plugin-eslint'

export default defineConfig({
  plugins: [
    vue(),
    eslint({
      config: 'eslint.config.js'
    })
  ]
})

关键点解释：

使用 eslint 插件进行代码检查
自动集成配置文件
支持实时检查和错误提示

七、进阶使用

1. 多环境配置

创建 env 目录并添加配置文件：

mkdir env
touch env/dev.env.ts
touch env/prod.env.ts

1.1 `env/dev.env.ts`

export default {
  API_URL: 'https://dev-api.example.com',
  DEBUG: true
}

1.2 `env/prod.env.ts`

export default {
  API_URL: 'https://api.example.com',
  DEBUG: false
}

1.3 在代码中使用环境变量

import { env } from './env'

console.log(env.API_URL)

关键点解释：

使用环境变量进行配置管理
通过 VITE_ 前缀暴露环境变量
支持动态环境切换

2. 自定义插件开发

创建 plugins 目录并添加自定义插件：

mkdir plugins
touch plugins/custom-plugin.ts

2.1 `plugins/custom-plugin.ts`

import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      name: 'custom-plugin',
      apply: 'build',
      transform(code, id) {
        if (id.includes('src/')) {
          return {
            code: code.replace('console.log', 'console.error'),
            map: null
          }
        }
      }
    }
  ]
})

关键点解释：

自定义插件可修改代码
apply 控制插件生效阶段
支持构建和开发阶段的差异化处理

八、性能与工程实践

1. 性能优化策略

1.1 启用 Tree Shaking

// vite.config.ts
export default defineConfig({
  build: {
    minify: true,
    sourcemap: false,
    terserOptions: {
      compress: true,
      mangle: true
    }
  }
})

关键点解释：

使用 Terser 进行代码压缩
启用 mangle 优化变量名
minify 控制是否压缩代码

1.2 使用 CDN 加速

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    include: ['vue', 'vue-router']
  }
})

关键点解释：

将常用依赖通过 CDN 加载
减少打包体积
提升首屏加载速度

2. 安全风险控制

2.1 Type Safety 配置

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true
  }
}

关键点解释：

strictNullChecks 防止 null/undefined 引发的错误
strictFunctionTypes 强制类型检查函数参数
提升类型安全性

2.2 ESLint 安全规则

// eslint.config.js
rules: {
  'no-script-url': 'error', // 禁止 script URL
  'no-prototype-builtins': 'error', // 禁止使用 Object.prototype 方法
}

关键点解释：

防止 XSS 攻击
避免潜在的原型污染
强化代码安全边界

九、常见问题与踩坑

1. 常见错误及解决办法

1.1 错误示例：忽略类型声明

// 错误代码
function add(a: number, b: number) {
  return a + b
}

问题分析：

缺少类型声明文件（.d.ts）
导致类型检查失效

解决办法：

// add.d.ts
declare function add(a: number, b: number): number;

1.2 错误示例：格式化冲突

# 报错：Prettier 与 ESLint 格式化规则冲突

问题分析：

未安装 eslint-config-prettier 和 stylelint-config-prettier
导致格式化规则不兼容

解决办法：

npm install --save-dev eslint-config-prettier stylelint-config-prettier

2. 常见问题分析

2.1 热更新失效

现象：修改代码后页面未更新

原因分析：

未正确配置 vite.config.ts
缺少必要的插件

解决办法：

// vite.config.ts
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue()]
})

2.2 类型检查不生效

现象：未触发类型错误提示

原因分析：

tsconfig.json 配置错误
未使用 --strict 模式

解决办法：

{
  "compilerOptions": {
    "strict": true
  }
}

十、最佳实践

1. 推荐实践方案

1.1 模块化开发

按功能划分模块
使用 @/ 前缀管理全局模块
遵循组件化开发模式

1.2 代码规范统一

使用 eslint + prettier 统一代码风格
配置 stylelint 统一 CSS 规范
设置 .eslintrc.cjs 和 .prettierrc 配置文件

1.3 环境配置分离

使用 env 目录管理不同环境配置
通过 VITE_ 前缀暴露环境变量
支持开发、测试、生产等多环境

2. 适用场景

新建现代前端项目
需要快速开发体验的项目
强调代码规范和可维护性的项目
团队协作项目

3. 不适用场景

传统单页应用（SPA）项目
老旧浏览器支持需求
需要复杂构建流程的项目
对性能要求极高的场景

十一、总结

本文深入解析了基于 Vite + Vue3 + TypeScript + ESLint + Prettier + Stylelint 的项目搭建方案，重点分析了各技术栈的协同机制和实际应用场景。通过三个完整的代码示例，展示了从项目初始化到规范配置的完整流程。

在实际开发中，这种方案能够显著提升开发效率，通过自动格式化、代码检查和规范统一，降低代码维护成本。同时，通过环境配置分离和插件扩展，能够适应不同项目需求。

需要注意的是，这种方案更适合现代化前端开发项目，对于需要复杂构建流程或特定浏览器兼容性的项目，需要进行相应的调整和优化。在使用过程中，要特别注意配置文件的正确性和插件的兼容性，避免出现格式化冲突和类型检查失效等问题。

通过合理的配置和实践，这种技术栈能够帮助开发团队构建出高效、规范、可维护的现代前端项目，是当前前端开发的首选方案之一。

一、背景与问题

二、基本原理

1. Vite 架构原理

2. Vue3 响应式系统

3. TypeScript 类型系统

4. ESLint + Prettier + Stylelint 协同机制

三、环境准备

1. 系统要求

2. 创建项目结构

四、核心实现

1. 项目配置文件

1.1 tsconfig.json（TypeScript 配置）

1.2 eslint.config.js

1.3 prettier.config.js

1.4 stylelint.config.js

五、完整案例

1. 创建一个完整项目结构

1.1 src/main.ts

1.2 src/App.vue

2. 配置文件整合

2.1 .eslintrc.cjs

2.2 .prettierrc

2.3 stylelint.config.js

六、源码解析

1. Vite 构建流程

1.1 开发服务器启动

2. ESLint 集成机制

七、进阶使用

1. 多环境配置

1.1 env/dev.env.ts

1.2 env/prod.env.ts

1.3 在代码中使用环境变量

2. 自定义插件开发

2.1 plugins/custom-plugin.ts

八、性能与工程实践

1. 性能优化策略

1.1 启用 Tree Shaking

1.2 使用 CDN 加速

2. 安全风险控制

2.1 Type Safety 配置

2.2 ESLint 安全规则

九、常见问题与踩坑

1. 常见错误及解决办法

1.1 错误示例：忽略类型声明

1.2 错误示例：格式化冲突

2. 常见问题分析

2.1 热更新失效

2.2 类型检查不生效

十、最佳实践

1. 推荐实践方案

1.1 模块化开发

1.2 代码规范统一

1.3 环境配置分离

2. 适用场景

3. 不适用场景

十一、总结

评论已关闭

推荐阅读

1.1 `tsconfig.json`（TypeScript 配置）

1.2 `eslint.config.js`

1.3 `prettier.config.js`

1.4 `stylelint.config.js`

1.1 `src/main.ts`

1.2 `src/App.vue`

2.1 `.eslintrc.cjs`

2.2 `.prettierrc`

2.3 `stylelint.config.js`

1.1 `env/dev.env.ts`

1.2 `env/prod.env.ts`

2.1 `plugins/custom-plugin.ts`