Vue 3 + Vite 项目脚手架配置（精简实操）
1. 创建项目并初始化 Git
pnpm create vite # 选择 Vue + TypeScript（推荐）
cd <项目名>
git init
2. 设置镜像源（加速依赖安装）
pnpm config set registry https://registry.npmmirror.com
3. 安装所有开发依赖（Biome + 提交规范工具 + DevTools）
pnpm add -D @biomejs/biome husky lint-staged @commitlint/cli @commitlint/config-conventional commitizen cz-git vite-plugin-vue-devtools
4. 配置 Biome（代码检查/格式化）
pnpx @biomejs/biome init
修改 biome.json 为以下内容（根据团队习惯调整，此处使用您提供的完整配置）：
{
"$schema": "https://biomejs.dev/schemas/2.5.1/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true,
"defaultBranch": "master"
},
"files": {
"ignoreUnknown": false
},
"formatter": {
"enabled": true,
"indentStyle": "tab",
"lineWidth": 100,
"lineEnding": "lf"
},
"linter": {
"enabled": true,
"rules": {
"preset": "recommended",
"style": {
"useTemplate": "error",
"useConst": "error",
"useSelfClosingElements": "error",
"useNumberNamespace": "error",
"useNodejsImportProtocol": "error"
},
"suspicious": {
"noConsole": { "level": "warn", "options": { "allow": ["warn", "error"] } },
"noDoubleEquals": "error",
"noAssignInExpressions": "warn"
},
"complexity": {
"noForEach": "error",
"useSimplifiedLogicExpression": "error"
}
}
},
"javascript": {
"formatter": {
"quoteStyle": "double",
"trailingCommas": "all",
"semicolons": "always"
}
},
"css": {
"formatter": {
"enabled": true,
"quoteStyle": "double"
}
},
"assist": {
"enabled": true,
"actions": {
"source": {
"organizeImports": "on",
"useSortedKeys": "on",
"useSortedProperties": "on",
"useSortedAttributes": "on"
}
}
},
"overrides": [
{
"includes": ["**/*.vue"],
"linter": {
"rules": {
"correctness": {
"noUnusedImports": "off",
"noUnusedVariables": "off"
}
}
}
},
{
"includes": ["package.json"],
"assist": {
"actions": {
"source": {
"useSortedKeys": "off"
}
}
}
}
]
}
在 package.json 的 scripts 中添加：
"biome:check": "biome check src",
"biome:fix": "biome check --write src",
"biome:format": "biome format --write src"
5. 配置 Husky + lint-staged（提交前自动检查）
pnpm husky init
编辑 .husky/pre-commit 内容为：
pnpm lint-staged
编辑 .husky/commit-msg 内容为：
commitlint --edit $1
在 package.json 中添加 lint-staged 配置：
"lint-staged": {
"*.{js,ts,vue,css,json,md}": [
"biome check --write --no-errors-on-unmatched",
"biome format --write --no-errors-on-unmatched"
]
}
6. 配置 Commitlint + Commitizen（规范提交信息）
在项目根目录创建 commitlint.config.ts，填入您提供的完整配置（此处略，请沿用原内容）。
在 package.json 中添加 config.commitizen 字段：
"scripts": {
"commit": "git-cz",
"preinstall": "npx only-allow pnpm"
},
"config": {
"commitizen": {
"path": "cz-git"
}
}
在 tsconfig.node.json 中添加字段：
"include": ["vite.config.ts", "commitlint.config.ts"]
在 commitlint.config.ts 中添加字段：
// @see https://commitlint.js.org/#/reference-rules
export default {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
[
'feat', // ✨ 新增功能
'fix', // 🐛 修复缺陷
'docs', // 📝 文档变更
'style', // 🌈 代码格式
'refactor', // 🔄 代码重构
'perf', // 🚀 性能优化
'test', // 🧪 测试改动
'build', // 📦️ 构建/依赖变更
'ci', // ⚙️ CI 配置
'revert', // ↩️ 回滚
'chore', // 🛠️ 辅助工具
'wip', // 🚧 开发中
],
],
'subject-case': [0], // 不校验 subject 大小写
},
prompt: {
messages: {
type: '选择你要提交的类型:',
scope: '选择一个提交范围（可选）:',
customScope: '请输入自定义的提交范围:',
subject: '填写简短精炼的变更描述:\n',
body: '填写更加详细的变更描述（可选）。使用 "|" 换行:\n',
breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行:\n',
footerPrefixesSelect: '选择关联 issue 前缀（可选）:',
customFooterPrefix: '输入自定义 issue 前缀:',
footer: '列举关联 issue（可选）例如: #31, #I3244:\n',
generatingByAI: '正在通过 AI 生成你的提交简短描述…',
generatedSelectByAI: '选择一个 AI 生成的简短描述:',
confirmCommit: '是否提交或修改commit?',
},
types: [
{ value: 'feat', name: '特性: ✨ 新增功能', emoji: ':sparkles:' },
{ value: 'fix', name: '修复: 🐛 修复缺陷', emoji: ':bug:' },
{ value: 'docs', name: '文档: 📝 文档变更（更新 README 文件，或者注释）', emoji: ':memo:' },
{ value: 'style', name: '格式: 🌈 代码格式（空格、格式化、缺失的分号等）', emoji: ':lipstick:' },
{ value: 'refactor', name: '重构: 🔄 代码重构（不修复错误也不添加特性的代码更改）', emoji: ':recycle:' },
{ value: 'perf', name: '性能: 🚀 性能优化', emoji: ':zap:' },
{ value: 'test', name: '测试: 🧪 添加疏漏测试或已有测试改动', emoji: ':white_check_mark:' },
{ value: 'build', name: '构建: 📦️ 构建流程、外部依赖变更（如升级 npm 包、修改 vite 配置等）', emoji: ':package:' },
{ value: 'ci', name: '集成: ⚙️ 修改 CI 配置、脚本', emoji: ':ferris_wheel:' },
{ value: 'revert', name: '回退: ↩️ 回滚 commit', emoji: ':rewind:' },
{ value: 'chore', name: '其他: 🛠️ 对构建过程或辅助工具和库的更改（不影响源文件、测试用例）', emoji: ':hammer:' },
{ value: 'wip', name: '开发中: 🚧 开发阶段临时提交', emoji: ':construction:' },
],
issuePrefixes: [{ value: 'closed', name: 'closed: ISSUES has been processed' }],
},
}
7. 安装生产依赖（Pinia + Vue Router）
pnpm add -S pinia pinia-plugin-persistedstate vue-router
8. 配置 Vite 与 Vue DevTools
修改 vite.config.ts 和 tsconfig.app.json：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import VueDevTools from 'vite-plugin-vue-devtools'
// https://vite.dev/config/
export default defineConfig({
plugins: [
VueDevTools(), // 必须在 vue() 之前
vue()
],
resolve: {
tsconfigPaths: true // ← 新增，Vite 8 自动读取 tsconfig paths
}
})
{
"extends": "@vue/tsconfig/tsconfig.dom.json",
"compilerOptions": {
"paths": { "@/*": ["./src/*"] }, // ← 新增
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
"types": ["vite/client"],
"noUnusedLocals": true,
"noUnusedParameters": true,
"erasableSyntaxOnly": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}
9. 配置 Pinia（含持久化）和 Router
编辑 src/main.ts：
import { createApp } from "vue";
import "@/style.css";
import { createPinia } from "pinia";
import piniaPluginPersistedstate from "pinia-plugin-persistedstate";
import App from "@/App.vue";
import router from "@/router";
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);
createApp(App).use(pinia).use(router).mount("#app");
创建 src/router/index.ts：
import { createRouter, createWebHistory } from "vue-router";
import HelloWorld from "@/components/HelloWorld.vue";
const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{
component: HelloWorld,
name: "home",
path: "/",
},
],
});
export default router;
10. 验证配置
- 运行
pnpm biome:check检查代码。 - 运行
pnpm cz尝试交互式提交（需先git add）。 - 运行
pnpm dev启动开发服务器，右下角应出现 Vue DevTools 图标。