企业官网建设流程全解析

简介：面向Vue3初学者的AI智能聊天演示项目，采用Vue3搭配Element Plus、Sass、TypeScript与Pinia，并接入MateChat实现聊天页面，支持移动端自适应，也可以作为对接私域应用打造AI助手的可复用模块。压缩包内共84个文件，体积6.39MB，其中包含13个Vue组件、25个TypeScript逻辑文件、15个JavaScript脚本、5个Sass样式，以及JSON配置、GLB三维模型、WASM解码器等资源，覆盖组件、状态管理、接口封装、国际化、路由等典型工程目录。已有167人学习下载。项目采用分层结构，视图模块中提供登录、首页、错误页等页面，布局模块内置多种页面布局方案，状态管理基于Pinia实现全局数据与持久化，网络请求模块统一封装接口与枚举，国际化模块支持多语言切换，并加入路由进度条、环境变量配置与编译产物等细节，方便对照源码理解构建流程。对想了解Vue3工程化搭建、移动端适配或AI聊天集成的开发者，这是一份结构清晰、可直接对照学习的实战参考，也能作为私域AI应用的前端基础模板。

1. vue3-Demo 配 MateChat：AI 智能聊天从骨架到可用

vue3 工程搭骨架，MateChat 提供聊天界面，再对接一个大模型接口，AI 智能聊天的最小闭环两个小时就能跑通。但多数人把时间耗在没人提醒的细节上：流式响应刷到一半页面卡住、列表被自动滚动拽回顶部、请求发出去无法取消。

这里不打算复刻花哨的聊天室，而是把 vue3-Demo + MateChat 链路拆开讲：组件怎么选、消息模型怎么设计、SSE 流式怎么接、参数怎么调、上线前躲哪些坑。每章对应一个能复现的步骤，代码按 TypeScript + Vue 3 组合式 API 写。

适合会 Vue 3 基础语法、想自己动手做 AI 聊天应用的前端开发者，也适合后端同学补前端聊天架构常识——不需要很深算法背景，但得理解"流式响应"和"消息状态"，这正是 Demo 能否撑到产品化的分水岭。

2. MateChat 接入实战：初始化工程并挂载聊天组件

组件选型这一步看起来最不起眼，但它决定了第 3、4 章代码的写法。选一个字段映射灵活、增量更新友好的组件，后面全是顺风局；选错，后面全是适配层。先把"用什么"和"为什么不自己写"想清楚，再动手。

2.1 为什么聊天 UI 不该从零写：四个能力与选型标准

一个聊天界面看上去就是"消息列表 + 输入框"，但要真正承载 AI 对话，它得同时具备四件事：流式增量渲染（模型吐一个字，气泡跟着长）、输入状态管理（发送中禁重复提交、可中断）、Markdown 渲染（代码块、表格、链接），以及消息的失败态与重试入口。这些东西从零写，两周都是保守估计，而且写出来的边角问题比功能还多。

一个典型的反例是 A同学 自己写消息渲染，两周后卡在三个地方：流式期间光标闪烁需要手动管理定时器、滚动锚定要兼容不同浏览器、复制按钮在不同气泡高度下对不齐。这些问题组件库基本都踩过一遍，直接拿来用比重复造轮子划算。

用 MateChat 这类 Vue 3 聊天组件库，常见做法是把上面四件事里跟业务无关的部分打包带走。选型时我会看三个标准：第一，组件支持增量更新单条消息而不是每次替换整个列表，这决定了流式吐字会不会卡；第二，props 能否映射消息字段，因为后端回来的消息结构各家不一样，字段不可配的组件后期会很痛苦；第三，插槽是否开放，气泡里要加复制按钮、token 计数时，只有插槽能兜底。

提示：把"组件能不能自动滚动"当默认能力是大忌。自动滚动必须能开关、能设阈值，否则到第 4 章你会为它重写一遍。

2.2 最小跑通：用脚手架初始化并挂载 MateChat 组件

先把手里的 vue3 工程准备好。从零开始的话，用官方脚手架创建工程是最省事的路径，记得选 TypeScript 模板，聊天消息的类型定义在后面几章会反复用到。

