飞鹅博客初始化及二次开发指南（一）博客前端#

该网址即为此项目搭建智心一梦

1. 项目简介#

飞鹅博客是一个基于 Nuxt 3 + TypeScript 构建的现代化 AI 技术分享平台，集成了智能对话助手、技术博客、AI 资讯等核心功能。该项目采用前后端分离架构，前端使用 Nuxt 3 框架，支持服务端渲染和静态站点生成，为用户提供高性能的访问体验。

1.1 技术栈#

技术/框架	版本	用途
Nuxt	^3.4.3	前端框架
TypeScript	^4.7.2	类型检查
Vue	3.x	UI 框架
Pinia	2.0.14	状态管理
Element Plus	^2.3.4	UI 组件库
Ant Design Vue	^3.2.7	UI 组件库
Less	^4.1.3	样式预处理器
Axios	-	HTTP 客户端

1.2 核心功能#

智能对话助手：支持单次对话和流式对话两种模式
技术博客：文章列表、详情展示、分类标签
AI 资讯：最新 AI 动态展示和外部链接跳转
用户系统：登录、注册、个人信息管理
响应式设计：适配不同屏幕尺寸

2. 环境准备#

2.1 基础环境#

⚠️ 注意事项：由于 Nuxt 当前版本存在 bug，启动项目时必须使用 Node.js 16.x，否则可能出现 unused body 报错。
建议使用 nvm 或 fnm 快速切换 Node 版本：
nvm use 16
# 或
fnm use 16

Node.js >= 14.0.0（推荐 16.x）
Yarn >= 1.22.0 或 npm >= 6.0.0
Git
Node.js >= 14.0.0
Yarn >= 1.22.0 或 npm >= 6.0.0
Git

2.2 开发工具推荐#

Visual Studio Code
Vue DevTools
ESLint 插件
Prettier 插件

3. 项目初始化#

3.1 克隆项目#

git clone https://github.com/your-repo/flygoose-blog.git
cd flygoose-blog

3.2 安装依赖#

yarn install

3.3 配置环境变量#

在项目根目录创建 .env 文件，配置基础 URL：

# 开发环境
export BASE_URL=http://localhost:3000/api

# 生产环境
export BASE_URL=https://your-api-domain.com/api

3.4 启动开发服务器#

yarn dev

访问 http://localhost:3000 即可查看项目。

4. 项目结构分析#

4.1 目录结构#

├── api/                # API 请求封装
├── assets/             # 静态资源
│   ├── images/         # 图片资源
│   ├── less/           # 全局样式
│   └── movie/          # 视频资源
├── components/         # Vue 组件
│   ├── blog/           # 博客相关组件
│   ├── global/         # 全局通用组件
│   ├── index/          # 首页组件
│   ├── layout/         # 布局组件
│   └── special/        # 专栏相关组件
├── hooks/              # 自定义 hooks
├── layouts/            # 页面布局
├── middleware/         # 中间件
├── pages/              # 页面组件
│   ├── ai/             # AI 相关页面
│   ├── detail/         # 文章详情
│   └── specialColumn/  # 专栏页面
├── plugins/            # 插件
├── stores/             # Pinia 状态管理
├── types/              # TypeScript 类型定义
├── utils/              # 工具函数
└── nuxt.config.ts      # Nuxt 配置文件

4.2 核心文件说明#

pages/index.vue：网站首页，包含英雄区域、AI 对话、博客入口和资讯展示
pages/ai/chatOnce.vue：单次对话组件，支持快捷问题和自定义问题
pages/ai/chatStream.vue：流式对话组件，支持实时打字效果
components/layout/：包含导航栏、侧边栏、页脚等布局组件
stores/user.ts：用户信息状态管理
api/index.ts：API 请求封装

5. 代码规范#

5.1 命名规范#

文件夹：小写，多个单词用连字符，如 ai-chat
Vue 文件：除了 index.vue 全部使用大驼峰，如 ArticleItem.vue
TypeScript 文件：使用小驼峰，如 useToken.ts
Class 名：多个字母用连字符，如 quick-questions
事件命名：触发的 DOM 事件命名为 handleXxxxClick，监听事件为 onXxxxChange

5.2 代码风格#

使用 ESLint + Prettier 进行代码检查和格式化
使用 TypeScript 进行类型检查
Vue 组件使用 Composition API
样式使用 Less 预处理器

6. 二次开发指南#

6.1 新增页面#

在 pages 目录下创建新的 Vue 文件，Nuxt 会自动生成路由：

<template>
  <div class="new-page">
    <h1>新页面</h1>
    <p>这是一个新添加的页面</p>
  </div>
</template>

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

