飞鹅博客系统初始化及二次开发（三）管理端前端#

1. 项目概述#

飞鹅博客系统管理端是一个基于 Vue 3 + TypeScript 的现代化管理后台，用于管理博客系统的各类内容和配置。本项目采用了组件化、模块化的设计思想，提供了良好的可扩展性和维护性。

1.1 技术栈#

技术/框架	版本	用途
Vue.js	3.x	前端框架
TypeScript	5.x	类型系统
Pinia	2.x	状态管理
Ant Design Vue	4.x	UI 组件库
Vue Router	4.x	路由管理
Axios	1.x	HTTP 请求
Vite	5.x	构建工具
Less	4.x	CSS 预处理器

2. 环境搭建#

2.1 安装依赖#

项目使用 pnpm 作为包管理工具，首先确保已安装 pnpm：

npm install -g pnpm

然后安装项目依赖：

cd ai-fire-admin
pnpm install

2.2 配置文件#

项目包含两个主要的环境配置文件：

.env.development：开发环境配置
.env.production：生产环境配置

配置文件中定义了 API 基础路径等关键信息，可根据实际情况修改：

# 开发环境示例
VITE_API_BASE_URL = '/api'

2.3 启动开发服务器#

pnpm dev

开发服务器默认会在 http://localhost:5173 启动。

3. 项目结构#

ai-fire-admin/
├── public/              # 静态资源
├── src/                 # 源代码
│   ├── apis/            # API接口定义
│   ├── assets/          # 静态资源
│   ├── components/      # 自定义组件
│   ├── layouts/         # 布局组件
│   ├── router/          # 路由配置
│   ├── stores/          # 状态管理
│   ├── types/           # TypeScript类型定义
│   ├── utils/           # 工具函数
│   ├── views/           # 页面组件
│   ├── App.vue          # 根组件
│   └── main.ts          # 入口文件
├── nginx/               # Nginx配置
├── .env.*               # 环境配置
├── package.json         # 项目配置
├── vite.config.ts       # Vite配置
└── tsconfig.json        # TypeScript配置

3.1 核心目录说明#

3.1.1 `src/apis/`#

定义了与后端交互的所有 API 接口，每个模块对应一个独立的文件：

// 示例：website-info.ts
import request from '@/utils/http'

export const getSiteInfoList = () => {
  return request.get('/api/website/info/list')
}

export const createSiteInfo = (data: any) => {
  return request.post('/api/website/info/create', data)
}

3.1.2 `src/components/`#

包含项目中使用的自定义组件，如表格、表单、模态框等：

table.vue：通用表格组件
form.vue：通用表单组件
modal.vue：通用模态框组件
pagination.vue：分页组件

3.1.3 `src/layouts/`#

定义了系统的整体布局结构：

default-layout.vue：默认布局，包含侧边栏、顶部导航和内容区域
menu.vue：侧边栏菜单组件
foot.vue：页脚组件

3.1.4 `src/router/`#

配置了系统的路由结构：

// index.ts
import { createRouter, createWebHistory } from 'vue-router'
import DefaultLayout from '@/layouts/default-layout.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: DefaultLayout,
      children: [
        {
          path: '',
          name: 'dashboard',
          component: () => import('../views/dashboard/index.vue')
        }
        // 其他路由...
      ]
    },
    {
      path: '/login',
      name: 'login',
      component: () => import('../views/login/index.vue')
    }
  ]
})

3.1.5 `src/stores/`#

使用 Pinia 进行状态管理，按功能模块划分：

// module/website-info.ts
import { defineStore } from 'pinia'
import * as websiteInfoApi from '@/apis/website-info'

export const useWebsiteInfoStore = defineStore('websiteInfo', {
  state: () => ({
    websiteInfoList: []
  }),
  actions: {
    async getSiteInfoListAction() {
      const res = await websiteInfoApi.getSiteInfoList()
      this.websiteInfoList = res.data
      return res.data
    }
  }
})

3.1.6 `src/utils/`#

包含项目中使用的工具函数：

http.ts：Axios 实例配置
constant.ts：常量定义

3.1.7 `src/views/`#

包含系统的所有页面组件，按功能模块划分：

dashboard/：仪表盘
blog/：博客管理
category/：分类管理
website-info/：网站信息管理
login/：登录页面

4. 核心功能模块#

4.1 登录与权限管理#

系统实现了基于 JWT 的登录认证机制：

用户输入账号密码登录
后端验证通过后返回 JWT token
前端将 token 存储到 localStorage
后续请求通过 Authorization 头携带 token

登录逻辑实现：

// views/login/index.vue
const handleLogin = async () => {
  try {
    const res = await userApi.login(formData.value)
    localStorage.setItem('token', res.data.token)
    router.push('/')
    message.success('登录成功')
  } catch (error) {
    message.error('登录失败')
  }
}

4.2 网站信息管理#

