rxthinkcmf-wiki/RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/frontend-start.md

2.4 前端服务启动

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

步骤一：安装依赖

# 进入前端项目目录（克隆/解压前端仓库至 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 开发环境准备。 :::

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

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

:::

步骤二：配置环境变量

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

.env.development（开发环境）

# 只在开发模式中被载入
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（生产环境）

# 是否开启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

步骤三：启动开发服务器

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

# 或使用 npm
npm run dev

启动成功后会看到：

  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：

// ui/vite.config.ts
server: {
  host: true,
  port: VITE_PORT,                    // 端口来自 VITE_PORT（8001）
  proxy: createProxy(VITE_PROXY),     // 解析 VITE_PROXY 生成代理规则
},

build/vite/proxy.ts 为每个 [前缀, 目标] 生成一条代理规则：

// 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 后端服务启动），然后访问 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）。 :::

构建生产版本

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

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

构建完成后，ui/dist/ 目录包含可部署的静态文件，部署方式见 11.5 前端部署。

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

常见问题

1. pnpm install 报错

# -----------------------------------------------------------------------------
# 清除缓存重新安装（修复依赖冲突或缓存损坏）
# -----------------------------------------------------------------------------
# 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：

# .env.development
VITE_PORT = 8002   # 改为其他端口（如 8002、8003 等）

3. API 请求 404

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

# 确认后端在运行（直接请求后端验证码接口）
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 变更 → 旧令牌全部失效，重新登录即可