237 lines
5.9 KiB
Markdown
237 lines
5.9 KiB
Markdown
# 前端启动
|
||
|
||
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `NaiveUI` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
|
||
|
||
:::tip 温馨提示
|
||
启动前端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的 `Node.js` 和 `pnpm` 安装，并已启动后端服务（参见 [后端启动](/zh/volume1/backend)）。
|
||
:::
|
||
|
||
## 前端目录结构
|
||
|
||
前端源码位于项目根目录的 `ui/` 文件夹中：
|
||
|
||
```
|
||
ui/
|
||
├── public/ # 静态资源
|
||
├── src/
|
||
│ ├── api/ # 接口请求封装
|
||
│ ├── assets/ # 资源文件（图片、样式等）
|
||
│ ├── components/ # 公共组件
|
||
│ ├── layout/ # 布局组件
|
||
│ ├── router/ # 路由配置
|
||
│ ├── store/ # 状态管理（Pinia）
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── views/ # 页面视图
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 入口文件
|
||
├── .env.development # 开发环境变量
|
||
├── .env.production # 生产环境变量
|
||
├── vite.config.ts # Vite 构建配置
|
||
├── package.json # 依赖清单
|
||
└── tsconfig.json # TypeScript 配置
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
进入前端项目目录，使用 `pnpm` 安装依赖：
|
||
|
||
```bash
|
||
# 进入前端目录
|
||
cd ui
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
```
|
||
|
||
安装过程如下：
|
||
|
||
```
|
||
$ pnpm install
|
||
Lockfile is up to date, resolution step is skipped
|
||
Packages: +1200
|
||
++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
Progress: resolved 1200, reused 1200, downloaded 0, added 1200, done
|
||
|
||
Done in 15.2s
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
依赖安装完毕后，在 `ui/` 目录下会生成 `node_modules` 文件夹，此文件夹包含了项目全部的前端依赖包。首次安装可能需要较长时间，请耐心等待。
|
||
:::
|
||
|
||
+ 验证依赖安装
|
||
|
||
```bash
|
||
# 检查 Vue 版本
|
||
npx vue --version
|
||
|
||
# 检查 Vite 版本
|
||
npx vite --version
|
||
```
|
||
|
||
:::tip 常见问题
|
||
如果 `pnpm install` 失败，可尝试以下解决方案：
|
||
|
||
```bash
|
||
# 清除缓存后重新安装
|
||
pnpm store prune
|
||
pnpm install
|
||
|
||
# 删除 node_modules 后重新安装
|
||
rm -rf node_modules
|
||
pnpm install
|
||
```
|
||
:::
|
||
|
||
## 配置代理
|
||
|
||
前端开发服务器通过 `Vite` 代理将 API 请求转发到后端服务。代理配置位于 `vite.config.ts` 文件中。
|
||
|
||
+ 开发环境变量
|
||
|
||
前端开发环境的变量配置在 `.env.development` 文件中：
|
||
|
||
```bash
|
||
# 开发服务器端口
|
||
VITE_PORT = 8001
|
||
|
||
# 网站根目录
|
||
VITE_PUBLIC_PATH = /
|
||
|
||
# 跨域代理配置（指向后端服务地址）
|
||
VITE_PROXY=[["/api","http://127.0.0.1:8021/api"]]
|
||
|
||
# 接口前缀
|
||
VITE_GLOB_API_URL_PREFIX = /api
|
||
```
|
||
|
||
:::tip 代理说明
|
||
`VITE_PROXY` 配置项中，`/api` 是前端请求的路径前缀，`http://127.0.0.1:8021/api` 是后端服务的实际地址。前端所有以 `/api` 开头的请求都会被代理到后端的 `8021` 端口。
|
||
:::
|
||
|
||
+ 修改代理地址
|
||
|
||
如果后端服务运行在不同的地址或端口，需要修改 `.env.development` 中的代理配置：
|
||
|
||
```bash
|
||
# 示例：后端运行在 192.168.1.100 的 8021 端口
|
||
VITE_PROXY=[["/api","http://192.168.1.100:8021/api"]]
|
||
```
|
||
|
||
## 启动开发服务器
|
||
|
||
确保后端服务已启动后，在 `ui/` 目录下执行以下命令：
|
||
|
||
```bash
|
||
# 启动前端开发服务器
|
||
pnpm dev
|
||
```
|
||
|
||
启动成功后，终端将输出类似以下信息：
|
||
|
||
```
|
||
$ vite
|
||
|
||
VITE v3.2.10 ready in 943 ms
|
||
|
||
➜ Local: http://localhost:8001/
|
||
➜ Network: http://192.168.1.100:8001/
|
||
```
|
||
|
||
:::tip 默认端口
|
||
前端开发服务器默认运行在 `http://localhost:8001/`，可通过 `.env.development` 中的 `VITE_PORT` 参数修改端口。
|
||
:::
|
||
|
||
## 访问系统
|
||
|
||
在浏览器中打开以下地址：
|
||
|
||
```
|
||
http://localhost:8001/
|
||
```
|
||
|
||
|
||
|
||
+ 默认登录账号
|
||
|
||
| 类型 | 账号 | 密码 | 说明 |
|
||
|:----|:----|:----|:----|
|
||
| 管理员 | `admin` | `123456` | 超管账号，默认拥有全部权限 |
|
||
| 普通用户 | `admin2` | `123456` | 普通账号，具有角色权限 |
|
||
|
||
:::tip 登录验证
|
||
1. 打开登录页面后，应能看到验证码图片正常显示，说明前后端通信正常。
|
||
2. 输入账号 `admin` 和密码 `123456`，点击登录按钮。
|
||
3. 成功登录后将进入系统主界面，表示前后端均已正确启动。
|
||
:::
|
||
|
||
:::danger 注意事项
|
||
如果验证码图片无法显示，请检查：
|
||
1. 后端服务是否已启动（`http://127.0.0.1:8021`）
|
||
2. 代理配置是否正确（`.env.development` 中的 `VITE_PROXY`）
|
||
3. Redis 服务是否正常运行（验证码存储依赖 Redis）
|
||
:::
|
||
|
||
## 前端构建与部署
|
||
|
||
+ 开发环境构建
|
||
|
||
```bash
|
||
# 开发环境打包
|
||
pnpm build:dev
|
||
```
|
||
|
||
+ 生产环境构建
|
||
|
||
```bash
|
||
# 生产环境打包
|
||
pnpm build
|
||
```
|
||
|
||
构建完成后，会在 `ui/` 目录下生成 `dist/` 文件夹，包含打包后的静态资源文件。将 `dist/` 目录部署到 `Nginx` 或其他 Web 服务器即可。
|
||
|
||
+ 预览构建结果
|
||
|
||
```bash
|
||
# 本地预览打包结果
|
||
pnpm preview
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
+ pnpm install 失败
|
||
|
||
```bash
|
||
# 清除 pnpm 缓存
|
||
pnpm store prune
|
||
|
||
# 使用淘宝镜像源
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
pnpm install
|
||
```
|
||
|
||
+ 端口被占用
|
||
|
||
如果启动时报端口冲突，可修改 `.env.development` 中的 `VITE_PORT`：
|
||
|
||
```bash
|
||
VITE_PORT = 8002
|
||
```
|
||
|
||
+ API 请求 404
|
||
|
||
检查后端服务是否启动，以及 `.env.development` 中的 `VITE_PROXY` 代理地址是否与后端实际地址一致。
|
||
|
||
+ 验证码不显示
|
||
|
||
```
|
||
1. 确认后端服务已启动
|
||
2. 确认 Redis 服务已启动并可连接
|
||
3. 检查浏览器控制台（F12）是否有跨域错误
|
||
4. 检查 .env 中 CORS_ALLOWED_ORIGINS 是否包含前端地址
|
||
```
|
||
|
||
## 总结
|
||
|
||
本章节介绍了前端项目的完整启动流程：安装依赖 → 配置代理 → 启动开发服务器 → 访问登录页面。通过以上步骤，你已经成功将前端应用运行在本地 `8001` 端口，并使用默认账号 `admin/123456` 登录系统。下一步可以进入 [第一个接口调试](/zh/volume1/first-api) 章节，学习如何调试后端 API 接口。
|