快速开始
本文将帮助你快速上手 vue3-element-admin。
环境准备
在开始之前，请确保你的开发环境满足以下要求：
| 环境类型 | 版本要求 | 备注 |
|---|---|---|
| Node.js | ^20.19.0 或 >=22.12.0 | 推荐使用 LTS 版本（主版本为偶数） |
| 包管理器 | pnpm >= 8.0.0 | 项目使用 pnpm 作为包管理器 |
| 开发工具 | Visual Studio Code | 可选，建议配合插件（见代码规范） |
安装 Node.js
访问 Node.js 官网 下载并安装最新的 LTS 版本。
bash
node -v安装 pnpm
项目使用 pnpm 作为包管理器，需要全局安装：
bash
corepack enable
corepack prepare pnpm@latest --activate验证安装：
bash
pnpm -v相关编辑器建议与插件清单已下沉到：
获取项目
bash
# 克隆项目
git clone https://gitee.com/youlaiorg/vue3-element-admin.git
# 进入项目目录
cd vue3-element-adminbash
# 克隆项目
git clone https://github.com/youlaitech/vue3-element-admin.git
# 进入项目目录
cd vue3-element-adminbash
# 克隆项目
git clone https://gitcode.com/youlai/vue3-element-admin.git
# 进入项目目录
cd vue3-element-admin安装依赖
bash
# 设置镜像源（可选，国内用户推荐）
pnpm config set registry https://registry.npmmirror.com
# 安装依赖
pnpm install提示
首次安装可能需要较长时间，请耐心等待。如果安装失败，可以先尝试：
- 删除
node_modules和pnpm-lock.yaml - 清除缓存：
pnpm store prune - 重新安装：
pnpm install
启动项目
bash
# 开发环境启动
pnpm run dev启动成功后，浏览器会自动打开 http://localhost:3000（端口号可能不同）。
构建生产
bash
# 构建生产环境
pnpm run build
# 预览生产环境
pnpm run preview构建完成后，会在项目根目录生成 dist 文件夹，可以将其部署到服务器。
代码检查、提交规范、接口环境配置等内容见：
常见问题
1. 依赖安装失败
原因：网络问题或依赖包版本冲突
解决方案：
powershell
# 清除缓存
pnpm store prune
# 删除依赖
Remove-Item -Recurse -Force node_modules
Remove-Item -Force pnpm-lock.yaml
# 重新安装
pnpm installbash
# 清除缓存
pnpm store prune
# 删除依赖
rm -rf node_modules pnpm-lock.yaml
# 重新安装
pnpm install2. 项目启动后浏览器空白
原因：浏览器版本过低，不支持某些 ES6+ 语法
解决方案：
- 检查
vite.config.ts中的server配置 - 重启开发服务器
- 清除浏览器缓存
3. 热更新失败
原因：Vite HMR 配置问题
解决方案：
- 检查
vite.config.ts中的server配置 - 重启开发服务器
- 清除浏览器缓存
4. 端口被占用
原因：3000 端口已被其他程序占用
解决方案：
bash
# 方式一：修改端口
# 在 vite.config.ts 中修改 server.port
# 方式二：杀死占用端口的进程
# Windows
netstat -ano | findstr 3000
taskkill /PID <PID> /F
# Mac/Linux
lsof -i :3000
kill -9 <PID>下一步
恭喜你已经成功运行项目！建议按这个顺序继续：
如有问题，欢迎提 Issue.