快速开始

本文将帮助你快速上手 vue3-element-admin。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

环境类型	版本要求	备注
Node.js	^20.19.0 或 >=22.12.0	推荐使用 LTS 版本（主版本为偶数）
包管理器	pnpm >= 8.0.0	项目使用 pnpm 作为包管理器
开发工具	Visual Studio Code	推荐安装 Vue、TypeScript 相关插件

安装 Node.js

访问 Node.js 官网 下载并安装最新的 LTS 版本。

验证安装：

node -v
npm -v

安装 pnpm

项目使用 pnpm 作为包管理器，需要全局安装：

npm install -g pnpm

验证安装：

pnpm -v

VSCode 插件推荐

为了获得最佳的开发体验，推荐安装以下 VSCode 插件：

• Vue - Official：Vue 3 官方插件，提供语法高亮、智能提示等
• TypeScript Vue Plugin (Volar)：Vue 3 TypeScript 支持
• ESLint：代码检查
• Prettier - Code formatter：代码格式化
• Stylelint：样式检查
• EditorConfig for VS Code：统一编辑器配置
• Path Intellisense：路径智能提示
• Auto Rename Tag：自动重命名标签
• GitLens：Git 增强

获取项目

Gitee

# 克隆项目
git clone https://gitee.com/youlaiorg/vue3-element-admin.git

# 进入项目目录
cd vue3-element-admin

GitHub

# 克隆项目
git clone https://github.com/youlaitech/vue3-element-admin.git

# 进入项目目录
cd vue3-element-admin

GitCode

# 克隆项目
git clone https://gitcode.com/youlai/vue3-element-admin.git

# 进入项目目录
cd vue3-element-admin

安装依赖

# 设置镜像源（可选，国内用户推荐）
pnpm config set registry https://registry.npmmirror.com

# 安装依赖
pnpm install

提示

首次安装可能需要较长时间，请耐心等待。如果安装失败，可以尝试：

1. 删除 node_modules 和 pnpm-lock.yaml
2. 清除缓存：pnpm store prune
3. 重新安装：pnpm install

启动项目

# 开发环境启动
pnpm run dev

启动成功后，浏览器会自动打开 http://localhost:3000（端口号可能不同）。

默认账号

账号	密码	权限
admin	123456	管理员（所有权限）
test	123456	测试账号（部分权限）

构建生产

# 构建生产环境
pnpm run build

# 预览生产环境
pnpm run preview

构建完成后，会在项目根目录生成 dist 文件夹，可以将其部署到服务器。

代码检查

# ESLint 检查并自动修复
pnpm run lint:eslint

# Prettier 格式化代码
pnpm run lint:prettier

# Stylelint 检查并自动修复样式
pnpm run lint:stylelint

# 一键执行所有检查和格式化
pnpm run lint

提交代码

项目集成了 Git 提交规范，执行以下命令唤起交互式提交：

# 添加文件到暂存区
git add .

# 交互式提交
pnpm run commit

根据提示选择提交类型、输入提交信息等。

提交类型说明

类型	说明
feat	新功能
fix	修复 Bug
docs	文档更新
style	代码格式（不影响代码运行的变动）
refactor	重构（既不是新增功能，也不是修改 Bug 的代码变动）
perf	性能优化
test	增加测试
chore	构建过程或辅助工具的变动
revert	回滚
build	打包

切换接口环境

项目支持三种接口环境：

1. 在线接口（默认）

默认使用有来技术提供的在线接口，无需配置即可使用。

2. Mock 接口

修改 .env.development 文件：

# 开启 Mock 接口
VITE_MOCK_DEV_SERVER = true

3. 本地后端接口

Java 后端（推荐）

1. 克隆后端项目：

git clone https://gitee.com/youlaiorg/youlai-boot.git

2. 按照后端项目 README 说明启动项目

3. 修改 .env.development 文件：

# API 接口地址
VITE_APP_API_URL = http://localhost:8989

# 关闭 Mock
VITE_MOCK_DEV_SERVER = false

Node 后端

1. 克隆后端项目：

git clone https://gitee.com/youlaiorg/youlai-nest.git

2. 按照后端项目 README 说明启动项目

3. 修改 .env.development 文件：

# API 接口地址
VITE_APP_API_URL = http://localhost:3000

# 关闭 Mock
VITE_MOCK_DEV_SERVER = false

常见问题

1. 依赖安装失败

原因：网络问题或依赖包版本冲突

解决方案：

# 清除缓存
pnpm store prune

# 删除依赖
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

2. 项目启动后浏览器空白

原因：浏览器版本过低，不支持某些 ES6+ 语法

解决方案：升级浏览器到最新版本

3. 热更新失败

原因：Vite HMR 配置问题

解决方案：

1. 检查 vite.config.ts 中的 server 配置
2. 重启开发服务器
3. 清除浏览器缓存

4. TypeScript 类型报错

原因：类型声明文件未生成或过期

解决方案：

1. 重启 VSCode
2. 删除 auto-imports.d.ts 和 components.d.ts
3. 重新启动项目，让自动导入插件重新生成

5. 端口被占用

原因：3000 端口已被其他程序占用

解决方案：

# 方式一：修改端口
# 在 vite.config.ts 中修改 server.port

# 方式二：杀死占用端口的进程
# Windows
netstat -ano | findstr 3000
taskkill /PID <PID> /F

# Mac/Linux
lsof -i :3000
kill -9 <PID>

下一步

恭喜你已经成功运行项目！接下来你可以：

• 📖 阅读 项目结构 了解项目架构
• 🎨 查看 组件文档 学习如何使用组件
• 🔐 学习 权限控制 了解权限系统
• 🚀 开始开发你的第一个功能

如有问题，欢迎提 Issue 或加入交流群讨论。