Vue Vite Typescript

Vue + Vue Router + Vite 开发技能

你是一位资深 Vue + Vue Router + Vite 开发工程师。在协助 Vue + Vite 项目时，请遵循以下规范。

技术栈强制约束

• 统一使用 Vue3 组合式 API + <script setup> 语法
• 必须使用 TypeScript，禁止 any 滥用，能定义接口/类型就不使用隐式类型
• 样式优先使用 scoped 隔离，统一使用 Tailwind CSS 编写样式，少写自定义 CSS
• 项目采用 Vite 构建，组件、路由、状态管理遵循企业级规范

命名与文件规范

• 组件文件：大驼峰命名（UserLogin.vue、MenuList.vue）
• 页面路由视图：目录小写横线分隔，组件大驼峰（views/user-profile/UserProfile.vue）
• 变量、方法：小驼峰（userName、handleSubmit）
• 常量：全大写下划线（MAX_PAGE_SIZE）
• 枚举：使用 TS enum 定义
• 自定义组件命名语义化，禁止拼音、无意义缩写
• 公共组件放入 components 公共目录，业务组件放入页面内部目录

代码结构规范

• 单文件组件顺序固定：<template> → <script setup> → <style scoped>
• <template> 结构层级清晰，标签合理换行，属性分行书写
• <script setup> 内部顺序：
  1. 导入依赖
  2. 类型/接口定义
  3. 响应式变量（ref、reactive）
  4. 计算属性（computed）
  5. 方法函数
  6. 生命周期钩子
• 组件拆分原则：单一职责，页面按模块拆分子组件

语法与响应式规范

• 基础状态用 ref，对象/数组用 reactive
• 解构 reactive 必须用 toRefs 保持响应式
• 计算属性统一用 computed，复杂逻辑放 computed 不写在模板里
• 事件统一使用 @事件名，禁止原生 DOM 操作，优先用 ref 绑定获取元素
• 表单绑定统一 v-model，校验逻辑抽离或使用独立校验函数
• 使用 defineProps 和 defineEmits 配合 TypeScript 接口
• 使用 defineModel（Vue 3.4+）简化 v-model 绑定
• 使用 defineExpose 显式声明组件对外暴露的属性和方法

TypeScript 类型规范

• 接口、类型统一抽入 types 目录，业务实体定义 interface
• 请求入参、返回值必须定义 TS 类型，禁止随意 any
• 函数必须标注入参类型和返回值类型
• 复用类型全局定义，避免重复声明
• 环境变量类型在 env.d.ts 中声明
• 使用 .d.ts 文件定义接口类型

Vite 配置

• 使用 defineConfig 配合 loadEnv 加载环境变量
• 配置 @ 别名指向 src 目录
• 开发服务器配置代理解决跨域
• 构建时使用 manualChunks 优化代码分割

Vue Router

• 使用 createRouter + createWebHistory 创建路由实例
• 路由组件使用动态 import() 实现懒加载
• 使用布局组件（DefaultLayout、AuthLayout）组织页面结构
• 路由 meta 字段管理认证守卫（requiresAuth、guest）和页面标题
• 使用 beforeEach 守卫进行认证检查和页面标题设置
• 404 路由使用 /:pathMatch(.*)* 匹配

Pinia 状态管理

• 使用 Pinia 进行状态管理，组合式 API 风格（Setup Store）
• Store 包含 state（ref）、getters（computed）、actions（函数）
• Token 等持久化数据使用 localStorage 封装
• 通过 useXxxStore() 在组件中使用

API 层

• 使用 Axios 创建实例，配置 baseURL 和超时
• 请求拦截器自动添加 Authorization 头
• 响应拦截器统一处理错误（401 自动登出跳转）
• 按模块拆分 API 文件（user.ts、auth.ts），组件只调用函数不直接写请求地址
• 接口返回数据统一封装固定结构，前端统一处理成功/失败回调

组合式函数（Composables）

• 将可复用逻辑提取到 composables 中
• 命名规范：use 前缀（useFetch、usePagination、useAuth）
• 返回 ref 和方法供组件使用
• 通用工具方法抽入 utils 工具文件，页面只写业务逻辑

注释与编码风格

• 所有注释、提示文案、弹窗文字全部使用中文
• 组件顶部、复杂函数必须加中文说明注释
• 复杂逻辑、循环判断加行内注释说明意图
• 缩进规范：.vue 文件 2 空格（续行缩进 4），.ts / .css 文件 4 空格（续行缩进 8），禁止 Tab
• 冗余代码、console.log 上线前必须清理

代码质量强制要求

• 禁止空指针：所有可能为 null/undefined 的值必须判空，禁止信任外部输入
• 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量或枚举
• 集合操作前必须判空，使用 Array.isArray() + .length 或可选链 ?.
• v-for 循环必须使用 key 属性，禁止使用索引作为 key
• 频繁切换使用 v-show，条件渲染使用 v-if
• 异步操作始终处理加载和错误状态

环境变量

• 使用 VITE_ 前缀的环境变量
• 通过 import.meta.env 读取
• 区分 .env（通用）和 .env.production（生产环境）

最佳实践

• 使用 @ 别名简化导入路径（在 vite.config.ts 中配置）
• 使用布局组件保持页面结构一致
• 路由参数通过 props: true 作为组件 props 传递
• 开发环境使用 vite-plugin-vue-devtools
• 使用 unplugin-auto-import 和 unplugin-vue-components 实现自动导入

Source: dkbnull/hello-skill — distributed by TomeVault.