# 创建工程，--ts 直接启用 TypeScript npm create vue@latest vue3-demo -- --ts cd vue3-demo npm install # 安装聊天组件库，包名以你实际安装的版本为准 npm install matechat

命令行参数说明：--ts让脚手架把 TypeScript 相关依赖一起装好，省得后面手动补类型配置；npm create vue@latest是官方脚手架，生成的目录结构自带src和构建配置，比手搓文件稳。组件库的包名这里按通用写法示意，装完先打开node_modules里对应的.d.ts确认导出名和样式文件路径，再往下写。

工程就绪后，把聊天组件挂到页面上。App.vue 里最简写法：

<script setup lang="ts"> import { ref } from 'vue' // 具体导出名以你安装版本的类型声明为准 import { MateChat } from 'matechat' import 'matechat/dist/index.css' interface ChatMessage { role: 'user' | 'assistant' content: string } const messages = ref<ChatMessage[]>([ { role: 'assistant', content: '你好，我是你的 AI 助手，有什么可以帮你？' } ]) function handleSend(text: string) { messages.value.push({ role: 'user', content: text }) // AI 回复的接入放在第 3 章，这里先让消息能上屏 } </script> <template> <MateChat :messages="messages" title="AI 智能聊天 Demo" @send="handleSend" /> </template>

这段代码的逻辑说明：messages是传给组件的唯一核心数据源，组件的职责是把数组渲染成气泡列表，它不关心消息从哪来、也不负责回复——@send只把输入框内容抛出来，后续接大模型、接流式，都在handleSend里做。title是聊天窗口标题，通常放在头部栏。

注意：这里用messages.value.push(...)而不是messages.value = [...]。整个数组替换会让组件内部所有气泡重新渲染，小 Demo 里没感觉，一旦消息里带上大段 Markdown，卡顿立刻出现。这个原则第 4 章还会展开。

组件库版本之间差异不小，有的版本消息字段叫id/text/type，有的叫id/role/content；事件名也有send和submit之分。接入前先瞄一眼.d.ts，再决定是改组件入参还是写一层消息适配器。常见做法是在组件外封装一层适配函数，把本地消息结构转成组件认识的字段结构，这样组件升级或更换时，业务代码不用跟着动。这一步花五分钟，能省掉后面一整天的定位时间。

3. 消息模型与服务层：从字符串数组到 SSE 流式解析

消息模型是聊天应用的地基。很多人先写页面再补数据结构，结果流式接进来时发现字符串数组根本没法表达"正在生成"这个状态，只好回头重构。这一章把数据结构和接口封装一起定下来，后面所有功能都在这两层上长出来。

3.1 消息数据结构：为什么字符串数组撑不起 AI 对话

新手阶段最常见的写法是messages: ref<string[]>，把用户和 AI 的话混在一个数组里。这在纯展示场景够用，一旦要接流式就露馅：你没法表达"这条消息正在生成中"，也没法在出错时只给这条消息标红，更没法记住每条消息的时间戳用于后续会话排序。

我一般会把一条消息定义成下面这样，id和status是撑起流式的两个关键字段：

