签入版本

DjangoAdmin_FastAPI_NaiveVue/zh/volume1/frontend.md

@@ -0,0 +1,236 @@
+# 前端启动
+
+本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `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 接口。