创建项目前完整前置准备工作从安装 Node.jsVS Code 开始一、第一步下载安装 Node.js必须1. 下载地址官网https://nodejs.org/ 推荐选择LTS 长期支持版稳定版不要选 Current 最新尝鲜版2. 安装注意事项Windows / MacWindows一路默认下一步一定要勾选 Add to PATH自动配置环境变量Mac.pkg安装包直接默认安装即可安装完成后打开终端CMD/PowerShell/ 终端验证是否安装成功# 查看node版本 node -v # 查看npm版本 npm -v出现版本号即安装成功。版本建议Node 18.0.0Vite4/Vite5 最低要求 Node14.18推荐 18、20 LTSnpm 会随 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 --registryhttps://registry.npmmirror.com # 之后可以用 cnpm install 代替 npm install三、第三步全局安装常用工具可选但建议装1. 升级 npm 到最新稳定版npm install -g npm2. 全局安装 yarn可选包管理工具备用npm install -g yarn # 验证 yarn -v3. 全局安装 vite 脚手架不装也可以create vite 临时会下载npm install -g create-vite4. 全局安装 eslint、prettier团队规范格式化可选npm install -g eslint prettier四、第四步配置系统全局缓存路径Windows必做解决C盘爆满默认 npm 全局依赖、缓存都存在 C 盘用户目录时间久会占用大量 C 盘空间建议修改全局路径在非 C 盘新建两个文件夹D:\node\npm_global全局包存放。D:\node\npm_cache缓存文件。终端执行配置命令npm config set prefix D:\node\npm_global npm config set cache D:\node\npm_cache配置系统环境变量把D:\node\npm_global配置到系统环境变量 PATH 中否则全局命令无法使用。环境变量找到变量Path选中后点【编辑】找到旧路径C:\Users\用户名\AppData\Roaming\npm选中删除这一行点击【新建】粘贴路径D:\node\npm_global点击【上移】把这一行路径移动到列表最顶部避免路径冲突系统变量补充配置可选但建议配置在系统变量区域点击【新建】变量名NODE_PATH变量值D:\node\npm_global\node_modules6.验证配置是否成功关闭所有已打开的 CMD、PowerShell、Git Bash 窗口必须重启终端才生效重新打开终端执行命令npm config get prefix返回D:\node\npm_global代表路径配置成功7.全局命令测试create-vite -v方式 1npx 临时查询推荐不用进项目npx create-vite --version方式 2查看全局安装包版本 npm list create-vite -g方式 3先退出当前创建流程再执行查询五、第五步终端工具选择与文件夹准备新建项目存放文件夹不要用中文、空格、特殊字符 错误示例D:\前端项目\vue项目正确示例D:\code\vue-project在文件夹地址栏输入cmd回车直接在当前目录打开终端不用频繁 cd 切换路径六、第六步Git 安装必须代码版本管理1. 下载 Githttps://git-scm.com/默认安装即可安装后验证git --version2. 全局配置用户名 邮箱第一次使用 Git 必须配置git config --global user.name 姓名/昵称 git config --global user.email 邮箱GitHub/Gitee注册邮箱 # 查看配置 git config --global --list3. 可选配置 SSH 密钥拉取推送 Gitee/GitHub 代码免密码ssh-keygen -t ed25519 -C 邮箱一路回车复制公钥配置到代码仓库平台。七、第七步VS Code 安装与前端必备插件提前装好下载 VS Codehttps://code.visualstudio.com/提前安装核心插件创建项目后不用临时下载VolarVue3 语法提示必须禁用 VeturTypeScript React code snippetsESLintPrettier - Code formatterStylelintSassGitLensChinese (Simplified) Language PackVS Code 开启保存自动格式化、ESLint 自动修复八、前置工作检查清单创建项目前核对✅ node -v、npm -v 输出版本号✅ npm 镜像为淘宝镜像✅ 配置 npm 全局路径Windows✅ git --version 正常配置全局用户名邮箱✅ 项目路径无中文、空格✅ VS Code Volar、ESLint、Prettier 插件已安装九、前置全部做完后才可以执行创建 Vite 项目命令npm create vitelatest vue3-ts-pinia-demo -- --template vue-tsVue3 Vite TypeScript Pinia 完整前端工程详细目录结构一、从零创建命令先初始化项目# 1. 创建vite项目 npm create vitelatest vue3-ts-pinia-demo -- --template vue-ts # 2. 进入项目 cd vue3-ts-pinia-demo # 3. 安装依赖 npm install # 4. 安装pinia、路由、axios等常用必备依赖 npm install pinia vue-router4 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. 入口文件src/main.ts项目挂载入口注册 Pinia、Router、全局组件、全局样式、全局指令index.htmlVite 唯一 html 入口引入src/main.ts2. 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.tsaxios 封装统一配置 baseURL、超时、请求头、token 携带、错误统一处理6. 组合式封装composablesVue3 推荐存放复用逻辑替代 vue2 的 mixins天然支持 TS 类型四、极简精简版目录个人小项目可用如果是小型项目不需要模块化拆分可简化src/ ├── api/ ├── assets/ ├── components/ ├── composables/ ├── router/ ├── store/ # Pinia ├── types/ ├── utils/ ├── views/ ├── App.vue ├── main.ts └── vite-env.d.tsVue3 配置命令清单一、前置校验命令先执行确认 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_cache2. 执行下面两条命令配置路径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 zhangsanshturl. # 查看Git全局配置是否生效 git config --global --list六、可选生成 Git SSH 密钥Gitee/GitHub 免密推送ssh-keygen -t ed25519 -C zhangsanshturl.执行后一路回车即可公钥默认路径C:\Users\用户名\.ssh\id_ed25519.pub七、创建 Vue3ViteTS 项目命令进入项目存放目录路径不要中文、空格后执行npm create vitelatest vue3-ts-pinia-project -- --template vue-ts八、进入项目安装依赖cd vue3-ts-pinia-project npm install # 安装核心必备依赖路由、状态管理、请求库、样式 npm install pinia vue-router4 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 helpVue3Vite 项目已经成功启动本地访问地址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的启动脚本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}指定端口。NVMNode Version ManagerNode 多版本管理工具一、NVM 作用一台电脑安装多个版本 Node.js可随时切换不同 Node 环境解决不同项目要求 Node 版本不一致、全局依赖冲突的问题。Windows 用nvm-windowsMac/Linux 用官方nvm二、Windows 安装 nvm-windows1. 下载安装包GitHub 地址https://github.com/coreybutler/nvm-windows/releases 下载nvm-setup.exe安装包重要前置提醒安装前必须卸载电脑上已有的 Node.js否则会出现版本冲突、切换失效问题。国内加速镜像下载GitHub 访问慢时用https://www.nvmnode.com/guide/download.html2. 安装注意事项第一步选择 NVM 存放路径建议非 C 盘D:\nvm第二步设置 Node 软链接路径D:\nodejs不要已有 Node 文件夹一路下一步完成安装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 时会自动配套安装对应 npm3. 查看本机已安装所有 Node 版本nvm list # 简写 nvm ls前面带*为当前正在使用的版本4. 切换使用某个 Node 版本nvm use 20.15.15. 设置默认 Node 版本新开终端自动生效nvm alias default 20.15.16. 卸载某个 Node 版本nvm uninstall 18.20.07. 开启 / 关闭 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 安装官方 NVM1. 一键安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash2. 配置环境变量根据终端类型配置到对应配置文件zshMac 默认~/.zshrcbash~/.bash_profile末尾添加export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh生效配置source ~/.zshrcMac 常用命令和 Windows 完全一致nvm list available nvm install lts nvm use 24.18.0 nvm alias default 24.18.0六、NVM 使用最佳实践开发 Vue3/Vite 项目推荐Node 18.x / 20.x LTS老 Vue2/Webpack 项目推荐Node 14.x / 16.x LTS每个 Node 版本的全局依赖互相隔离切换版本后全局包需要重新安装不要手动全局配置 npm 的 prefix 路径NVM 会自动管理全局包路径七、常见问题nvm use权限报错Windows 以管理员身份打开终端执行切换版本后node -v不生效检查是否设置default默认版本、重启终端Node 下载失败必须配置淘宝镜像源
前端工程化-02：一个完整的vue工程结构模板
发布时间：2026/7/5 13:25:09
创建项目前完整前置准备工作从安装 Node.jsVS Code 开始一、第一步下载安装 Node.js必须1. 下载地址官网https://nodejs.org/ 推荐选择LTS 长期支持版稳定版不要选 Current 最新尝鲜版2. 安装注意事项Windows / MacWindows一路默认下一步一定要勾选 Add to PATH自动配置环境变量Mac.pkg安装包直接默认安装即可安装完成后打开终端CMD/PowerShell/ 终端验证是否安装成功# 查看node版本 node -v # 查看npm版本 npm -v出现版本号即安装成功。版本建议Node 18.0.0Vite4/Vite5 最低要求 Node14.18推荐 18、20 LTSnpm 会随 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 --registryhttps://registry.npmmirror.com # 之后可以用 cnpm install 代替 npm install三、第三步全局安装常用工具可选但建议装1. 升级 npm 到最新稳定版npm install -g npm2. 全局安装 yarn可选包管理工具备用npm install -g yarn # 验证 yarn -v3. 全局安装 vite 脚手架不装也可以create vite 临时会下载npm install -g create-vite4. 全局安装 eslint、prettier团队规范格式化可选npm install -g eslint prettier四、第四步配置系统全局缓存路径Windows必做解决C盘爆满默认 npm 全局依赖、缓存都存在 C 盘用户目录时间久会占用大量 C 盘空间建议修改全局路径在非 C 盘新建两个文件夹D:\node\npm_global全局包存放。D:\node\npm_cache缓存文件。终端执行配置命令npm config set prefix D:\node\npm_global npm config set cache D:\node\npm_cache配置系统环境变量把D:\node\npm_global配置到系统环境变量 PATH 中否则全局命令无法使用。环境变量找到变量Path选中后点【编辑】找到旧路径C:\Users\用户名\AppData\Roaming\npm选中删除这一行点击【新建】粘贴路径D:\node\npm_global点击【上移】把这一行路径移动到列表最顶部避免路径冲突系统变量补充配置可选但建议配置在系统变量区域点击【新建】变量名NODE_PATH变量值D:\node\npm_global\node_modules6.验证配置是否成功关闭所有已打开的 CMD、PowerShell、Git Bash 窗口必须重启终端才生效重新打开终端执行命令npm config get prefix返回D:\node\npm_global代表路径配置成功7.全局命令测试create-vite -v方式 1npx 临时查询推荐不用进项目npx create-vite --version方式 2查看全局安装包版本 npm list create-vite -g方式 3先退出当前创建流程再执行查询五、第五步终端工具选择与文件夹准备新建项目存放文件夹不要用中文、空格、特殊字符 错误示例D:\前端项目\vue项目正确示例D:\code\vue-project在文件夹地址栏输入cmd回车直接在当前目录打开终端不用频繁 cd 切换路径六、第六步Git 安装必须代码版本管理1. 下载 Githttps://git-scm.com/默认安装即可安装后验证git --version2. 全局配置用户名 邮箱第一次使用 Git 必须配置git config --global user.name 姓名/昵称 git config --global user.email 邮箱GitHub/Gitee注册邮箱 # 查看配置 git config --global --list3. 可选配置 SSH 密钥拉取推送 Gitee/GitHub 代码免密码ssh-keygen -t ed25519 -C 邮箱一路回车复制公钥配置到代码仓库平台。七、第七步VS Code 安装与前端必备插件提前装好下载 VS Codehttps://code.visualstudio.com/提前安装核心插件创建项目后不用临时下载VolarVue3 语法提示必须禁用 VeturTypeScript React code snippetsESLintPrettier - Code formatterStylelintSassGitLensChinese (Simplified) Language PackVS Code 开启保存自动格式化、ESLint 自动修复八、前置工作检查清单创建项目前核对✅ node -v、npm -v 输出版本号✅ npm 镜像为淘宝镜像✅ 配置 npm 全局路径Windows✅ git --version 正常配置全局用户名邮箱✅ 项目路径无中文、空格✅ VS Code Volar、ESLint、Prettier 插件已安装九、前置全部做完后才可以执行创建 Vite 项目命令npm create vitelatest vue3-ts-pinia-demo -- --template vue-tsVue3 Vite TypeScript Pinia 完整前端工程详细目录结构一、从零创建命令先初始化项目# 1. 创建vite项目 npm create vitelatest vue3-ts-pinia-demo -- --template vue-ts # 2. 进入项目 cd vue3-ts-pinia-demo # 3. 安装依赖 npm install # 4. 安装pinia、路由、axios等常用必备依赖 npm install pinia vue-router4 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. 入口文件src/main.ts项目挂载入口注册 Pinia、Router、全局组件、全局样式、全局指令index.htmlVite 唯一 html 入口引入src/main.ts2. 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.tsaxios 封装统一配置 baseURL、超时、请求头、token 携带、错误统一处理6. 组合式封装composablesVue3 推荐存放复用逻辑替代 vue2 的 mixins天然支持 TS 类型四、极简精简版目录个人小项目可用如果是小型项目不需要模块化拆分可简化src/ ├── api/ ├── assets/ ├── components/ ├── composables/ ├── router/ ├── store/ # Pinia ├── types/ ├── utils/ ├── views/ ├── App.vue ├── main.ts └── vite-env.d.tsVue3 配置命令清单一、前置校验命令先执行确认 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_cache2. 执行下面两条命令配置路径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 zhangsanshturl. # 查看Git全局配置是否生效 git config --global --list六、可选生成 Git SSH 密钥Gitee/GitHub 免密推送ssh-keygen -t ed25519 -C zhangsanshturl.执行后一路回车即可公钥默认路径C:\Users\用户名\.ssh\id_ed25519.pub七、创建 Vue3ViteTS 项目命令进入项目存放目录路径不要中文、空格后执行npm create vitelatest vue3-ts-pinia-project -- --template vue-ts八、进入项目安装依赖cd vue3-ts-pinia-project npm install # 安装核心必备依赖路由、状态管理、请求库、样式 npm install pinia vue-router4 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 helpVue3Vite 项目已经成功启动本地访问地址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的启动脚本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}指定端口。NVMNode Version ManagerNode 多版本管理工具一、NVM 作用一台电脑安装多个版本 Node.js可随时切换不同 Node 环境解决不同项目要求 Node 版本不一致、全局依赖冲突的问题。Windows 用nvm-windowsMac/Linux 用官方nvm二、Windows 安装 nvm-windows1. 下载安装包GitHub 地址https://github.com/coreybutler/nvm-windows/releases 下载nvm-setup.exe安装包重要前置提醒安装前必须卸载电脑上已有的 Node.js否则会出现版本冲突、切换失效问题。国内加速镜像下载GitHub 访问慢时用https://www.nvmnode.com/guide/download.html2. 安装注意事项第一步选择 NVM 存放路径建议非 C 盘D:\nvm第二步设置 Node 软链接路径D:\nodejs不要已有 Node 文件夹一路下一步完成安装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 时会自动配套安装对应 npm3. 查看本机已安装所有 Node 版本nvm list # 简写 nvm ls前面带*为当前正在使用的版本4. 切换使用某个 Node 版本nvm use 20.15.15. 设置默认 Node 版本新开终端自动生效nvm alias default 20.15.16. 卸载某个 Node 版本nvm uninstall 18.20.07. 开启 / 关闭 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 安装官方 NVM1. 一键安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash2. 配置环境变量根据终端类型配置到对应配置文件zshMac 默认~/.zshrcbash~/.bash_profile末尾添加export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh生效配置source ~/.zshrcMac 常用命令和 Windows 完全一致nvm list available nvm install lts nvm use 24.18.0 nvm alias default 24.18.0六、NVM 使用最佳实践开发 Vue3/Vite 项目推荐Node 18.x / 20.x LTS老 Vue2/Webpack 项目推荐Node 14.x / 16.x LTS每个 Node 版本的全局依赖互相隔离切换版本后全局包需要重新安装不要手动全局配置 npm 的 prefix 路径NVM 会自动管理全局包路径七、常见问题nvm use权限报错Windows 以管理员身份打开终端执行切换版本后node -v不生效检查是否设置default默认版本、重启终端Node 下载失败必须配置淘宝镜像源
