一个完整的前端vue工程结构模板

创建项目前完整前置准备工作：从安装 Node.js，VS Code 开始

一、第一步：下载安装 Node.js（必须）

1. 下载地址

官网：https://nodejs.org/ 推荐选择 LTS 长期支持版（稳定版，不要选 Current 最新尝鲜版）

2. 安装注意事项（Windows / Mac）

Windows：一路默认下一步，一定要勾选 Add to PATH（自动配置环境变量）
Mac：.pkg 安装包直接默认安装即可
安装完成后，打开终端（CMD/PowerShell/ 终端）验证是否安装成功

javascript 复制代码

# 查看node版本
node -v
# 查看npm版本
npm -v

出现版本号即安装成功。

版本建议

Node >= 18.0.0（Vite4/Vite5 最低要求 Node14.18+，推荐 18、20 LTS）
npm 会随 Node 自带安装，无需单独装

二、第二步：配置 npm 淘宝镜像（解决下载依赖慢、失败）

默认 npm 是国外源，国内下载极易超时报错，必须切换国内镜像。

方式 1：全局切换淘宝镜像（推荐）

javascript 复制代码

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 校验是否设置成功
npm config get registry
# 返回 https://registry.npmmirror.com 代表成功

方式 2：安装 cnpm（可选备用）

javascript 复制代码

npm install -g cnpm --registry=https://registry.npmmirror.com
# 之后可以用 cnpm install 代替 npm install

三、第三步：全局安装常用工具（可选但建议装）

1. 升级 npm 到最新稳定版

javascript 复制代码

npm install -g npm

2. 全局安装 yarn（可选，包管理工具，备用）

javascript 复制代码

npm install -g yarn

# 验证
yarn -v

3. 全局安装 vite 脚手架（不装也可以，create vite 临时会下载）

javascript 复制代码

npm install -g create-vite

4. 全局安装 eslint、prettier（团队规范格式化，可选）

javascript 复制代码

npm install -g eslint prettier

四、第四步：配置系统全局缓存路径（Windows必做，解决C盘爆满）

默认 npm 全局依赖、缓存都存在 C 盘用户目录，时间久会占用大量 C 盘空间，建议修改全局路径：

在非 C 盘新建两个文件夹：
1. D:\node\npm_global（全局包存放）。
2. D:\node\npm_cache（缓存文件）。
终端执行配置命令：

javascript 复制代码

npm config set prefix "D:\node\npm_global"

npm config set cache "D:\node\npm_cache"

配置系统环境变量

把 D:\node\npm_global 配置到系统环境变量 PATH 中，否则全局命令无法使用。
1. 环境变量，找到变量 Path，选中后点【编辑】，
2. 找到旧路径：C:\Users\用户名\AppData\Roaming\npm，选中删除这一行
3. 点击【新建】，粘贴路径：D:\node\npm_global
4. 点击【上移】，把这一行路径移动到列表最顶部（避免路径冲突）
5. 系统变量补充配置（可选但建议配置）：在 系统变量 区域，点击【新建】
  1. 变量名：NODE_PATH
  2. 变量值：D:\node\npm_global\node_modules

6.验证配置是否成功

关闭所有已打开的 CMD、PowerShell、Git Bash 窗口（必须重启终端才生效），

重新打开终端，执行命令：npm config get prefix；

返回 D:\node\npm_global 代表路径配置成功

7.全局命令测试：create-vite -v

方式 1：npx 临时查询（推荐，不用进项目）npx create-vite --version

方式 2：查看全局安装包版本 npm list create-vite -g

方式 3：先退出当前创建流程，再执行查询

五、第五步：终端工具选择与文件夹准备

新建项目存放文件夹（不要用中文、空格、特殊字符）错误示例：D:\前端项目\vue项目 正确示例：D:\code\vue-project
在文件夹地址栏输入 cmd 回车，直接在当前目录打开终端，不用频繁 cd 切换路径

六、第六步：Git 安装（必须，代码版本管理）

1. 下载 Git：https://git-scm.com/

默认安装即可，安装后验证：

javascript 复制代码

git --version

2. 全局配置用户名 + 邮箱（第一次使用 Git 必须配置）

