工程脚手架5 分钟搭出标准项目结构脚手架不是炫技是规范。一个结构清晰、配置合理的工程能让后续所有开发事半功倍。这篇文章带你用 Vite 在 5 分钟内搭出一个符合企业标准的 Vue 3 Element Plus 工程。一、为什么不用 vue-cli在 Vue 3 时代创建项目有两个主流选择vue-cli和Vite。我毫不犹豫地选了 Vite原因有三1. 速度碾压vue-cli基于 Webpack启动一个开发服务器要等十几秒改一行代码热更新HMR要等 1-2 秒。Vite 基于浏览器原生 ES Module esbuild 预构建冷启动通常在 300ms 以内HMR 几乎是改完即所见。对于一天要改几百次代码的前端来说每次保存后等 1 秒和等 0.1 秒的差距累积起来就是一天少等半小时。2. Vue 3 官方推荐Vue 官方文档明确推荐 Vite 作为构建工具。create-vueVue 官方的脚手架底层就是 Vite。用官方推荐的工具意味着踩坑时更容易找到官方文档和社区解答。3. 配置更简洁Webpack 的配置动辄几百行loader、plugin、resolve 各种概念。Vite 的配置是约定优于配置——大部分场景零配置就能跑需要定制时改vite.config.js即可语法也更直观。二、项目初始化打开终端执行三行命令# 用 Vite 官方模板创建项目npmcreate vitelatest pipe-network-tool ----templatevue# 进入项目目录cdpipe-network-tool# 用 pnpm 安装依赖比 npm 快磁盘占用更小pnpminstallnpm create vitelatest会交互式地问你项目名称、框架、变体。加上-- --template vue参数直接跳过交互用 Vue 3 的纯 JS 模板创建。创建完成后目录结构是这样的pipe-network-tool/ ├── index.html # 入口 HTML ├── package.json # 依赖与脚本 ├── vite.config.js # Vite 配置 ├── .gitignore └── src/ ├── main.js # 应用入口 ├── App.vue # 根组件 └── assets/ # 静态资源此时执行pnpm dev一个最基础的 Vue 3 应用就能跑起来了。但离企业级后台还差得远——接下来要装依赖、配别名、建目录、接 Element Plus。三、关键依赖一个空模板只有vue和vite两个核心依赖。企业级后台需要补齐以下依赖。我直接给出package.json的关键部分{dependencies:{vue:^3.4.0,vue-router:^4.2.5,pinia:^2.1.7,element-plus:^2.4.4,element-plus/icons-vue:^2.3.1,axios:^1.6.2,mockjs:^1.1.0},devDependencies:{sass:^1.69.0}}逐个说明为什么需要它们依赖作用是否必需vue核心框架必需vue-router路由管理多页面跳转必需pinia状态管理跨组件共享数据必需element-plusUI 组件库必需element-plus/icons-vueElement Plus 图标集推荐axiosHTTP 请求对接 Mock / 真实后端必需mockjs生成 Mock 数据演示用演示项目必需sassSCSS 编译Element Plus 主题覆写需要必需安装命令pnpmaddvue-router pinia element-plus element-plus/icons-vue axios mockjspnpmadd-Dsass注意vue、vite已经在创建模板时装好了不需要重复安装。四、vite.config.js 配置默认的vite.config.js几乎是空的。我做了三处关键配置import{defineConfig}fromviteimportvuefromvitejs/plugin-vueimport{fileURLToPath,URL}fromnode:urlexportdefaultdefineConfig({plugins:[vue()],resolve:{alias:{// 把 指向 src 目录避免写一长串相对路径:fileURLToPath(newURL(./src,import.meta.url))}},server:{port:5173,// 开发服务器端口open:true,// 启动后自动打开浏览器host:0.0.0.0// 允许局域网访问方便手机/其他设备调试},css:{preprocessorOptions:{scss:{// 全局注入 SCSS 变量所有 .vue 文件无需手动 importadditionalData:use /styles/variables.scss as *;}}}})4.1别名没有别名时从src/views/ApiRegistry.vue引入一个工具函数要写import{formatTime}from../../utils/format有了别名无论文件在哪一层都写import{formatTime}from/utils/format深层嵌套的组件里这个别名能省下大量../../的烦恼。4.2 SCSS 全局变量预注入css.preprocessorOptions.scss.additionalData这一行很关键。它让variables.scss里的所有 SCSS 变量自动注入到每个.vue文件的style langscss中不需要在每个文件里写use /styles/variables.scss。踩坑提示这里用的是use ... as *不是老式的import。Sass 官方已弃用import新项目一律用use。五、目录规范依赖装好了接下来是目录结构。这是整个项目骨架中的骨架。src/ ├── api/ # 接口请求层封装 axios按模块分文件 │ ├── apiManage.js │ ├── modelGather.js │ └── modelPublish.js ├── components/ # 通用组件AppTable、AppDialog 等 │ ├── AppTable.vue │ ├── AppDialog.vue │ └── AppPagination.vue ├── layout/ # 布局组件主框架 │ ├── MainLayout.vue │ ├── TopBar.vue │ └── SideNav.vue ├── views/ # 页面级组件每个路由对应一个 │ ├── login/ │ ├── api-manage/ │ ├── model-gather/ │ └── model-publish/ ├── router/ # 路由配置 │ └── index.js ├── store/ # Pinia 状态管理 │ ├── api.js │ └── user.js ├── styles/ # 全局样式 │ ├── tokens.css │ ├── variables.scss │ ├── element-override.scss │ └── global.css ├── mock/ # Mock 数据 │ ├── apiManage.js │ └── index.js ├── utils/ # 工具函数 │ ├── format.js │ └── request.js └── data/ # 静态数据常量、枚举、配置 └── constants.js为什么这样分每个目录都有明确的职责边界避免代码乱放api/vsutils/request.jsrequest.js是 axios 实例和拦截器通用能力api/下是按业务模块封装的具体接口业务语义。components/vsviews/components/是可复用的积木不绑定具体业务views/是用积木搭出来的房间绑定具体路由和业务。store/vsapi/api/负责取数据store/负责存数据并跨组件共享。data/vsmock/data/是写死的常量比如状态枚举映射表mock/是模拟接口返回的动态数据。这套目录规范不是我拍脑袋想的——它来自对十几个企业级 Vue 项目的观察总结。遵循它新成员接手项目时不需要问这个文件该放哪因为约定已经写在了目录结构里。六、main.js 关键配置src/main.js是应用的入口所有全局能力在这里装配import{createApp}fromvueimport{createPinia}frompiniaimportElementPlusfromelement-plusimportelement-plus/dist/index.cssimportzhCnfromelement-plus/es/locale/lang/zh-cnimportAppfrom./App.vueimportrouterfrom./router// 样式导入顺序很重要// 1. Element Plus 默认样式importelement-plus/dist/index.css// 2. 设计 Token定义 CSS 变量import/styles/tokens.css// 3. Element Plus 主题覆写消费 Tokenimport/styles/element-override.scss// 4. 全局自定义样式import/styles/global.cssconstappcreateApp(App)app.use(createPinia())// 安装 Piniaapp.use(router)// 安装路由app.use(ElementPlus,{locale:zhCn})// 安装 Element Plus 中文语言包app.mount(#app)6.1 中文 locale 是必选项Element Plus默认是英文。分页器的上一页/下一页、日期选择器的月份、表单校验的提示语默认都是英文。加上locale: zhCn才能让组件显示中文——这是新手最容易漏掉的一步也是项目总结里踩过的 10 个坑的第一名。6.2 样式导入顺序前面提过样式导入顺序不能乱Element Plus 默认样式 → Token 定义 → Element Plus 覆写 → 全局样式。如果覆写在 Token 之前CSS 变量还没定义覆写会失效。七、常见踩坑搭脚手架阶段有三个高频坑提前说明能省你两小时坑 1路径别名需要 vite tsconfig 双重配置如果你用 TypeScript别名除了在vite.config.js里配还要在tsconfig.json里配paths否则 TS 类型检查会报找不到模块{compilerOptions:{baseUrl:.,paths:{/*:[src/*]}}}本项目用 JS所以只配 vite 即可。但如果你后续加 TS项目总结里提到的后续可以做什么第一条记得补这一处。坑 2SCSS 全局变量需要 vite 预配置如果你在.vue文件的style langscss里用了$primary-color这样的 SCSS 变量但没在vite.config.js里配additionalData会报Undefined variable。解决方式就是第四节里的css.preprocessorOptions.scss.additionalData配置。配好之后所有 SCSS 变量自动可用。坑 3Element Plus 按需引入 vs 全局引入的取舍app.use(ElementPlus)是全局引入——简单但首屏体积大约 1MB。对于演示原型全局引入完全够用开发体验最好。如果要优化体积见第 12 篇性能优化可以改用unplugin-vue-componentsunplugin-element-plus做按需引入。但按需引入 主题覆写组合时必须用unplugin-element-plus而不是手动 import 样式否则覆写会失效。我的建议原型阶段用全局引入先把功能跑通交付前再做按需引入优化。不要一上来就追求最优雅的方案——过早优化是万恶之源。八、验证脚手架全部配置完成后写一个简单的App.vue验证一下template el-config-provider el-button typeprimary测试主色按钮/el-button el-table :data[] stylemargin-top: 16px el-table-column propname label名称 / /el-table /el-config-provider /template script setup // 如果按钮是 #0073FB我们的主色说明主题覆写生效了 // 如果按钮文字是中文说明 locale 生效了 /script打开浏览器看到蓝色主按钮 中文界面脚手架就搭好了。九、小结规范比代码本身更重要脚手架搭完项目还一行业务代码都没写但已经具备了清晰的目录规范每个文件该放哪统一的路径别名不用写../../设计系统接入Token Element Plus 覆写全局能力装配路由、状态、组件库、中文这些看不见的基础设施决定了后续开发的顺畅程度。一个规范的项目新成员第一天就能找到文件、看懂结构、提交代码一个混乱的项目每个人都在这个组件放哪为什么样式不生效上浪费时间。脚手架的价值在于它把团队的默契变成了代码的约定。上一篇04 - 设计系统从设计稿到 CSS 变量下一篇预告脚手架就位下一步是主布局——顶栏 侧栏 内容区的工程化设计。后台系统的骨架是怎么搭起来的