Vue 3 + TypeScript 专业前端开发环境搭建指南

Vue 3 + TypeScript 专业前端开发环境搭建指南
目标
本指南旨在搭建一个功能完备、具备高度自动化和代码质量保障的前端开发环境。完成搭建后，将生成一个可直接用于项目开发的、可复用的“黄金模板”。
技术栈概览:
核心框架: Vue 3 (使用 Composition API)
语言: TypeScript
UI 框架: Bootstrap 5 & Bootstrap Icons
数据可视化: Apache ECharts
代码质量:
ESLint: 代码逻辑检查
Prettier: 代码风格格式化
Husky & lint-staged: Git 提交前自动化检查与格式化
前提条件
Node.js: 请确保已安装 v18 或更高版本的 Node.js。可在终端输入 node -v 查看。
VS Code: 推荐使用的代码编辑器。
VS Code 扩展 (关键！):
Vue Language Features (Volar): 为 Vue 3 提供语言支持。
Prettier – Code formatter: 用于自动格式化代码。
请确保禁用或卸载旧的 Vetur 扩展，以避免与 Volar 冲突。
第一部分：项目初始化与基础配置
使用 Vue 官方推荐的脚手架 create-vue 来初始化项目，它能帮我们预设好大部分配置。创建项目:
打开终端，执行以下命令：
npm create vue@latest

配置选项:
脚手架会以交互方式询问您需要开启哪些功能。请按照以下建议进行选择（使用方向键移动，空格键选中）：
Generated code
✔ Project name: › vue-pro-template (输入您的项目名，例如 vue-pro-template)
✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes (即使暂时不用，也建议添加)
✔ Add Vitest for Unit Testing? … No (可根据团队需求选择 Yes)
✔ Add an End-to-End Testing Solution? › No (可根据团队需求选择)
✔ Add ESLint for code quality? … Yes
✔ Add Prettier for code formatting? … Yes

进入项目并安装依赖:
cd vue-pro-template
npm install
至此，一个包含了 Vue 3、TS、Router、Pinia、ESLint 和 Prettier 的基础项目已经创建完毕。

第二部分：集成 UI 框架 (Bootstrap)
安装依赖:
npm install bootstrap bootstrap-icons
全局引入:
打开 src/main.ts 文件，在顶部引入 Bootstrap 的 CSS 和 JS 文件。
// src/main.ts

// 1. 引入 Bootstrap
import ‘bootstrap/dist/css/bootstrap.min.css’
import ‘bootstrap’
import ‘bootstrap-icons/font/bootstrap-icons.css’

// 2. 引入项目原有样式
import ‘./assets/main.css’

import { createApp } from ‘vue’
// … 后续代码保持不变
TypeScript

第三部分：集成数据可视化库 (Apache ECharts)
为了在 Vue 中更优雅地使用 ECharts，我们采用 vue-echarts 封装库。
安装依赖:
npm install echarts vue-echarts

创建 ECharts 插件 (按需引入):
在 src 目录下创建一个新文件夹 plugins，并在其中创建 echarts.ts 文件。这种方式可以有效减小最终打包体积。
src/plugins/echarts.ts:
Generated typescript
import { use } from “echarts/core”;
import { CanvasRenderer } from “echarts/renderers”;
import { BarChart, LineChart, PieChart } from “echarts/charts”;
import {
GridComponent,
TooltipComponent,
LegendComponent,
TitleComponent,
} from “echarts/components”;

// 按需引入 ECharts 图表和组件
use([
CanvasRenderer,
BarChart,
LineChart,
PieChart,
GridComponent,
TooltipComponent,
LegendComponent,
TitleComponent,
]);

全局注册 ECharts 组件:
再次打开 src/main.ts 文件，引入 ECharts 插件和 vue-echarts 组件。
src/main.ts (整合后):
Generated typescript
// Bootstrap
import ‘bootstrap/dist/css/bootstrap.min.css’
import ‘bootstrap’
import ‘bootstrap-icons/font/bootstrap-icons.css’
// …

// ECharts
import ECharts from ‘vue-echarts’
import ‘./plugins/echarts’ // 导入创建的插件文件

// …

const app = createApp(App)

// 全局注册 v-chart 组件
app.component(‘v-chart’, ECharts)

app.use(createPinia())
app.use(router)