javascript 复制代码

git config --global user.name "姓名/昵称"
git config --global user.email "邮箱（GitHub/Gitee注册邮箱）"

# 查看配置
git config --global --list

3. 可选：配置 SSH 密钥（拉取推送 Gitee/GitHub 代码免密码）

javascript 复制代码

ssh-keygen -t ed25519 -C "邮箱"

一路回车，复制公钥配置到代码仓库平台。

七、第七步：VS Code 安装与前端必备插件提前装好

下载 VS Code：https://code.visualstudio.com/
提前安装核心插件，创建项目后不用临时下载：

Volar（Vue3 语法提示，必须，禁用 Vetur）
TypeScript React code snippets
ESLint
Prettier - Code formatter
Stylelint
Sass
GitLens
Chinese (Simplified) Language Pack

VS Code 开启：保存自动格式化、ESLint 自动修复

八、前置工作检查清单（创建项目前核对）

✅ node -v、npm -v 输出版本号
✅ npm 镜像为淘宝镜像
✅ 配置 npm 全局路径（Windows）
✅ git --version 正常，配置全局用户名邮箱
✅ 项目路径无中文、空格
✅ VS Code + Volar、ESLint、Prettier 插件已安装

九、前置全部做完后，才可以执行创建 Vite 项目命令

javascript 复制代码

npm create vite@latest vue3-ts-pinia-demo -- --template vue-ts

Vue3 + Vite + TypeScript + Pinia 完整前端工程详细目录结构

一、从零创建命令（先初始化项目）

javascript 复制代码

# 1. 创建vite项目
npm create vite@latest vue3-ts-pinia-demo -- --template vue-ts

# 2. 进入项目
cd vue3-ts-pinia-demo

# 3. 安装依赖
npm install

# 4. 安装pinia、路由、axios等常用必备依赖
npm install pinia vue-router@4 axios

# 可选：样式、工具
npm install element-plus sass
npm install -D unplugin-vue-components unplugin-auto-import

二、完整标准目录结构（企业级规范版）

javascript 复制代码

