前端工程化-02：一个完整的vue工程结构模板

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

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

1. 下载地址

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

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

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

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

出现版本号即安装成功。

版本建议

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

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

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

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

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

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

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

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

1. 升级 npm 到最新稳定版

npm install -g npm

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

npm install -g yarn # 验证 yarn -v

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

npm install -g create-vite

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

npm install -g eslint prettier

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

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

1. 在非 C 盘新建两个文件夹：

   1. D:\node\npm_global（全局包存放）。

   2. D:\node\npm_cache（缓存文件）。

2. 终端执行配置命令：

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

配置系统环境变量

1. 把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：先退出当前创建流程，再执行查询

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

1. 新建项目存放文件夹（不要用中文、空格、特殊字符） 错误示例：D:\前端项目\vue项目正确示例：D:\code\vue-project

2. 在文件夹地址栏输入cmd回车，直接在当前目录打开终端，不用频繁 cd 切换路径

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

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

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

git --version

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

git config --global user.name "姓名/昵称" git config --global user.email "邮箱（GitHub/Gitee注册邮箱）" # 查看配置 git config --global --list

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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

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

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. 入口文件

1. src/main.ts：项目挂载入口，注册 Pinia、Router、全局组件、全局样式、全局指令
2. 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 类型

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

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

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

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

# 升级npm到最新稳定版 npm install -g npm # 全局安装yarn包管理器（可选） npm install -g yarn # 全局安装vite脚手架 npm install -g create-vite # 代码格式化、校验工具 npm install -g eslint prettier

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

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

git config --global user.name "张三" git config --global user.email "zhangsan@shturl." # 查看Git全局配置是否生效 git config --global --list

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

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

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

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

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

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

八、进入项目安装依赖

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

九、启动开发服务

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

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

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

1. 本地访问地址：http://localhost:5173在浏览器直接打开这个地址，就能预览前端项目。
2. Network: use --host to expose意思：当前只能自己本机访问，局域网内别的设备（手机、同事电脑）打不开。 需要加--host参数启动，才能把项目暴露在局域网。
3. 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的启动脚本：

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

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

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

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

常见小问题

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

NVM（Node Version Manager）Node 多版本管理工具

一、NVM 作用

一台电脑安装多个版本 Node.js，可随时切换不同 Node 环境，解决不同项目要求 Node 版本不一致、全局依赖冲突的问题。

• Windows 用：nvm-windows
• Mac/Linux 用：官方nvm

二、Windows 安装 nvm-windows

1. 下载安装包

GitHub 地址：https://github.com/coreybutler/nvm-windows/releases 下载：nvm-setup.exe安装包

重要前置提醒：

安装前必须卸载电脑上已有的 Node.js，否则会出现版本冲突、切换失效问题。

国内加速镜像下载（GitHub 访问慢时用）

https://www.nvmnode.com/guide/download.html

2. 安装注意事项

1. 第一步选择 NVM 存放路径（建议非 C 盘：D:\nvm）
2. 第二步设置 Node 软链接路径：D:\nodejs（不要已有 Node 文件夹）
3. 一路下一步完成安装

3. 校验是否安装成功

新开终端执行：

nvm -v

输出版本号即安装成功。

三、NVM 常用核心命令（直接复制使用）

1. 查看可安装的 Node 稳定版本

nvm list available

推荐安装LTS 长期稳定版（带 LTS 标识）

2. 安装指定 Node 版本

# 安装20.x LTS版本 nvm install 20.15.1 # 安装最新LTS版 nvm install lts

安装 Node 时会自动配套安装对应 npm

3. 查看本机已安装所有 Node 版本

nvm list # 简写 nvm ls

前面带*为当前正在使用的版本

4. 切换使用某个 Node 版本

nvm use 20.15.1

5. 设置默认 Node 版本（新开终端自动生效）

nvm alias default 20.15.1

6. 卸载某个 Node 版本

nvm uninstall 18.20.0

7. 开启 / 关闭 Node 版本管理

nvm on nvm off

四、Windows NVM 配置淘宝镜像（解决下载 Node 慢）

方式 1：终端执行配置

nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/

方式 2：手动修改配置文件

打开 NVM 安装目录下的settings.txt，添加两行：

node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/

配置后再执行nvm install xxx下载速度会大幅提升。

五、Mac / Linux 安装官方 NVM

1. 一键安装脚本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

2. 配置环境变量

根据终端类型配置到对应配置文件：

• zsh（Mac 默认）：~/.zshrc
• bash：~/.bash_profile末尾添加：

export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

生效配置：

source ~/.zshrc

Mac 常用命令和 Windows 完全一致

nvm list available nvm install lts nvm use 24.18.0 nvm alias default 24.18.0

六、NVM 使用最佳实践

1. 开发 Vue3/Vite 项目：推荐Node 18.x / 20.x LTS
2. 老 Vue2/Webpack 项目：推荐Node 14.x / 16.x LTS
3. 每个 Node 版本的全局依赖互相隔离，切换版本后全局包需要重新安装
4. 不要手动全局配置 npm 的 prefix 路径，NVM 会自动管理全局包路径

七、常见问题

1. nvm use权限报错：Windows 以管理员身份打开终端执行
2. 切换版本后node -v不生效：检查是否设置default默认版本、重启终端
3. Node 下载失败：必须配置淘宝镜像源