app.mount(‘#app’)

第四部分：配置自动化代码质量体系
这是提升效率和代码质量的关键一步。
配置 Prettier:
项目根目录已生成 .prettierrc.json 文件。建议使用以下配置，它融合了通用最佳实践：
.prettierrc.json:
Generated json
{
“$schema”: “https://json.schemastore.org/prettierrc”,
“semi”: true,
“singleQuote”: true,
“printWidth”: 100,
“tabWidth”: 2,
“trailingComma”: “es5”
}

配置 ESLint 与 Prettier 协同:
项目脚手架已经帮我们做好了这一步，ESLint 的配置（通常是 .eslintrc.cjs）已经包含了与 Prettier 协同的规则。无需额外操作。
配置 Git 提交钩子 (Husky & lint-staged):
这将强制在每次 git commit 前自动检查和格式化代码。
安装依赖:
npm install –save-dev husky lint-staged

初始化 Husky:
npx husky-init

此命令会创建 .husky 目录并自动在 package.json 中添加 “prepare”: “husky install” 脚本。
配置 lint-staged:
打开 package.json 文件，在末尾添加以下配置：
Generated json
// package.json
{
// … 其他配置
“lint-staged”: {
“*.{js,ts,vue}”: “eslint –fix”
}
}
修改 pre-commit 钩子:
将 .husky/pre-commit 文件里的内容修改为：
Generated sh
#!/usr/bin/env sh
. “$(dirname — “$0″)/_/husky.sh”

npx lint-staged

第五部分：环境有效性验证
创建一个专门的测试页面来验证所有集成是否都正常工作。
创建测试视图:
在 src/views 目录下新建 TestView.vue 文件，并粘贴以下代码：
(此代码与之前验证代码一致)
Generated vue
<template>
<div class=”test-view”>
<div class=”container mt-4″>
<div class=”card”>
<div class=”card-header”>
<h2 class=”d-flex align-items-center”>
<i class=”bi bi-check2-circle me-2 text-success”></i>
环境集成测试
</h2>
</div>
<div class=”card-body”>
<p class=”card-text”>
如果下方所有元素都正常显示且功能正常，则环境已成功搭建！
</p>
<button class=”btn btn-primary” @click=”updateChartData”>
这是一个 Bootstrap 按钮 (点击更新图表)
</button>
<hr class=”my-4″>
<h4 class=”mb-3″>ECharts 图表测试</h4>
<div class=”chart-container p-3 border rounded”>
<v-chart class=”chart” :option=”chartOption” autoresize />
</div>
</div>
</div>
</div>
</div>
</template>

const chartOption = ref<EChartsOption>({
tooltip: { trigger: ‘axis’ },
legend: { data: [‘测试数据’] },
xAxis: {
type: ‘category’,
data: [‘周一’, ‘周二’, ‘周三’, ‘周四’, ‘周五’, ‘周六’, ‘周日’],
},
yAxis: { type: ‘value’ },
series: [{
name: ‘测试数据’,
type: ‘line’,
smooth: true,
data: [120, 132, 101, 134, 90, 230, 210],
}],
});

const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{
path: ‘/test’, // 定义测试页面的访问路径
name: ‘test’,
component: TestView
},
// … 其他路由
]
})
export default router

启动并验证:
运行 npm run dev。
在浏览器中访问 http://localhost:5173/test。
检查清单:
[ ] Bootstrap: 页面是否显示 Bootstrap 风格的卡片和蓝色按钮？图标是否显示？
[ ] ECharts: 折线图是否正常渲染？点击按钮后图表数据是否更新？
[ ] TypeScript: 在 TestView.vue 中，鼠标悬停在 chartOption 上是否显示类型？修改配置时是否有智能提示？
[ ] Husky:
在 TestView.vue 中随便加一个 console.log(“test”) 但不加分号。
执行 git add .
执行 git commit -m “test”
提交是否被阻止，并提示 ESLint 错误？
修复错误（或让 Prettier 自动修复）后，是否能成功提交？

第六部分：模板化与团队推广
验证无误后，就可以将这个项目作为团队的标准模板。
清理项目:
删除测试文件: src/views/TestView.vue。
清理测试路由: 删除 src/router/index.ts 中关于 /test 的路由。
（可选）清理 App.vue 和 views、components 目录下的默认内容，保留一个最干净的骨架。
（关键）删除 node_modules 文件夹。
（可选）删除 .git 文件夹，以便新项目初始化自己的版本历史。
保存模板:
将清理后的整个项目文件夹复制并重命名为 vue-pro-template，保存在团队共享的位置。
使用模板:
当需要开启新项目时：
复制 vue-pro-template 文件夹，重命名为新项目名称。
进入新项目目录，在终端执行 npm install。
执行 npm run dev，开始新项目的开发。

相关文章