vue3-ts-pinia-demo/
├── .vscode/                      # VSCode配置文件夹（团队格式化、代码片段）
│   ├── extensions.json           # 推荐安装插件
│   ├── settings.json             # 编辑器格式化、保存自动修复配置
│   └── launch.json               # 调试配置
├── public/                       # 静态资源（不会被vite打包处理，直接复制dist）
│   ├── favicon.ico               # 网站图标
│   └── static/                   # 第三方静态文件、视频、字体等
│       └── demo.mp4
├── src/                          # 项目源码根目录（核心业务代码）
│   ├── api/                      # 接口请求模块
│   │   ├── index.ts              # axios实例封装、请求拦截器、响应拦截器
│   │   ├── request.ts            # 请求基础封装
│   │   ├── user/                 # 用户模块接口
│   │   │   └── user.ts
│   │   └── system/               # 系统管理模块接口
│   │       └── system.ts
│   ├── assets/                   # 项目内资源（会被vite压缩打包）
│   │   ├── images/               # 页面图片
│   │   ├── styles/               # 全局样式
│   │   │   ├── index.scss        # 全局样式入口
│   │   │   ├── reset.scss        # 样式重置
│   │   │   └── variable.scss     # scss全局变量、主题色
│   │   └── fonts/                # 自定义字体文件
│   ├── components/               # 全局公共组件
│   │   ├── global/               # 全局注册组件
│   │   │   ├── PageHeader/
│   │   │   │   ├── index.vue
│   │   │   │   └── index.ts
│   │   │   └── SearchForm/
│   │   │       ├── index.vue
│   │   │       └── types.ts
│   │   └── business/             # 业务复用组件（局部引入）
│   │       └── UploadFile/
│   │           └── index.vue
│   ├── composables/              # Vue3 组合式函数（hooks）复用逻辑
│   │   ├── useUser.ts            # 用户相关hooks
│   │   ├── useTable.ts           # 表格封装hooks
│   │   └── useRequest.ts         # 请求封装hooks
│   ├── directives/               # 全局自定义指令
│   │   ├── permission.ts         # 权限指令v-permission
│   │   └── index.ts              # 指令统一注册入口
│   ├── env/                      # 多环境配置文件ts类型声明
│   │   ├── env.d.ts
│   │   └── vite-env.d.ts
│   ├── router/                   # vue-router路由
│   │   ├── index.ts              # 路由实例创建、路由守卫
│   │   ├── permission.ts         # 全局路由权限守卫
│   │   └── modules/              # 路由模块拆分
│   │       ├── user.route.ts
│   │       └── system.route.ts
│   ├── store/                    # Pinia状态管理
│   │   ├── index.ts              # pinia实例创建
│   │   ├── modules/               # 模块化仓库
│   │   │   ├── user.ts           # 用户仓库（登录、token、用户信息）
│   │   │   ├── app.ts            # 全局配置（侧边栏、主题、加载）
│   │   │   └── tags.ts           # 标签页仓库
│   │   └── types/                # pinia类型定义
│   │       └── index.ts
│   ├── types/                    # 全局TS类型声明
│   │   ├── global.d.ts           # 全局类型
│   │   ├── api.d.ts              # 接口返回类型
│   │   └── user.d.ts             # 用户相关类型
│   ├── utils/                    # 通用工具函数
│   │   ├── storage.ts            # localStorage/sessionStorage封装
│   │   ├── format.ts             # 时间、金额格式化
│   │   ├── validate.ts           # 正则校验工具
│   │   └── common.ts             # 通用方法
│   ├── views/                    # 页面视图文件夹（路由对应页面）
│   │   ├── login/
│   │   │   └── index.vue
│   │   ├── home/
│   │   │   └── index.vue
│   │   └── system/
│   │       ├── user/
│   │       │   └── index.vue
│   │       └── role/
│   │           └── index.vue
│   ├── App.vue                   # 根组件
│   ├── main.ts                   # 项目入口文件（挂载全局、注册插件）
│   └── vite-env.d.ts             # vite内置ts环境类型声明
├── .env                           # 开发环境默认配置
├── .env.development               # 开发环境变量
├── .env.production                # 生产环境变量
├── .env.test                      # 测试环境变量
├── .eslintrc.cjs                  # ESLint代码校验规则
├── .eslintignore                  # eslint忽略文件
├── .gitignore                     # git忽略提交文件
├── .prettierrc                    # Prettier格式化配置
├── .prettierignore                # 格式化忽略文件
├── index.html                     # vite入口html
├── package.json                   # 项目依赖、脚本命令
├── package-lock.json              # 依赖锁定文件
├── tsconfig.json                  # TypeScript全局编译配置
├── tsconfig.node.json             # vite node环境ts配置
├── vite.config.ts                 # vite打包、插件、代理配置
└── README.md                      # 项目说明文档

三、核心关键文件作用说明

1. 入口文件

src/main.ts：项目挂载入口，注册 Pinia、Router、全局组件、全局样式、全局指令
index.html：Vite 唯一 html 入口，引入 src/main.ts

2. Pinia 核心文件

