# 前端启动

本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `AntDesign Vue` + `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.js # 入口文件
├── .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:8031/api"]]

# 接口前缀
VITE_GLOB_API_URL_PREFIX = /api
```

:::tip 代理说明
`VITE_PROXY` 配置项中，`/api` 是前端请求的路径前缀，`http://127.0.0.1:8031/api` 是后端服务的实际地址。前端所有以 `/api` 开头的请求都会被代理到后端的 `8031` 端口。
:::

+ 修改代理地址

如果后端服务运行在不同的地址或端口，需要修改 `.env.development` 中的代理配置：

```bash
# 示例：后端运行在 192.168.1.100 的 8031 端口
VITE_PROXY=[["/api","http://192.168.1.100:8031/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/
```

![](/demo/1.png)

+ 默认登录账号

| 类型 | 账号 | 密码 | 说明 |
|:----|:----|:----|:----|
| 管理员 | `admin` | `123456` | 超管账号，默认拥有全部权限 |
| 普通用户 | `admin2` | `123456` | 普通账号，具有角色权限 |

:::tip 登录验证
1. 打开登录页面后，应能看到验证码图片正常显示，说明前后端通信正常。
2. 输入账号 `admin` 和密码 `123456`，点击登录按钮。
3. 成功登录后将进入系统主界面，表示前后端均已正确启动。
:::

:::danger 注意事项
如果验证码图片无法显示，请检查：
1. 后端服务是否已启动（`http://127.0.0.1:8031`）
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) 章节，学习如何使用 Swagger UI 调试后端 API 接口。