233 lines
6.7 KiB
Markdown
233 lines
6.7 KiB
Markdown
# 2.4 前端服务启动
|
||
|
||
:::tip 概述
|
||
本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。前端为本仓库 `ui/` 目录内的 NaiveVue 管理后台（Vue3 + NaiveUI）。
|
||
:::
|
||
|
||
## 步骤一：安装依赖
|
||
|
||
```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 = /
|
||
|
||
# 是否开启mock
|
||
VITE_USE_MOCK = false
|
||
|
||
# 网站前缀
|
||
VITE_BASE_URL = /
|
||
|
||
# 是否删除console
|
||
VITE_DROP_CONSOLE = true
|
||
|
||
# 跨域代理，可以配置多个，请注意不要换行
|
||
VITE_PROXY=[["/api","http://admin.laravel13.naivevue/api"]]
|
||
|
||
# API 接口地址
|
||
VITE_GLOB_API_URL =
|
||
|
||
# 图片上传地址
|
||
VITE_GLOB_UPLOAD_URL =
|
||
|
||
# 图片前缀地址
|
||
VITE_GLOB_IMG_URL =
|
||
|
||
# 接口前缀
|
||
VITE_GLOB_API_URL_PREFIX = /api
|
||
```
|
||
|
||
### `.env.production`（生产环境）
|
||
|
||
```bash
|
||
# 是否开启mock
|
||
VITE_USE_MOCK = false
|
||
|
||
# 网站根目录
|
||
VITE_PUBLIC_PATH = /
|
||
|
||
# 网站前缀
|
||
VITE_BASE_URL = /
|
||
|
||
# 是否删除console
|
||
VITE_DROP_CONSOLE = true
|
||
|
||
# API
|
||
VITE_GLOB_API_URL =
|
||
|
||
# 图片上传地址
|
||
VITE_GLOB_UPLOAD_URL =
|
||
|
||
# 图片前缀地址
|
||
VITE_GLOB_IMG_URL =
|
||
|
||
# 接口前缀
|
||
VITE_GLOB_API_URL_PREFIX = /api
|
||
|
||
# 是否启用gzip压缩或brotli压缩
|
||
# 可选: gzip | brotli | none
|
||
VITE_BUILD_COMPRESS = 'none'
|
||
|
||
# 使用压缩时是否删除原始文件，默认为false
|
||
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
|
||
```
|
||
|
||
## 步骤三：启动开发服务器
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
|
||
# -----------------------------------------------------------------------------
|
||
pnpm dev
|
||
|
||
# 或使用 npm
|
||
npm run dev
|
||
```
|
||
|
||
启动成功后会看到：
|
||
|
||
```text
|
||
VITE v5.4.x ready in 1234 ms
|
||
|
||
➜ Local: http://localhost:8001/
|
||
➜ Network: http://192.168.1.100:8001/
|
||
```
|
||
|
||
## 步骤四：配置 API 代理
|
||
|
||
开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务。代理规则由 `.env.development` 的 `VITE_PROXY` 驱动，`vite.config.ts` 只负责调用 `createProxy`：
|
||
|
||
```typescript
|
||
// ui/vite.config.ts
|
||
server: {
|
||
host: true,
|
||
port: VITE_PORT, // 端口来自 VITE_PORT（8001）
|
||
proxy: createProxy(VITE_PROXY), // 解析 VITE_PROXY 生成代理规则
|
||
},
|
||
```
|
||
|
||
`build/vite/proxy.ts` 为每个 `[前缀, 目标]` 生成一条代理规则：
|
||
|
||
```typescript
|
||
// createProxy 由 VITE_PROXY = [["/api","http://admin.laravel13.naivevue/api"]] 生成
|
||
'/api': {
|
||
target: 'http://admin.laravel13.naivevue/api', // 后端地址（Laragon 虚拟主机，见 2.2 Laragon 环境搭建）
|
||
changeOrigin: true, // 修改请求头的 Origin
|
||
ws: true, // 支持 WebSocket
|
||
rewrite: (path) => path.replace(new RegExp('^/api'), ''), // 去掉 /api 前缀再转发
|
||
},
|
||
```
|
||
|
||
需要切换后端地址时，直接修改 `.env.development` 中的 `VITE_PROXY`（改完重启 `pnpm dev` 生效），无需改动 `vite.config.ts`。
|
||
|
||
确保后端服务已启动（见 [2.3 后端服务启动](/zh/quickstart/backend-start.html)），然后访问 `http://localhost:8001`。
|
||
|
||
## 步骤五：验证前后端联调
|
||
|
||
1. 打开浏览器访问 `http://localhost:8001`
|
||
2. 应该看到登录页面
|
||
3. 输入默认账号 `admin` / `123456`
|
||
4. 登录成功后进入控制台页面
|
||
|
||
:::tip 代理原理
|
||
浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://admin.laravel13.naivevue/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` 由它驱动），改完重启 `pnpm dev`：
|
||
|
||
```bash
|
||
# .env.development
|
||
VITE_PORT = 8002 # 改为其他端口（如 8002、8003 等）
|
||
```
|
||
|
||
### 3. API 请求 404
|
||
|
||
检查后端服务是否启动，以及代理配置是否正确：
|
||
|
||
```bash
|
||
# 确认后端在运行（直接请求后端验证码接口）
|
||
curl http://admin.laravel13.naivevue/api/captcha
|
||
# → {"code":0,...} 即后端正常
|
||
```
|
||
|
||
再检查 `.env.development` 中 `VITE_PROXY` 的目标地址是否指向后端实际地址（改完需重启 `pnpm dev`）。
|
||
|
||
### 4. 登录报 401
|
||
|
||
1. Token 过期 → 重新登录（access_token 默认 2 小时）
|
||
2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
|
||
3. 后端 `JWT_SECRET` 变更 → 旧令牌全部失效，重新登录即可
|