src/store/index.ts：创建 createPinia() 实例，全局挂载
src/store/modules/*.ts：按业务拆分仓库，替代 Vuex，支持 TS 类型自动推导

3. 路由核心

src/router/index.ts：创建路由实例、路由模式、全局前置 / 后置守卫
src/router/modules：大项目路由拆分，避免单个路由文件臃肿

4. TS 类型相关

src/types/*.d.ts：全局接口、对象、参数类型定义
tsconfig.json：约束 TS 语法、路径别名、类型检查规则
src/vite-env.d.ts：识别 .env 环境变量、vue 文件 TS 类型

5. 接口请求

src/api/index.ts：axios 封装，统一配置 baseURL、超时、请求头、token 携带、错误统一处理

6. 组合式封装

composables：Vue3 推荐存放复用逻辑，替代 vue2 的 mixins，天然支持 TS 类型

四、极简精简版目录（个人小项目可用）

如果是小型项目不需要模块化拆分，可简化：

javascript 复制代码

src/
├── api/
├── assets/
├── components/
├── composables/
├── router/
├── store/          # Pinia
├── types/
├── utils/
├── views/
├── App.vue
├── main.ts
└── vite-env.d.ts

Vue3 配置命令清单

一、前置校验命令（先执行，确认 Node 安装成功）

打开 CMD / PowerShell / Git Bash 依次执行

复制代码

node -v
npm -v
git --version

能输出版本号说明环境安装正常。

二、一键配置 npm 淘宝镜像（必执行，解决下载慢）

复制代码

# 设置国内镜像源
npm config set registry https://registry.npmmirror.com
# 验证镜像是否配置成功
npm config get registry

三、Windows 用户：修改 npm 全局路径（防止 C 盘爆满）

1. 先在 D 盘新建两个文件夹

复制代码

D:\node\npm_global
D:\node\npm_cache

2. 执行下面两条命令配置路径

复制代码

npm config set prefix "D:\node\npm_global"
npm config set cache "D:\node\npm_cache"

配置完成后需要手动把 D:\node\npm_global 添加到系统环境变量 PATH

四、全局常用工具一键安装命令

javascript 复制代码

# 升级npm到最新稳定版
npm install -g npm

# 全局安装yarn包管理器（可选）
npm install -g yarn

# 全局安装vite脚手架
npm install -g create-vite

# 代码格式化、校验工具
npm install -g eslint prettier

五、Git 全局用户名邮箱配置（第一次使用 Git 必须配置）

把下面姓名、邮箱替换成自己的再执行

javascript 复制代码

git config --global user.name "张三"
git config --global user.email "zhangsan@shturl."

# 查看Git全局配置是否生效
git config --global --list

六、可选：生成 Git SSH 密钥（Gitee/GitHub 免密推送）

javascript 复制代码

ssh-keygen -t ed25519 -C "zhangsan@shturl."

执行后一路回车即可，公钥默认路径：C:\Users\用户名\.ssh\id_ed25519.pub

七、创建 Vue3+Vite+TS 项目命令

进入项目存放目录（路径不要中文、空格）后执行：

javascript 复制代码

npm create vite@latest vue3-ts-pinia-project -- --template vue-ts

八、进入项目安装依赖

javascript 复制代码

cd vue3-ts-pinia-project

npm install

# 安装核心必备依赖：路由、状态管理、请求库、样式
npm install pinia vue-router@4 axios sass

npm install element-plus

# 自动导入插件
npm install -D unplugin-vue-components unplugin-auto-import

九、启动开发服务

javascript 复制代码

npm run dev

# 方式 1：临时启动（本次生效）
npm run dev -- --host

javascript 复制代码

# 运行结果出现
➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

Vue3+Vite 项目已经成功启动：

本地访问地址 ：http://localhost:5173 在浏览器直接打开这个地址，就能预览前端项目。
Network: use --host to expose 意思：当前只能自己本机访问，局域网内别的设备（手机、同事电脑）打不开 。需要加 --host 参数启动，才能把项目暴露在局域网。
press h + enter to show help 在当前终端直接按键盘 h 再回车，可以查看 vite 服务的所有快捷键帮助。

常用操作

1. 本机直接访问

浏览器打开：http://localhost:5173/

2. 让局域网内其他设备访问（手机 / 同网段电脑调试）

方式 1：临时启动（本次生效）

先按 Ctrl + C 关闭当前运行中的服务，执行：

复制代码

npm run dev -- --host

启动后就会出现 Network: http://192.168.x.x:5173/，同 WiFi 下设备就能访问这个地址。

方式 2：永久配置（推荐，以后启动自动开放局域网）

修改 package.json 的启动脚本：

javascript 复制代码

"scripts": {
  "dev": "vite --host",
  "build": "tsc && vite build",
  "preview": "vite preview"
}

之后每次执行 npm run dev 都会自动开放局域网访问。

3. 常用快捷键（终端内直接按）

h + 回车：查看所有快捷键说明
r：重启开发服务
o：自动在浏览器打开项目
c：清空终端控制台
q：关闭当前开发服务

常见小问题

手机打不开局域网地址：关闭电脑防火墙，确保手机和电脑连同一个 WiFi；
想修改默认端口 5173：可以在 vite.config.ts 配置 server:{port: 8080} 指定端口。