网站信息管理模块用于配置博客系统的基本信息，如标题、标语、封面、版权信息等。

主要功能：

查看网站信息列表
选择并查看详情
编辑网站信息
创建新的网站信息

实现细节：

<!-- views/website-info/website-info.vue -->
<Table
  :data-source="dataSource"
  :columns="columns"
  ref="table"
  @edit="edit"
  @change="handleTableChange"
>
  <!-- 表格内容 -->
</Table>

<a-descriptions bordered style="margin-top: 20px;">
  <a-descriptions-item label="网站标题">{{ websiteInfo.title }}</a-descriptions-item>
  <!-- 其他信息项 -->
</a-descriptions>

4.3 博客管理#

博客管理模块用于管理博客文章，支持以下功能：

博客列表展示与分页
博客文章的创建、编辑、删除
富文本编辑
分类与标签管理
状态管理（已发布/草稿）

4.4 分类管理#

分类管理模块用于管理博客文章的分类，支持：

分类列表展示
分类的创建、编辑、删除
分类排序
分类状态管理

4.5 仪表盘#

仪表盘模块提供系统概览，包括：

博客文章统计
分类统计
访问量统计
最新动态

5. 二次开发指南#

5.1 添加新页面#

在 src/views/ 目录下创建新的页面组件
在 src/router/ 中配置路由
在侧边栏菜单中添加新的菜单项

示例：添加新页面

<!-- src/views/new-page/index.vue -->
<template>
  <div class="new-page">
    <h1>新页面</h1>
  </div>
</template>

<script setup lang="ts">
// 页面逻辑
</script>

// src/router/index.ts
const router = createRouter({
  // ...
  routes: [
    {
      path: '/',
      component: DefaultLayout,
      children: [
        // ...
        {
          path: '/new-page',
          name: 'newPage',
          component: () => import('../views/new-page/index.vue')
        }
      ]
    }
  ]
})

5.2 添加新组件#

在 src/components/ 目录下创建新的组件
在需要使用的地方导入并使用

示例：创建新组件

<!-- src/components/my-component.vue -->
<template>
  <div class="my-component">
    <slot></slot>
  </div>
</template>

<script setup lang="ts">
// 组件逻辑
</script>

5.3 扩展 API#

在 src/apis/ 目录下创建新的 API 文件
定义 API 函数
在组件或 store 中使用

示例：添加新 API

// src/apis/new-api.ts
import request from '@/utils/http'

export const getNewData = () => {
  return request.get('/api/new-data')
}

5.4 自定义主题#

系统使用 Ant Design Vue 的主题定制功能，可以通过修改 src/assets/css/variables.less 文件来自定义主题颜色：

// 自定义主题色
@primary-color: #1890ff;
@success-color: #52c41a;
@warning-color: #faad14;
@error-color: #f5222d;

6. 部署流程#

6.1 构建生产版本#

pnpm build

构建后的文件会输出到 dist/ 目录。

6.2 Nginx 配置#

项目提供了 Nginx 配置文件 nginx/nginx.conf，可根据实际情况修改：

# 全局配置
user nginx;
worker_processes auto;

# http 配置
http {
    include       mime.types;
    default_type  application/octet-stream;

    # 服务器配置
    server {
        listen       8080;
        server_name  localhost;

        # 前端静态资源
        location / {
            root   /usr/share/nginx/html;
            index  index.html index.htm;
            try_files $uri $uri/ /index.html;
        }

        # API 代理
        location /api {
            proxy_pass http://127.0.0.1:29090;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

6.3 部署步骤#

将构建后的 dist/ 目录上传到服务器的 /usr/share/nginx/html/ 目录
将 Nginx 配置文件复制到服务器的 /etc/nginx/conf.d/ 目录
重新加载 Nginx 配置：
```
nginx -s reload
```

7. 开发规范#

7.1 代码风格#

项目使用 ESLint 和 Prettier 来保证代码风格的一致性，提交代码前会自动进行检查。

7.2 命名规范#

组件名：大驼峰命名，如 WebsiteInfo
文件/目录名：小写字母加短横线，如 website-info.vue
变量名：小驼峰命名，如 websiteInfoList
常量名：全大写加下划线，如 API_BASE_URL

7.3 注释规范#

组件和函数使用 JSDoc 注释
复杂逻辑添加必要的单行注释
代码变更添加提交注释

8. 常见问题与解决方案#

8.1 跨域问题#

开发环境中，Vite 配置了代理解决跨域问题：

// vite.config.ts
export default defineConfig({
  // ...
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:29090',
        changeOrigin: true
      }
    }
  }
})

生产环境中，通过 Nginx 代理解决跨域问题。

8.2 构建失败#

检查依赖是否正确安装
检查 TypeScript 类型是否正确
检查语法错误

8.3 页面空白#

检查路由配置是否正确
检查组件是否正确导入
检查网络请求是否正常