PC端二次开发指南（小白版）

📖 本指南专门针对 PC 端（Nuxt.js）的二次开发，从零开始教你如何配置、开发和部署 PC 端项目。

📋 目录

1. 技术栈介绍
2. 开始之前的准备
3. 首次安装配置
4. 环境文件配置详解
5. 开发模式（本地调试）
6. 生产环境打包
7. 开发技巧
8. 常见问题解决
9. 快速参考

技术栈介绍

PC 端使用的技术栈：

核心特性：

✅ 支持 SSR（服务端渲染）和 SPA（单页应用）两种模式
✅ SEO 优化（搜索引擎优化）
✅ 自动路由（基于文件系统）
✅ 热重载（代码修改后自动刷新）
✅ TypeScript 支持

开始之前的准备

2.1 检查 Node.js 版本

PC 端必须使用 Node 16 或更高版本（推荐 Node 16 或 18）。

检查当前版本：
node -v

如果版本低于 16，请先升级 Node.js：

下载地址：https://nodejs.org/
选择 LTS 版本（长期支持版）
2.2 安装 pnpm 包管理器

PC 端项目使用 pnpm 管理依赖（不要用 npm 或 yarn）。

安装 pnpm：
npm install -g pnpm@9.12.3

验证安装：
pnpm -v

💡 为什么用 pnpm？

速度更快
节省磁盘空间
更严格的依赖管理

首次安装配置

步骤 1：进入 PC 端目录

在项目根目录下

cd pc

步骤 2：安装依赖包

安装所有依赖（首次会比较慢，请耐心等待）

pnpm install

⚠️ 重要提示：

安装前务必确认 Node 版本是 16+
如果安装失败，请查看本文档「常见问题」部分
不要使用 npm install 或 yarn install

安装成功的标志：

终端没有报错
生成了 node_modules 文件夹
生成了 pnpm-lock.yaml 文件
步骤 3：复制环境配置文件

PC 端需要配置 3 个环境文件：

在 pc 目录下执行以下命令（Windows 系统）

1. 复制全局配置文件

copy .env.example .env

2. 复制开发环境配置

copy .env.development.example .env.development

3. 复制生产环境配置

copy .env.production.example .env.production

Mac/Linux 系统：
cp .env.example .env
cp .env.development.example .env.development
cp .env.production.example .env.production

💡 文件说明：

.env → 全局配置（所有环境通用）
.env.development → 开发环境配置（本地开发用）
.env.production → 生产环境配置（打包上线用）

环境文件配置详解

4.1 配置文件 1：.env（全局配置）

打开 pc/.env 文件，通常保持默认值即可：

打包后文件存放的位置（指向后端的 public 目录）

VITE_RELEASE_PATH=../server/public

网站的基础路径

VITE_BASE_URL=/

是否开启 SSR（服务端渲染）

留空 = 关闭 SSR（普通 SPA 模式）

填任意值 = 开启 SSR（SEO 模式）

VITE_SSR=

开发服务器端口号

NITRO_PORT=3001

配置说明：

配置项
说明
建议值
VITE_RELEASE_PATH
打包文件输出目录
保持默认
VITE_BASE_URL
网站访问路径
保持 /
VITE_SSR
是否启用 SEO 模式
开发时留空
NITRO_PORT
开发服务器端口
默认 3001

关于 SSR（重要）：

留空 = 普通模式（类似 Vue 单页应用，不支持 SEO）
填 1 = SEO 模式（服务端渲染，支持搜索引擎收录）

💡 新手建议：开发时保持 VITE_SSR= 留空，这样更简单。

4.2 配置文件 2：.env.development（开发环境）

打开 pc/.env.development，配置后端 API 地址：

后端 API 请求地址

VITE_API_URL='http://你的后端地址'

配置示例：

示例 1：本地开发（后端在本地运行）
VITE_API_URL='http://127.0.0.1:8000'

示例 2：连接测试服务器
VITE_API_URL='http://test.yourdomain.com'

示例 3：连接线上服务器
VITE_API_URL='https://api.yourdomain.com'

🎯 重点：这个地址必须是你的后端服务器地址，开发时所有 API 请求都会发送到这里。

4.3 配置文件 3：.env.production（生产环境）

打开 pc/.env.production，配置生产环境的 API 地址：

生产环境的后端 API 地址

