Hertz System 文档

Appearance

前端项目初始化与运行 ​

本页为前端内容初始化教程，提供 hertz_ui Vue3 管理端项目的环境准备、依赖安装、运行与打包的操作指引，可作为《前端项目介绍》的配套“动手指南”。

一、前提条件 ​

在开始之前，请确保：

  • 已在本机安装 Node.js（推荐 18+ 版本）。
  • 已安装 Git，用于拉取前端项目代码。
  • 后端服务已按《后端项目部署及运行》启动，能够通过 http://localhost:8000 访问。

在终端中确认 Node.js 环境：

bash
node --version
npm --version

二、获取前端项目代码 ​

前端工程目录名为 hertz_ui，通常与后端项目在同一仓库或同级目录。以单独仓库为例：

bash
git clone <前端仓库地址>
cd hertz_ui

仓库地址以实际项目为准，可参考 HzGit 上的说明。

三、安装依赖 ​

在 hertz_ui 目录下执行：

bash
npm install

如使用 pnpm 或 yarn，可根据团队约定改为 pnpm install / yarn。

四、配置后端接口地址 ​

前端通过 Vite 环境变量 VITE_API_BASE_URL 与后端对接，需要同时配置开发/生产两个环境文件：

  1. 开发环境：创建或编辑 .env.development 文件（本地联调使用）：

    env
    VITE_API_BASE_URL=http://127.0.0.1:8000

  2. 生产环境：创建或编辑 .env.production 文件（正式部署使用），示例：

    env
    VITE_API_BASE_URL=http://127.0.0.1:8000

  3. 确保后端服务可以通过上面配置的地址正常访问（端口如有调整，请同步修改）。

注意：VITE_API_BASE_URL 只写协议 + 域名/IP + 端口，不包含 /api 前缀。

五、本地开发运行 ​

在依赖安装完成、.env.development 配置好后，执行：

bash
npm run dev

终端会输出本地访问地址，例如：

  • http://localhost:5173/

在浏览器中打开该地址，即可进入 Hertz System 前端管理端界面进行开发调试。

六、生产构建与预览 ​

当需要打包前端用于部署时，在 hertz_ui 目录下执行：

bash
# 构建生产版本
npm run build

# 本地预览构建产物（可选）
npm run preview

构建完成后，会在项目根目录生成 dist/ 目录，包含所有前端静态资源。后续可由 Django、Nginx 或其他静态服务器托管 dist 目录中的文件。

七、与后端协同的注意事项 ​

  • 确保前端配置的 VITE_API_BASE_URL 与后端实际访问地址一致。
  • 如果后端通过反向代理暴露路径前缀（例如 /hertz/），需要在前端 Axios 封装中统一调整 baseURL 或路径前缀。
  • WebSocket 等实时接口应与后端协商统一的地址和路径（例如 ws://localhost:8000/ws/）。

八、常用 npm 脚本速查 ​

在 package.json 中，前端工程通常提供以下脚本：

json
{
  "scripts": {
    "dev": "vite",           // 本地开发
    "build": "vite build",   // 生产构建
    "preview": "vite preview" // 预览构建产物
  }
}

具体脚本以实际项目 package.json 为准，可在编辑器中打开查看。