# 2.4 前端服务启动

:::tip 概述
本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。前端为本仓库 `ui/` 目录内的 EleVue 管理后台（Vue3 + ElementPlus）。
:::

## 步骤一：安装依赖

```bash
# 进入前端项目目录（克隆/解压前端仓库至 ui/ 目录）
cd ui

# -----------------------------------------------------------------------------
# 安装依赖（推荐 pnpm — 速度快、磁盘占用少）
# -----------------------------------------------------------------------------
# install → 从 pnpm-lock.yaml 精确安装所有依赖
pnpm install

# 如果没有 pnpm，也可以使用 npm
npm install
```

:::warning Node.js 版本
前端项目要求 Node.js >= 22（推荐 22.18.0）。可通过 `node -v` 检查版本，安装方式见 [2.1 开发环境准备](/zh/quickstart/environment.html)。
:::

:::tip 国内镜像
安装速度较慢时配置镜像源：

```bash
pnpm config set registry https://registry.npmmirror.com
# 或
npm config set registry https://registry.npmmirror.com
```
:::

## 步骤二：配置环境变量

前端有两个环境配置文件：

### `.env.development`（开发环境）

```bash
# 服务端口
VITE_PORT = 8001

# 公共基础路径
VITE_PUBLIC_PATH = /

# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
VITE_PROXY = [["/api","http://localhost:8000/api"]]

# API 接口基础路径（留空，由代理处理）
VITE_GLOB_API_URL =

# API 前缀
VITE_GLOB_API_URL_PREFIX = /api

# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload

# 图片访问地址（附件域名，对应后端 FILE_DOMAIN_URL）
VITE_GLOB_IMG_URL = http://file.laravel13.elevue

# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK = false
```

### `.env.production`（生产环境）

```bash
# 公共基础路径
VITE_PUBLIC_PATH = /

# 是否在生产环境删除 console
VITE_DROP_CONSOLE = true

# API 接口基础路径（留空，由 Nginx 代理处理）
VITE_GLOB_API_URL =

# API 前缀
VITE_GLOB_API_URL_PREFIX = /api

# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload

# 图片访问地址
VITE_GLOB_IMG_URL = https://file.example.com

# 是否启用 gzip 压缩
VITE_BUILD_COMPRESS = gzip

# 压缩后是否删除原文件
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
```

## 步骤三：启动开发服务器

```bash
# -----------------------------------------------------------------------------
# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
# -----------------------------------------------------------------------------
pnpm dev

# 或使用 npm
npm run dev
```

启动成功后会看到：

```text
  VITE v3.2.x  ready in 1234 ms

  ➜  Local:   http://localhost:8001/
  ➜  Network: http://192.168.1.100:8001/
```

## 步骤四：配置 API 代理

开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务。

在 `vite.config.ts` 中配置代理：

```typescript
// ui/vite.config.ts
server: {
  port: 8001,                                // 开发服务器端口（对应 VITE_PORT）
  proxy: {
    '/api': {
      target: 'http://localhost:8000/api',   // 后端服务地址（对应 VITE_PROXY）
      changeOrigin: true,                     // 开启跨域（修改请求头的 Origin）
      rewrite: (path) => path,                // 保持路径不变（不做路径替换）
    },
  },
}
```

后端使用虚拟域名时（见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)），target 改为对应地址：

```typescript
target: 'http://admin.laravel13.elevue/api',
```

确保后端服务已启动（`php artisan serve`），然后访问 `http://localhost:8001`。

## 步骤五：验证前后端联调

1. 打开浏览器访问 `http://localhost:8001`
2. 应该看到登录页面
3. 输入默认账号 `admin` / `123456`
4. 登录成功后进入控制台页面

:::tip 代理原理
浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://localhost:8000/api/login` → 后端处理

代理方式下前端无需关心跨域；若改为直连后端（`VITE_GLOB_API_URL` 配置完整地址），则依赖后端 CORS 配置（`.env` 中 `CORS_ALLOW_ORIGIN`）。
:::

## 构建生产版本

```bash
# -----------------------------------------------------------------------------
# 构建生产版本（Vite 会压缩代码、Tree-shaking、分包）
# -----------------------------------------------------------------------------
# build → 输出到 ui/dist/ 目录
pnpm build

# -----------------------------------------------------------------------------
# 预览构建结果（本地启动一个静态文件服务器预览 dist/ 内容）
# -----------------------------------------------------------------------------
pnpm preview
```

构建完成后，`ui/dist/` 目录包含可部署的静态文件，部署方式见 [11.5 前端部署](/zh/deploy/frontend.html)。

:::tip
后端仓库根目录的 `composer dev` / `composer setup` 也会执行 `npm run build`（构建后端 `resources/` 下的静态资源），与前端仓库的构建相互独立。
:::

## 常见问题

### 1. `pnpm install` 报错

```bash
# -----------------------------------------------------------------------------
# 清除缓存重新安装（修复依赖冲突或缓存损坏）
# -----------------------------------------------------------------------------
# rm -rf → 递归强制删除（node_modules 和 lockfile）
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### 2. 端口 8001 被占用

修改 `.env.development` 中的 `VITE_PORT` 或 `vite.config.ts` 中的 `server.port`：

```typescript
server: {
  port: 8002,  // 改为其他端口（如 8002、8003 等）
}
```

### 3. API 请求 404

检查后端服务是否启动，以及代理配置是否正确：

```bash
# 确认后端在运行（直接请求后端验证码接口）
curl http://localhost:8000/api/captcha
# → {"code":0,...} 即后端正常
```

再检查 `vite.config.ts` 中 `proxy.target` 是否指向后端实际地址（改完需重启 `pnpm dev`）。

### 4. 登录报 401

1. Token 过期 → 重新登录（access_token 默认 2 小时）
2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
3. 后端 `JWT_SECRET` 变更 → 旧令牌全部失效，重新登录即可