VITE_API_URL=''

配置说明：

情况 1：普通打包（非 SEO 模式） ⭐ 推荐新手

保持为空：VITE_API_URL=''
打包后会自动使用当前域名作为 API 地址
例如：网站是 https://www.abc.com，则 API 也请求 https://www.abc.com/api
情况 2：SEO 打包（SSR 模式）
必须填写完整的后端地址：VITE_API_URL='https://api.yourdomain.com'
因为服务端渲染需要明确知道 API 地址

开发模式（本地调试）

配置完成后，就可以启动开发服务器了。

5.1 启动开发服务器

在 pc 目录下执行

pnpm dev

5.2 访问网站

启动成功后，终端会显示：

✔ Nuxt 3.12.4 is ready!

➜ Local: http://localhost:3001/
➜ Network: http://192.168.1.100:3001/

打开浏览器访问：http://localhost:3001

5.3 开发模式特点

✅ 热重载：修改代码后自动刷新页面
✅ 实时预览：可以立即看到修改效果
✅ 错误提示：代码错误会在浏览器中显示
✅ 调试友好：支持 Vue DevTools 等开发工具

💡 提示：开发时不要关闭终端窗口，保持开发服务器运行。

生产环境打包

开发完成后，需要打包成生产版本部署到服务器。

6.1 普通打包（非 SEO 模式）⭐ 推荐新手

适用场景：不需要搜索引擎收录的项目（内部系统、会员系统等）

第 1 步：确认配置

打开 pc/.env，确保 VITE_SSR 为空：

留空表示关闭 SSR

VITE_SSR=

打开 pc/.env.production，VITE_API_URL 留空：

留空表示使用当前域名

VITE_API_URL=''

第 2 步：执行打包命令

在 pc 目录下执行

pnpm build

第 3 步：等待打包完成

打包过程通常需要 1-3 分钟，终端会显示进度。

打包成功的标志：

终端显示 "Build complete"
生成的文件在 server/public/ 目录下
第 4 步：部署

将 server/public/ 目录下的所有文件上传到你的服务器即可。

6.2 SEO 打包（SSR 模式）

适用场景：需要搜索引擎收录的项目（官网、博客、新闻站等）

第 1 步：启用 SSR

打开 pc/.env，给 VITE_SSR 赋值（任意值都行）：

填任意值开启 SSR

VITE_SSR=1

第 2 步：配置生产环境 API 地址

打开 pc/.env.production，必须填写后端地址：

SSR 模式必须指定 API 地址

VITE_API_URL='https://api.yourdomain.com'

⚠️ 重要：SSR 模式下，API 地址不能留空！

第 3 步：执行 SSR 打包命令

在 pc 目录下执行

pnpm build:ssr

第 4 步：部署

SSR 模式的部署比较复杂：

将打包后的文件上传到服务器
在服务器上运行 Node.js 服务（不能只部署静态文件）
配置 PM2 等进程管理工具保持服务运行

💡 新手提示：如果不需要 SEO，建议使用普通打包模式，部署更简单。

开发技巧

7.1 页面路由（自动路由系统）

Nuxt.js 使用文件系统路由，在 pc/src/pages/ 下创建文件即可自动生成路由。

路由规则：

pc/src/pages/
├─ index.vue → 访问路径: /
├─ about.vue → 访问路径: /about
├─ user/
│ ├─ index.vue → 访问路径: /user
│ └─ profile.vue → 访问路径: /user/profile
└─ article/
└─ [id].vue → 访问路径: /article/123（动态路由）

示例：创建一个关于我们页面

创建文件 pc/src/pages/about.vue：
.about-page { padding: 20px; }

保存后，直接访问 http://localhost:3001/about 即可看到页面。

7.2 调用后端 API

方式一：创建 API 文件（推荐）

在 pc/src/api/ 下创建 API 接口文件：

// pc/src/api/article.ts
import request from '@/utils/request'

// 获取文章列表
export function getArticleList(params: any) {
return request.get('/api/article/list', { params })
}

// 获取文章详情
export function getArticleDetail(id: number) {
return request.get('/api/article/detail', { params: { id } })
}

// 创建文章
export function createArticle(data: any) {
return request.post('/api/article/create', data)
}

方式二：在页面中使用

7.3 状态管理（Pinia）

在 pc/src/stores/ 下创建状态管理文件：

