简介面向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 配 MateChatAI 智能聊天从骨架到可用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 vuelatest vue3-demo -- --ts cd vue3-demo npm install # 安装聊天组件库包名以你实际安装的版本为准 npm install matechat命令行参数说明--ts让脚手架把 TypeScript 相关依赖一起装好省得后面手动补类型配置npm create vuelatest是官方脚手架生成的目录结构自带src和构建配置比手搓文件稳。组件库的包名这里按通用写法示意装完先打开node_modules里对应的.d.ts确认导出名和样式文件路径再往下写。工程就绪后把聊天组件挂到页面上。App.vue 里最简写法script setup langts import { ref } from vue // 具体导出名以你安装版本的类型声明为准 import { MateChat } from matechat import matechat/dist/index.css interface ChatMessage { role: user | assistant content: string } const messages refChatMessage[]([ { role: assistant, content: 你好我是你的 AI 助手有什么可以帮你 } ]) function handleSend(text: string) { messages.value.push({ role: user, content: text }) // AI 回复的接入放在第 3 章这里先让消息能上屏 } /script template MateChat :messagesmessages titleAI 智能聊天 Demo sendhandleSend / /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: refstring[]把用户和 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 ): AsyncGeneratorstring { // 发给服务端只保留角色和内容两个字段 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 refAIMessage[]([]) const isStreaming ref(false) const listRef refHTMLElement | 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 promptDemo 跑通流式之后下一步是让回复像个人话。大模型接口里最常动的是三个参数外加一个不在请求参数列表里的隐藏项参数作用建议起点调大 / 调小的影响temperature控制回复随机性0.7调大更发散更有灵感调小更稳定更贴近事实top_p核采样按概率累计截断候选词0.9一般和 temperature 二选一别同时猛调max_tokens限制单次回复长度512~1024调太小会说到一半被截断观感像 Bugsystem prompt设定角色、语气与行为边界按产品定写好它比在每条用户消息里反复强调稳得多参数调整的常见做法是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 srcx onerror...之类的内容页面弹窗、跳转或者样式被改乱。原因用了v-html直接渲染 AI 输出或者 Markdown 渲染库默认放行原始 HTML。大模型输出来自外部数据本质上和用户输入一样不可信直接当 HTML 渲染等于把执行权交给模型。解决不要对 AI 输出用v-html。选能过滤原始 HTML 的渲染方案只放行白名单标签链接统一拦截外链补target_blank relnoopener 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 里的abortControlleraiMsg 处于streaming状态时显示停止按钮点击调用abort()finally块会把状态置为doneerror状态的消息旁放重试按钮复用send的同一套逻辑但只重发失败那一刻之前的历史。上下文截断有更省事的做法不搞摘要压缩只保留最近 N 条消息。想快速上线的人可以直接这么做摘要压缩等技术方案等有真实需求再上。验证是否达标可以关掉网络模拟断流确认error状态能重试把max_tokens调到 30确认截断有友好提示把temperature调到 1.5确认回复发散但还算人话。我自己做这类 Demo 的习惯是先让流式不卡和可中断两条底线成立再谈界面美化。很多翻车不是模型的问题而是前端状态管理没兜住——消息状态、滚动锚定、请求生命周期这三件事想清楚聊天应用的地基就稳了。如果你也卡在某一步按第 5 章的排查顺序过一遍多半能定位到具体环节。希望帮到你。本文还有配套的精品资源点击获取