<style lang="less" scoped>
.new-page {
  padding: 20px;
}
</style>

6.2 新增组件#

在 components 目录下创建新的 Vue 组件：

<template>
  <div class="new-component">
    <slot></slot>
  </div>
</template>

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

<style lang="less" scoped>
.new-component {
  /* 组件样式 */
}
</style>

6.3 添加 API 请求#

在 api/index.ts 中添加新的 API 请求：

export const getNewData = async (params: any) => {
  return await request({
    url: '/api/new-data',
    method: 'get',
    params
  })
}

6.4 状态管理#

在 stores 目录下创建新的状态管理文件：

import { defineStore } from 'pinia'

export const useNewStore = defineStore('new', () => {
  const data = ref([])
  
  const fetchData = async () => {
    const res = await getNewData()
    data.value = res.data
  }
  
  return {
    data,
    fetchData
  }
})

6.5 修改主题样式#

在 assets/less/style.less 中修改全局样式变量：

// 主题色
@primary-color: #52c41a;
@success-color: #52c41a;
@warning-color: #faad14;
@error-color: #f5222d;

// 文字色
@text-color: #333333;
@text-color-secondary: #666666;
@text-color-tertiary: #999999;

7. 快捷问题按钮开发实例#

以 chatOnce.vue 中的快捷问题按钮为例，展示二次开发过程：

7.1 添加按钮到模板#

<div class="quick-questions">
  <button @click="handleFirstHandshake" class="quick-question-button first-handshake-button">
    第一次握手
  </button>
  <button v-for="(button, index) in quickButtons" :key="index" class="quick-question-button" @click="fillQuestion(button.message)">
    {{ button.buttonname }}
  </button>
</div>

7.2 实现按钮样式#

.quick-questions {
  display: flex;
  gap: 12px;
  margin-top: 12px;
  flex-wrap: wrap;
}

.quick-question-button {
  padding: 6px 12px;
  border: 1px solid #52c41a;
  border-radius: 16px;
  background: #f6ffed;
  color: #52c41a;
  font-size: 12px;
  cursor: pointer;
  transition: all 0.3s;
  white-space: nowrap;
  position: relative;
  overflow: hidden;
  
  &.first-handshake-button {
    border: 1px solid #ff7a45;
    background: #fff7e6;
    color: #ff7a45;
    
    &:hover {
      background: linear-gradient(135deg, #ff7a45, #ffac38);
      border-color: #ff7a45;
      color: #fff;
      box-shadow: 0 2px 8px rgba(255, 122, 69, 0.3);
    }
  }
  
  &:hover {
    background: linear-gradient(135deg, #52c41a, #73d13d);
    color: #fff;
    border-color: #52c41a;
    transform: translateY(-1px);
    box-shadow: 0 2px 8px rgba(82, 196, 26, 0.3);
  }
}

7.3 实现按钮功能#

// 快捷问题按钮数据
const quickButtons = [
  { buttonname: 'AI 是什么？', message: '人工智能（AI）是什么？它有哪些主要应用领域？' },
  { buttonname: '机器学习入门', message: '如何入门机器学习？需要学习哪些基础知识？' },
  { buttonname: '深度学习框架', message: '目前主流的深度学习框架有哪些？它们各自的优缺点是什么？' }
]

// 填充问题到输入框
const fillQuestion = (message: string) => {
  userInput.value = message
}

// 处理第一次握手
const showHandshakeDialog = ref(false)
const authorName = ref('')
const authorNameError = ref('')

const handleFirstHandshake = () => {
  authorName.value = ''
  authorNameError.value = ''
  showHandshakeDialog.value = true
}

8. 部署流程#

8.1 构建生产版本#

# 开发环境构建
yarn build:local

# 测试环境构建
yarn build_test

# 生产环境构建
yarn build

构建成功后，会生成 .output 目录。

8.2 使用 PM2 部署#

在项目根目录执行：

pm install pm2 -g
pm2 start pm2.config.js

8.3 配置 Nginx#

server {
  listen 80;
  server_name your-domain.com;
  
  location / {
    proxy_pass http://localhost:58081;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}

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

9.1 API 请求失败#

检查 BASE_URL 配置是否正确
确保后端服务正常运行
检查网络连接

9.2 样式不生效#

检查 Less 依赖是否安装
确保样式文件路径正确
检查 CSS 选择器是否正确

9.3 页面路由 404#

检查页面文件命名和路径是否符合 Nuxt 路由规则
确保布局文件存在

10. 项目维护#

10.1 代码更新#

git pull
yarn install
yarn build
yarn start

10.2 依赖更新#

yarn upgrade-interactive

10.3 日志查看#

pm2 logs