// pc/src/stores/user.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
state: () => ({
userInfo: null,
token: '',
isLogin: false
}),

getters: {
// 计算属性
userName: (state) => state.userInfo?.name || '游客'
},

actions: {
// 设置 Token
setToken(token: string) {
this.token = token
this.isLogin = true
},

// 设置用户信息
setUserInfo(info: any) {
this.userInfo = info
},

// 退出登录
logout() {
this.token = ''
this.userInfo = null
this.isLogin = false
}
}
})

在页面中使用：

7.4 组合式函数（Composables）

在 pc/src/composables/ 下创建可复用的逻辑：

// pc/src/composables/useArticle.ts
export const useArticle = () => {
const loading = ref(false)
const list = ref([])

// 获取文章列表
const fetchList = async () => {
loading.value = true
try {
const data = await getArticleList()
list.value = data.lists
} catch (error) {
console.error('获取文章失败', error)
} finally {
loading.value = false
}
}

return {
loading,
list,
fetchList
}
}

在页面中使用：

7.5 SEO 优化

使用 useHead 设置页面标题和描述：

常见问题解决

问题 1：pnpm install 失败

错误提示：
ERR_PNPM_...

解决方法：

方法 1：删除依赖重新安装

rmdir /s /q node_modules
del pnpm-lock.yaml
pnpm install

方法 2：清除 pnpm 缓存

pnpm store prune
pnpm install

方法 3：使用淘宝镜像

pnpm config set registry https://registry.npmmirror.com
pnpm install

问题 2：Node 版本不对

错误提示：
The engine "node" is incompatible with this module

解决方法：

检查 Node 版本：
node -v
如果版本低于 16，请升级 Node.js：

下载地址：https://nodejs.org/
安装 Node 16 或 18 LTS 版本

问题 3：端口被占用

错误提示：
Port 3001 is already in use

解决方法：

方法 1：更换端口

修改 pc/.env 文件：
NITRO_PORT=3002

方法 2：关闭占用进程（Windows）

查找占用端口的进程

netstat -ano | findstr :3001

结束进程（替换为实际的 PID）

taskkill /PID 12345 /F

问题 4：打包后访问白屏

可能原因：

API 地址配置错误
后端服务未启动
路径配置问题
排查步骤：

检查 .env.production 中的 VITE_API_URL 配置
打开浏览器控制台（F12），查看具体错误
检查网络请求是否成功
确认后端服务正常运行

问题 5：API 请求跨域错误

错误提示：
Access to XMLHttpRequest has been blocked by CORS policy

解决方法：

开发环境：配置代理（修改 nuxt.config.ts）
export default defineNuxtConfig({
nitro: {
devProxy: {
'/api': {
target: 'http://127.0.0.1:8000',
changeOrigin: true
}
}
}
})

生产环境：后端需要配置 CORS 跨域支持。

问题 6：热重载不生效

解决方法：

重启开发服务器：

Ctrl+C 停止服务器

然后重新启动

pnpm dev

清除缓存：

删除 .nuxt 目录

rmdir /s /q .nuxt

重新启动

pnpm dev

快速参考

9.1 常用命令

安装依赖

pnpm install

启动开发服务器

pnpm dev

普通打包（非 SEO）

pnpm build

SEO 打包（SSR 模式）

pnpm build:ssr

预览生产版本

pnpm preview

代码检查

pnpm lint

代码格式化

pnpm prettier

9.2 配置文件位置

文件
路径
说明
全局配置
pc/.env
所有环境通用
开发环境
pc/.env.development
本地开发用
生产环境
pc/.env.production
打包上线用
Nuxt 配置
pc/nuxt.config.ts
Nuxt 框架配置
包管理配置
pc/package.json
依赖和脚本
TypeScript 配置
pc/tsconfig.json
TS 配置

9.3 重要目录结构

pc/
├── src/
│ ├── pages/ # 页面文件（自动路由）
│ ├── components/ # 公共组件
│ ├── api/ # API 接口定义
│ ├── stores/ # 状态管理（Pinia）
│ ├── composables/ # 组合式函数
│ ├── layouts/ # 布局组件
│ ├── plugins/ # 插件
│ ├── utils/ # 工具函数
│ ├── assets/ # 静态资源
│ └── app.vue # 根组件
├── .env # 全局配置
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
├── nuxt.config.ts # Nuxt 配置
└── package.json # 项目配置

