简介面向需要快速搭建前台应用的前端开发者这份模板基于 Vue3、Vite、TypeScript 与 Pinia是一套企业级 Vue 前端工程模板。它将项目脚手架、目录结构、代码规范与常用依赖预先整合省去从零配置的时间适合团队统一技术栈或开发者快速启动新项目。压缩包共 125 个文件大小仅 1.05MB包含 43 个 TypeScript 源文件、13 个 Vue 组件、12 个 JavaScript 脚本、7 个 JSON 配置文件另有 SVG 图标、字体文件、样式表、Markdown 文档以及 Git 钩子等辅助资源目录结构清晰模块分工明确可直接替换成实际业务代码。目前已有 503 人学习下载。模板内置 Vite 热更新、Pinia 状态管理、Vue3 Composition API 组合式逻辑复用方案以及 TypeScript 类型检查同时提供 Prettier、ESLint、Stylelint 等规范配置并预设 commit-msg 与 pre-commit 钩子方便接入团队协作流程大幅减少工程化配置的重复劳动让开发者更专注于业务功能本身无论是中后台管理界面还是面向用户的 H5 页面都能基于此快速落地。1. 为什么 Vue3ViteTsPinia 模板能把搭建时间压到分钟级如果你以为这个模板只是把 create-vue 脚手架跑一遍再装个 Pinia那就低估它了。它真正的价值在于把企业级项目里“起步阶段最容易漏掉”的那批工程配置直接做成了文件.env 系列管环境切换commit-msg 管提交规范vue.code-snippets 管编码体感outfile.cjs 管构建产物整理。拿到压缩包解压、装依赖、改几个变量名一个带类型检查、提交校验、状态管理规范的前台应用骨架就能直接进入业务开发。适合两类人一类是要快速起后台管理系统或中后台前台应用的小团队另一类是打算把 Vue3 工程化最佳实践一次落地的开发者。Vite 的响应速度、TypeScript 的静态检查、Pinia 的数据流设计分别对应企业级应用最在意的三个点迭代速度、代码可靠性、复杂状态的可维护性。接下来按文件逐个拆讲清楚每个配置是干什么的、改坏了会发生什么。2. 模板结构与预配置拆解从目录骨架到 vue.code-snippets拿到压缩包先别急着pnpm dev先看它给了哪些文件。outfile.cjs、vue.code-snippets、commit-msg、.env.development、.env、.eslintignore、.gitignore、index.hbs这些文件各自管一块工程能力组合起来就是一套完整的团队协作基线。2.1 先看目录骨架再聊预设我一般先看目录结构再翻配置文件。这个模板的标准骨架大体如下和 create-vue 默认生成的结构相比多出来的都是为业务扩展预留的位置├── .env ├── .env.development ├── .eslintignore ├── .gitignore ├── commit-msg ├── index.hbs ├── outfile.cjs ├── vite.config.ts ├── src │ ├── api # 接口请求层 │ ├── components # 公共组件 │ ├── layouts # 布局组件 │ ├── stores # Pinia 状态模块 │ ├── utils # 工具函数 │ ├── views # 页面 │ ├── types # 全局类型声明 │ ├── env.d.ts # 环境变量类型声明 │ └── main.tssrc 下的模块划分遵循“约定优于配置”的思路api 层统一收敛请求views 只做页面组装stores 管理跨组件状态types 放全局类型。团队开发时不需要讨论“这个文件放哪”按目录进去就能找到。相比自己从零搭省掉的是每次新项目都要重复一遍的目录讨论和依赖选型。2.2 vue.code-snippets 为什么值得进版本库vue.code-snippets 是 VSCode 的 User Snippets 文件模板把它打进压缩包意味着每个成员拉下代码后就自动拥有同一套代码片段不需要各自去配置中心装插件。常见做法是定义一组以v3开头的前缀比如输入v3ts直接展开一个完整的script setup langts组件骨架{ Vue3 Script Setup Component: { scope: vue,typescript, prefix: v3ts, body: [ script setup lang\ts\, import { ref, computed } from vue, , defineOptions({ name: ${1:ComponentName} }), , const ${2:count} ref(0), const double computed(() ${2:count}.value * 2), /script, , template, div${1:ComponentName}/div, /template ], description: Vue3 TypeScript script setup SFC 基础骨架 } }这里三个关键参数scope限定片段在.vue和.ts文件里触发prefix是输入什么字符触发补全body里的${1:ComponentName}和${2:count}是 Tab 跳转位第一个先填组件名回车跳到第二个变量名。这种片段最大的作用不是省几行代码而是统一团队的组件写法所有人都用defineOptions声明组件名变量都用ref声明代码风格自然收敛。如果模板里没有这个文件新成员第一天写的组件和第二个月写的组件结构可能完全不同。2.3 index.hbs 和代码生成链路index.hbs 这种模板文件常见做法是配合 plop 或 hygen 做页面/组件生成器避免手动复制粘贴重复代码。模板里会在 package.json 里挂一个脚本比如generate:component: plop component执行后交互式询问组件名然后按模板生成文件。一段典型的 hbs 模板长这样script setup langts defineOptions({ name: {{pascalCase name}} }) /script template div class{{dashCase name}} slot / /div /template style scoped .{{dashCase name}} { /* styles */ } /style{{pascalCase name}}把输入转成大驼峰用作组件名{{dashCase name}}转成短横线用作 class。模板里预设这个文件说明作者在意的不是“生成文件”这个动作而是让所有新建页面保持统一命名。对后台管理系统这类大量重复 CRUD 页面的场景生成器能把每个页面的模板代码压缩到几秒钟。2.4 .eslintignore 与 .gitignore别把两者混为一谈两个文件都叫 ignore但控制的范围完全不同。模板里同时出现这两个文件是因为它们经常被搞混搞混的后果非常实际文件由谁读取不配置的后果.eslintignoreESLintlint 会扫 node_modules 和 dist编辑器卡顿lint 输出全是无关警告.gitignoreGitnode_modules、dist 被提交进仓库仓库体积膨胀克隆速度变慢.eslintignore 里一般写dist、node_modules、public让 lint 只关心源码.gitignore 里写node_modules、dist、*.local让版本库只保留源码和配置。判断一个文件该进哪个 ignore就看它是“离线产物”还是“运行时依赖”node_modules 是运行时依赖进 .gitignoredist 既是构建产物也是 lint 目标所以两个文件里都要出现。模板把这两个文件放在根目录属于开箱即用的工程底线。3. 环境变量与构建链.env、.env.development 和 outfile.cjs 的配合企业级应用最烦的场景之一是“开发环境能跑生产环境接口地址对不上”。模板用一组 env 文件把这个问题在源头拆掉再通过 vite.config.ts 和 outfile.cjs 把开发、构建、部署串成一条链。3.1 Vite 加载 .env 的顺序与 VITE_ 前缀机制Vite 启动时按模式读取 env 文件vite dev对应 development 模式vite build对应 production 模式。加载顺序是.env→.env.local→.env.[mode]→.env.[mode].local后面的覆盖前面。模板默认给了.env和.env.development一个放全局配置一个放开发环境覆盖项# .env 所有环境生效 VITE_APP_TITLEAdmin Pro VITE_APP_VERSION1.0.0 # .env.development 仅开发环境生效 VITE_API_BASE_URL/api VITE_USE_MOCKtrue变量名必须以VITE_开头才会暴露给客户端代码非VITE_前缀的变量只在 vite.config.ts 里通过loadEnv读取不会进import.meta.env。代码里通过import.meta.env.VITE_API_BASE_URL访问。如果后面需要生产环境单独一份配置就新建.env.production# .env.production VITE_API_BASE_URLhttps://api.example.com VITE_USE_MOCKfalse常见的坑是有人把NODE_ENV或自定义变量写进.env然后在业务代码里读不到——不是文件没生效是缺VITE_前缀Vite 默认不会把非前缀变量打进客户端。3.2 env.d.ts 给环境变量补类型加了VITE_APP_TITLE之后TS 里访问import.meta.env.VITE_APP_TITLE会提示属性不存在因为 Vite 自带的类型只声明了BASE_URL、MODE、DEV这几个内置字段。模板里的env.d.ts就是干这个的/// reference typesvite/client / interface ImportMetaEnv { readonly VITE_APP_TITLE: string readonly VITE_API_BASE_URL: string readonly VITE_USE_MOCK?: boolean } interface ImportMeta { readonly env: ImportMetaEnv }自定义变量全部要在ImportMetaEnv里声明?:表示可选。这个文件不配置的话TS 会报Property VITE_APP_TITLE does not exist。如果你在若依这类 Vue3TS 项目里遇到过同样的报错原因就在这不是 Vite 没读到变量是类型声明里没告诉 TS 这个变量存在。模板把这一层补齐等于把“环境变量可用但类型不可用”的隐患提前消除了。3.3 vite.config.ts 的 base 与 server.proxyvite.config.ts 里有两个配置项在部署阶段最容易被翻出来调。一个是base决定打包后资源引用的路径前缀另一个是server.proxy解决开发环境的跨域代理import { defineConfig } from vite import vue from vitejs/plugin-vue import { fileURLToPath, URL } from node:url export default defineConfig({ base: ./, plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)), }, }, server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true, }, }, }, })base: ./让打包产物里的 JS、CSS 引用变成相对路径。Windows 服务器上用 Nginx 部署 Vue3 项目时如果把 dist 放到非根路径的 location比如location /admin/而base写的/所有资源都会 404改成./或/admin/才能匹配实际访问路径。server.proxy则把开发环境里请求/api/login转发到http://localhost:8080changeOrigin: true会改写请求头里的 Host避免后端做域名校验时报 403。3.4 outfile.cjs 把产物整理到指定目录outfile.cjs 这个文件在压缩包里出现说明模板作者想把构建产物再做一次收口。常见做法是在vite build之后用 node 脚本把 dist 里的文件复制到预定目录比如带版本号的发布目录、或后端工程的 static 目录。一个最小实现长这样const { cpSync, mkdirSync } require(node:fs) const { resolve } require(node:path) const fromDir resolve(__dirname, dist) const toDir resolve(__dirname, output, webapp, Date.now().toString()) mkdirSync(toDir, { recursive: true }) cpSync(fromDir, toDir, { recursive: true }) console.log([outfile] dist copied - ${toDir})cpSync是 Node 16.7 之后提供的目录复制 APIrecursive: true才会递归复制子目录。用Date.now()生成时间戳目录线上可以保留多个发布版本回滚时直接切软链。模板在 package.json 里的构建脚本一般写成这样{ scripts: { build: vite build node outfile.cjs } }这样打完包自动多出一份带时间戳的产物省掉手动上传再改名的步骤。很多团队上线前还要做压缩、加水印、注入版本号这些都可以在这个阶段用同一个脚本串起来outfile.cjs 就是那个扩展口。4. Pinia 模块化状态管理与 TypeScript 类型闭环企业级数据流怎么落模板选 Pinia 而不是 Vuex不是跟风而是两者在 TypeScript 项目里的体验差距太明显。Pinia 删掉了 mutationsaction 里直接改 statestore 之间可以互相 import 组合类型推导从定义穿透到组件消费全程不需要手写类型体操。4.1 Pinia 与 Vuex 4 的取舍vue pinia vs vuex 是一个每次都要回答的选型问题。直观对比如下对比项Vuex 4Pinia同步修改 state必须走 mutationsaction 直接赋值TypeScript 推导需要手动声明 module 类型setup 语法天然推导多 store 组织modules 嵌套去深层取值靠 namespace每个 store 独立文件互相 importDevTools 支持Vue DevTools 支持原生支持时间旅行更顺滑Vuex 的 mutations 在团队协作里的实际价值是约束“修改入口”但代价是写一堆模板代码。Pinia 把约束从结构层移到类型层state 是ref、getters 是computed、actions 是普通函数TS 全部能推导。对企业级应用来说类型推导比手动规范更可靠因为机器检查不会疲劳。4.2 用 setup 语法定义 store模板里的 store 建议用 setup 语法写和组件的 Composition API 心智一致。以用户状态为例// src/stores/user.ts import { defineStore } from pinia import { ref, computed } from vue export interface UserInfo { id: number name: string avatar: string } export const useUserStore defineStore(user, () { const token refstring(localStorage.getItem(token) ?? ) const userInfo refUserInfo | null(null) const isLoggedIn computed(() token.value.length 0) async function login(username: string, password: string) { const res await fetch(/api/login, { method: POST, body: JSON.stringify({ username, password }), }) const data await res.json() token.value data.token localStorage.setItem(token, data.token) } async function fetchUserInfo() { const res await fetch(/api/user/info, { headers: { Authorization: Bearer ${token.value} }, }) userInfo.value (await res.json()) as UserInfo } function logout() { token.value userInfo.value null localStorage.removeItem(token) } return { token, userInfo, isLoggedIn, login, fetchUserInfo, logout } })defineStore第一个参数是 store idDevTools 里靠它区分实例第二个参数是一个函数函数里ref声明的就是 statecomputed是 getter普通函数是 action。token初始化时直接读 localStorage刷新页面不会丢登录态。isLoggedIn用 computed 派生组件里拿它控制路由跳转即可。4.3 组件消费、storeToRefs 与持久化组件里消费 store 要分清楚两个 API 的差异直接从 store 对象解构会丢失响应式必须用storeToRefs包一层script setup langts import { useUserStore } from /stores/user import { storeToRefs } from pinia const userStore useUserStore() const { token, userInfo } storeToRefs(userStore) const { login, logout } userStore async function handleLogin() { await login(admin, 123456) await userStore.fetchUserInfo() } /script template div v-ifuserInfo?.name欢迎回来{{ userInfo.name }}/div button v-else clickhandleLogin登录/button /templatestoreToRefs只对 state 和 getter 生效actions 直接解构不会丢 this 绑定。持久化有两条路简单场景手动读写 localStorage也就是 4.2 里 token 的写法复杂场景用一个 Pinia 插件统一处理配置里写key和paths指定要持久化的字段。模板没把持久化写死因为有些项目不需要硬塞进去反而多了无用的 localStorage 读写。4.4 类型闭环怎么检查TypeScript 的类型闭环体现在错误提前暴露fetchUserInfo返回的数据断言成UserInfo后模板里userInfo.name有补全提示后端字段名改成userName编译期就会爆红而不是运行时才发现。这套机制在模板里已经配好了strict: true拿到的 action 返回值也会被推导const result: AwaitedReturnTypetypeof userStore.fetchUserInfo这一行的意思是取fetchUserInfo这个 action 的函数类型提取它的返回值类型再解包 Promise。写一次后面接口调整时 TS 会把所有引用到该类型的地方全部标出来。Pinia 在这里承担的不只是状态管理它让 store 成为类型定义的唯一事实来源业务数据流从接口、store、组件贯穿一致。5. commit-msg 钩子与工程化细节模板里不那么显眼但决定体验的部分commit-msg 在压缩包的文件清单里很容易被当成 Linux 残留文件跳过实际上它决定了团队的 git 历史能不能看懂。解压后看不到它是因为钩子脚本要落在.git/hooks目录才生效模板里的 commit-msg 是一份原始脚本需要配合 husky 安装到当前仓库。5.1 commit-msg 在卡什么commit-msg 钩子在git commit执行前运行收到一个参数临时提交信息文件的路径。脚本读文件内容用正则校验格式。模板里常见的最小校验逻辑如下基于 Conventional Commits 规范#!/bin/sh message$(cat $1) pattern^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-z]\))?: . if ! echo $message | grep -qE $pattern; then echo commit-msg: invalid commit message format echo expected: type(scope): subject echo example: feat(user): add login action exit 1 fi$1是 Git 传入的提交信息文件路径cat $1读出完整信息grep -qE静默匹配符合规则返回 0不符合返回 1配合exit 1中断提交。类型限定在 feat、fix、docs、style、refactor、perf、test、chore 这八个常见词scope 可选比如fix(user): prevent duplicated submit。如果想快速跳过校验命令是git commit --no-verify但这种绕过应该是例外而不是常态——模板配好规则就是让默认路径走规范。5.2 验证模板工程化链路的一组自检命令配置对不对用一组命令验证比肉眼更可靠。装完依赖后依次执行pnpm install pnpm dev先确认开发服务器能起。pnpm dev起不来时先查 Node 版本Vite 4 需要 Node 14.18Vite 5 需要 Node 18模板 lock 文件锁定的版本决定了实际要求。接着验证构建链路pnpm build这一步会跑vite buildTS 类型检查如果没有单独挂在vue-tsc上至少要确认产物正常生成、outfile.cjs 复制出带时间戳的目录。最后验证 commit 校验git add . git commit -m test如果钩子生效这个提交会被拒绝终端输出invalid commit message format。改成git commit -m chore: test commit hook才能通过。最后一条自检是看历史git log --format%s每一行都是type(scope): subject的格式说明整条工程化链路已经完整跑通模板从环境变量、类型声明、状态管理到提交规范全部处于工作状态。本文还有配套的精品资源点击获取