djangoadmin/djangoadmin-wiki

Fork 0

Files

T

gitadmin 11c46addfa 优化更新

2026-09-14 10:33:29 +08:00

5.9 KiB

Raw Permalink Blame History

前端启动

本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 Vue3 + NaiveUI + TypeScript+Vite 构建，采用组件化开发模式，支持热更新和代理配置。

:::tip 温馨提示启动前端前，请确保已完成环境准备章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见后端启动）。 :::

前端目录结构

前端源码位于项目根目录的 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 安装依赖：

# 进入前端目录
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 文件夹，此文件夹包含了项目全部的前端依赖包。首次安装可能需要较长时间，请耐心等待。 :::

验证依赖安装

# 检查 Vue 版本
npx vue --version

# 检查 Vite 版本
npx vite --version

:::tip 常见问题如果 pnpm install 失败，可尝试以下解决方案：

# 清除缓存后重新安装
pnpm store prune
pnpm install

# 删除 node_modules 后重新安装
rm -rf node_modules
pnpm install

:::

配置代理

前端开发服务器通过 Vite 代理将 API 请求转发到后端服务。代理配置位于 vite.config.ts 文件中。

开发环境变量

前端开发环境的变量配置在 .env.development 文件中：

# 开发服务器端口
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 中的代理配置：

# 示例：后端运行在 192.168.1.100 的 8031 端口
VITE_PROXY=[["/api","http://192.168.1.100:8031/api"]]

启动开发服务器

确保后端服务已启动后，在 ui/ 目录下执行以下命令：

# 启动前端开发服务器
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/

默认登录账号

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

:::tip 登录验证

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

:::danger 注意事项如果验证码图片无法显示，请检查：

后端服务是否已启动（http://127.0.0.1:8031）
代理配置是否正确（.env.development 中的 VITE_PROXY）
Redis 服务是否正常运行（验证码存储依赖 Redis） :::

前端构建与部署

开发环境构建

# 开发环境打包
pnpm build:dev

生产环境构建

# 生产环境打包
pnpm build

构建完成后，会在 ui/ 目录下生成 dist/ 文件夹，包含打包后的静态资源文件。将 dist/ 目录部署到 Nginx 或其他 Web 服务器即可。

预览构建结果

# 本地预览打包结果
pnpm preview

常见问题

pnpm install 失败

# 清除 pnpm 缓存
pnpm store prune

# 使用淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install

端口被占用

如果启动时报端口冲突，可修改 .env.development 中的 VITE_PORT：

VITE_PORT = 8002

API 请求 404

检查后端服务是否启动，以及 .env.development 中的 VITE_PROXY 代理地址是否与后端实际地址一致。

验证码不显示

1. 确认后端服务已启动
2. 确认 Redis 服务已启动并可连接
3. 检查浏览器控制台（F12）是否有跨域错误
4. 检查 .env 中 CORS_ALLOWED_ORIGINS 是否包含前端地址

总结

本章节介绍了前端项目的完整启动流程：安装依赖 → 配置代理 → 启动开发服务器 → 访问登录页面。通过以上步骤，你已经成功将前端应用运行在本地 8001 端口，并使用默认账号 admin/123456 登录系统。下一步可以进入第一个接口调试章节，学习如何使用 Swagger UI 调试后端 API 接口。

5.9 KiB Raw Permalink Blame History Unescape Escape