export type ChatRole = 'system' | 'user' | 'assistant' export interface AIMessage { id: string // 消息唯一 ID，流式更新、定位、重试都靠它 role: ChatRole // 角色决定气泡样式，也是发给服务端的身份字段 content: string // 文本内容，流式期间由增量不断追加 status: 'pending' | 'streaming' | 'done' | 'error' createdAt: number // 时间戳，会话排序与本地恢复用 error?: string // status 为 error 时，记录给用户看的失败原因 }

字段参数说明：status是这个模型的心脏。streaming状态驱动输入框旁边的"停止"按钮和气泡里的光标闪烁；error状态让该条消息变成可点击重试的样式，而不是整页弹 toast。createdAt看起来不起眼，到第 6 章做本地持久化和会话截断时，你会发现没有时间戳根本没法可靠恢复顺序——这是很多人后面补课的地方。

服务端要求的历史记录格式和前端展示格式不完全一样：发给大模型只需要role和content，多余字段会影响部分服务的请求体校验。所以我在服务层里做一次映射，只挑这两个字段发送，其余字段留在前端本地用。这层映射也是后面接不同服务商时的唯一改动点。

3.2 服务层封装：用 fetch 解析 SSE 流式响应

大模型接口返回流式文本时，绝大多数走的是 SSE 协议，也就是一段一段的data: <json>行。用浏览器原生fetch就能读，Demo 阶段不需要引入 WebSocket 或第三方 SDK。封装成异步生成器是最干净的做法，调用方用for await逐段拿增量文本。

import type { AIMessage } from '../types' export interface ChatParams { temperature?: number // 随机性，0~2，聊天场景默认 0.7 maxTokens?: number // 单次回复的最大 token 数 topP?: number // 核采样，0~1，与 temperature 二选一调整 } export async function* streamChat( history: AIMessage[], params: ChatParams, signal?: AbortSignal ): AsyncGenerator<string> { // 发给服务端只保留角色和内容两个字段 const messages = history.map(({ role, content }) => ({ role, content })) const response = await fetch('/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages, ...params }), signal // 第 5 章做中断请求时传入 }) if (!response.ok) throw new Error(`请求失败：HTTP ${response.status}`) if (!response.body) throw new Error('当前环境不支持流式读取') const reader = response.body.getReader() const decoder = new TextDecoder('utf-8') let buffer = '' while (true) { const { done, value } = await reader.read() if (done) break // stream: true 让解码器缓存半个字符，防止中文被拦腰截断 buffer += decoder.decode(value, { stream: true }) const lines = buffer.split('\n') buffer = lines.pop() ?? '' // 最后一行可能不完整，留到下一轮 for (const line of lines) { const text = line.trim() if (!text.startsWith('data:')) continue const payload = text.slice(5).trim() if (payload === '[DONE]') return // 增量文本在不同服务商返回里字段名不同，以实际响应为准 const json = JSON.parse(payload) yield json.delta ?? json.content ?? '' } } }

这段代码里有三个细节决定它能不能稳定跑：第一，buffer = lines.pop()处理半行分包——网络包不可能恰好按行切，最后一段可能是半个data:行，攒到下一轮拼完整再解析；第二，TextDecoder的{ stream: true }参数处理多字节字符被拆到两个包里的情况，没有它，中文回复大概率出现乱码；第三，[DONE]是服务端约定的结束标记，必须先判断再JSON.parse，否则会把结束标记当 JSON 解析直接抛异常。

yield json.delta ?? json.content ?? ''这句是适配不同服务商响应的关键。有的返回choices[0].delta.content，有的直接给content字段，还有的用delta.text。接入前先用curl打一次接口，确认实际字段路径，再改这一行的取值逻辑。整个服务层只有这一处跟具体服务商耦合，把变化点收敛在这里，后面换模型、换网关都不用动组件代码。

4. 流式渲染与参数调整：让打字机不卡不跳不乱

服务层就绪后，接下来是把它接进页面并让输出"像人话"。这一章解决两件事：增量渲染和滚动锚定这两个底层约束怎么落地，以及 temperature、top_p、max_tokens 这些参数到底怎么调。上一章写的消息模型在这里正式发挥作用。

4.1 增量更新与滚动锚定：打字机效果的两个底层约束

把流式接口接到页面，第一个坑就是更新方式。最直观的写法是每次拿到增量就messages.value = [...messages.value]替换整个数组。在本地接口、几十条消息时看不出问题；一旦消息里有大表格、有代码块，每几十毫秒全量 diff 一次，渲染线程直接被打满，气泡滚动就变成幻灯片。

正确做法是保持数组引用不变，只修改正在流式更新的那一条消息的content。Vue 3 的reactive代理会精准追踪对象属性变化，只重渲染依赖这条消息的组件节点。把发送逻辑收进组合式函数，页面组件保持干净：

import { nextTick, ref } from 'vue' import type { AIMessage } from '../types' import { streamChat } from '../services/chat' export function useChat() { const messages = ref<AIMessage[]>([]) const isStreaming = ref(false) const listRef = ref<HTMLElement | null>(null) let abortController: AbortController | null = null // 距底部 120px 以内才允许自动滚动，超出则说明用户在回看 function shouldAutoScroll() { const el = listRef.value if (!el) return true return el.scrollHeight - el.scrollTop - el.clientHeight < 120 } async function scrollToBottom() { await nextTick() const el = listRef.value if (el && shouldAutoScroll()) el.scrollTop = el.scrollHeight } async function send(text: string) { if (isStreaming.value) return // 上一次未结束，禁止连发 const now = Date.now() const userMsg: AIMessage = { id: crypto.randomUUID(), role: 'user', content: text, status: 'done', createdAt: now } const aiMsg: AIMessage = { id: crypto.randomUUID(), role: 'assistant', content: '', status: 'streaming', createdAt: now } messages.value.push(userMsg, aiMsg) isStreaming.value = true abortController = new AbortController() try { const history = messages.value.map(({ role, content }) => ({ role, content })) for await (const delta of streamChat(history, { temperature: 0.7 }, abortController.signal)) { aiMsg.content += delta // 只改单条 content，不替换数组 await scrollToBottom() } aiMsg.status = 'done' } catch (err) { aiMsg.status = 'error' aiMsg.error = (err as Error).message } finally { isStreaming.value = false abortController = null await scrollToBottom() } } return { messages, isStreaming, listRef, send } }

参数说明：120px 是自动滚动的触发阈值，它是手感参数，调太小会在快到底时反复开关滚动，调太大会把回看用户强行拽下去，实测 80~160px 之间差别不大，120 是稳妥默认值。isStreaming有双重作用：一是防连发，二是给输入框和"停止"按钮提供状态。abortController这章先挂着，第 5 章讲中断时你会看到它正是为组件卸载和用户点停止准备的。

4.2 三个必调参数与一个常被忽略的 system prompt

Demo 跑通流式之后，下一步是让回复"像个人话"。大模型接口里最常动的是三个参数，外加一个不在请求参数列表里的隐藏项：

参数调整的常见做法是：temperature 和 top_p 只动其中一个，另一个保持默认，因为两个一起调手感会互相抵消，很难判断是谁的功劳。max_tokens的坑在于截断没有明显标记，用户看到一半话就结束，第一反应是"模型坏了"。如果产品允许，把截断做成可见状态——消息停在done但长度异常时，展示一条"回复已达长度上限"的提示。

system prompt的作用常被新手低估。人设、禁止事项、回答风格放在 system 里，比塞进用户消息稳定很多，因为用户后续提问不会覆盖掉这段系统设定。我习惯把 system prompt 作为历史数组的第一条消息传给服务端，前端展示时过滤掉它，只渲染 user 和 assistant 两种气泡。

5. 避坑指南：AI 聊天 Demo 的五个翻车点与排查思路

这一章是给"能跑但不敢用"的 Demo 准备的。五个问题都是踩坑积累下来的高频场景，按 现象 → 原因 → 解决 的顺序写，方便你对着排查。前三个是渲染层问题，后两个是生命周期与状态管理问题，基本覆盖了聊天应用 80% 的线上翻车。

5.1 流式输出卡顿，长回复时甚至白屏

现象：回复到一半，页面滚动明显掉帧，CPU 占用接近满载，消息里带大表格时直接白屏。原因是两种常见误写：一是每次增量都messages.value = [...messages.value]整体替换数组，让 Vue 对整个列表重新 diff；二是把 Markdown 渲染做成同步组件，每几十毫秒把同一段大表格重复编译一遍。

解决：回到 4.1 的增量更新方式，只改单条消息的content，数组引用保持不动；Markdown 渲染改成异步组件并做结果缓存，渲染过的内容不要重复解析。排查时可以打开 Vue 开发者工具的时间线面板，看每次增量后的渲染耗时曲线，呈锯齿状基本就是全量替换导致的。白屏大多是渲染超时被浏览器中断，先解决全量替换，再考虑拆组件。

5.2 自动滚动把正在回看的用户拖回底部

现象：用户往上翻历史消息想回看前文，新 token 一到就被强制滚到底部，阅读节奏完全被打断。

原因：写死了"每一次增量都scrollToBottom"，没有判断用户当前视口位置。组件库默认开启自动滚动时也一样，很多组件只是简单地在更新后执行一次到底，不具备回看感知。

解决：按 4.1 的shouldAutoScroll方案加阈值判断，距离底部 120px 以内才滚。另外加一个暂停标志位：用户主动向上滚动后，即使距离小于阈值也应暂停自动滚动，直到他再次滚到底部才恢复。监听scroll事件时注意不要高频操作，用requestAnimationFrame节流一下。

5.3 AI 输出的 Markdown 里带 HTML，页面被注入

现象：模型回复里出现<img src=x onerror=...>之类的内容，页面弹窗、跳转，或者样式被改乱。

原因：用了v-html直接渲染 AI 输出，或者 Markdown 渲染库默认放行原始 HTML。大模型输出来自外部数据，本质上和用户输入一样不可信，直接当 HTML 渲染等于把执行权交给模型。

解决：不要对 AI 输出用v-html。选能过滤原始 HTML 的渲染方案，只放行白名单标签；链接统一拦截外链，补target="_blank" rel="noopener noreferrer"，防止新开页面时被反向控制窗口。Demo 阶段宁可少渲染部分格式，也不要裸奔。

5.4 组件卸载后请求还在跑，日志刷屏

现象：从聊天页切走，控制台持续报读流失败的错，接口请求占着连接不释放，浏览器标签页都变卡。

原因：组件卸载了，但streamChat里的fetch没中断，异步生成器还卡在reader.read()上等数据。Vue 不会自动帮你取消外部请求，这个生命周期得自己兜。

解决：用AbortController。组件里加onUnmounted(() => abortController?.abort())，streamChat把signal传给fetch，生成器在finally里正常退出。前面 3.2 代码里预留的signal参数就是干这个的，别删。

5.5 刷新页面上下文全丢，AI"失忆"

现象：刷新后 AI 不记得刚聊的内容，用户得重新自我介绍，会话无法续接，体验和匿名聊天没区别。

原因：消息只存在前端内存ref里，没有落盘；服务端无状态，每次请求只拿到当前页面传过去的历史，页面一刷新历史就归零。

解决：用 localStorage 存最近一个会话，写入时带schemaVersion字段；恢复时先校验版本再解析，版本不匹配直接丢弃，防止旧数据结构把新代码打崩。createdAt在这里派上用场——恢复消息数组后按时间戳排序，顺序才可靠。注意控制存储量，只存最近一个会话的最近几十条，不要无脑全存。

6. 进阶：把 Demo 改成能连续干活的聊天工具

Demo 和工具的差别，在于能不能不盯着屏幕也能把活干完。三个小改造值得做：会话管理、中断与重试、上下文截断。

会话管理按sessionId分组存储，localStorage 只留最近三个会话，每个会话恢复时截断到最近 20 条再发给服务端。这既控制 token 成本，也避免历史太长拖慢首字返回时间。中断用 4.1 里的abortController：aiMsg 处于streaming状态时显示停止按钮，点击调用abort()，finally块会把状态置为done；error状态的消息旁放重试按钮，复用send的同一套逻辑，但只重发失败那一刻之前的历史。

上下文截断有更省事的做法：不搞摘要压缩，只保留最近 N 条消息。想快速上线的人可以直接这么做，摘要压缩等技术方案等有真实需求再上。验证是否达标，可以关掉网络模拟断流，确认error状态能重试；把max_tokens调到 30，确认截断有友好提示；把temperature调到 1.5，确认回复发散但还算人话。

我自己做这类 Demo 的习惯是：先让"流式不卡"和"可中断"两条底线成立，再谈界面美化。很多翻车不是模型的问题，而是前端状态管理没兜住——消息状态、滚动锚定、请求生命周期，这三件事想清楚，聊天应用的地基就稳了。如果你也卡在某一步，按第 5 章的排查顺序过一遍，多半能定位到具体环节。希望帮到你。

本文还有配套的精品资源，点击获取