9.4 开发流程速查

首次开发：

cd pc
pnpm install
copy .env.example .env
copy .env.development.example .env.development
copy .env.production.example .env.production
编辑 .env.development，填写 API 地址
pnpm dev
访问 http://localhost:3001

日常开发：

cd pc
pnpm dev
修改代码
浏览器自动刷新

打包部署：

编辑 .env.production
pnpm build
上传 server/public/ 到服务器

🎯 总结

本指南涵盖了 PC 端二次开发的所有关键步骤：

✅ 环境准备（Node.js、pnpm）
✅ 安装配置（依赖、环境文件）
✅ 开发调试（启动服务、热重载）
✅ 打包部署（普通打包、SEO 打包）
✅ 开发技巧（路由、API、状态管理）
✅ 问题解决（常见错误处理）
下一步：

熟悉 Nuxt.js 官方文档：https://nuxt.com/
学习 Vue 3 组合式 API：https://cn.vuejs.org/
了解 Element Plus 组件：https://element-plus.org/
我来分析一下PC端pages目录的结构和功能模块。
好的！我来为你详细分析一下 PC 端 pages 目录的结构和功能模块，用最简单易懂的方式讲解：

📁 PC 端 pages 目录结构分析

这个 pages 目录是整个 PC 端网站的"页面中心"，每个文件夹就是一个功能模块。我按功能类型给你分类讲解：

🏠 首页与入口

index - 网站首页，展示各种功能入口

💬 对话聊天类（核心功能）

chat - 通用聊天页面
- 支持文本和数字人对话
- 包含登录组件和会话文件管理
dialogue - 对话助手
- chat.vue - 问答助手（文字问答）
- role.vue - 角色助手（不同AI角色扮演）
- 支持文件上传、模型切换
digital - 数字人对话
- 专门用于数字人视频聊天

🎨 AI 创作类

draw - AI 绘画
- 支持多种模型：
  - dalle.vue - DALL-E 模型
  - sd.vue - Stable Diffusion 模型
  - mj.vue - Midjourney 模型
  - doubao.vue - 豆包模型
- 包含完整的绘图工具和设置
creation - AI 文字创作
- 创作中心（生成文章、文案等）
video - AI 视频生成
- 支持上传图片、设置视频风格和尺寸
music - AI 音乐生成
- 包含音乐播放器
ai_ppt - AI PPT 生成
- index.vue - 主页面
- history.vue - 历史记录
- detail.vue - 详情页
- 包含大纲生成、模板选择等组件
digital_human - 数字人制作
- 完整的数字人设计中心
- 支持选择头像、背景、配音、音乐、字幕等

🔍 搜索与工具类

search - AI 搜索
- 支持多种搜索类型和模型
- 包含搜索历史
mind_map - 思维导图
- 思维导图生成和预览

🤖 应用与机器人

application - 应用中心
- robot - 机器人应用（对话、编辑、发布）
- kb - 知识库（数据导入、学习、测试）
- digital - 数字人应用
app_center - 应用中心首页
robot_square - 机器人广场
- 展示各种机器人、绘画、音乐、视频作品

👤 用户中心

user - 用户个人中心
- center.vue - 个人资料
- balance.vue - 余额管理
- member.vue - 会员中心
- recharge.vue - 充值
- notification.vue - 通知
- task_reward.vue - 任务奖励
- promotion - 推广分销
- record - 使用记录
- works - 我的作品
recharge - 充值页面

📄 其他页面

policy - 政策条款（隐私政策、用户协议等）
empty - 空页面（可能是占位页）

🎯 技术特点总结

模块化设计 - 每个功能独立成文件夹，方便维护
组件化 - 大量使用 _components 子目录存放私有组件
多模型支持 - 绘画、对话等功能支持多种 AI 模型切换
文件上传 - 多处支持文件、图片上传功能
响应式布局 - 适配PC和移动端
实时通信 - 使用 SSE（Server-Sent Events）实现实时对话

📊 功能统计

对话类：3 个模块
AI 创作类：6 个模块
应用工具类：5 个模块
用户相关：2 个模块

这是一个功能非常完整的 AI 综合平台，涵盖了对话、绘画、视频、音乐、PPT、思维导图等多种 AI 能力！

祝你开发顺利！🚀