企业官网建设流程全解析

Vue3+SSE实现RAG知识库问答，我在前端踩过的8个实战坑

技术栈：Vue3 + TypeScript + Pinia + SSE + Element‑Plus 项目背景：企业私有文档RAG问答平台，实现PDF/TXT文档上传、SSE流式对话、Markdown渲染、答案溯源、长上下文对话，把Demo落地到真实生产环境，记录前端侧踩过的真实问题与解决方案。

摘要

很多教程讲RAG都聚焦后端向量库、文档切片、大模型调用，很少讲前端工程落地。我在开发RAG知识库问答平台过程中发现：Demo跑通只是第一步，真正上线后SSE断连、DOM卡顿、Markdown乱码、溯源失效、上下文溢出、异常兜底等问题接踵而至。本文全部来自真实项目复盘，每个坑包含现象、根因、可直接复制的代码方案，适合正在做AI问答、RAG前端交互的同学参考。

目录

1. 坑1：原生EventSource无法携带token鉴权
2. 坑2：SSE流式高频追加文本，页面主线程卡顿、网页无响应
3. 坑3：SSE分片截断，JSON解析直接报错崩溃
4. 坑4：Markdown流式渲染错乱，换行、代码块格式全部失效
5. 坑5：没有处理[DONE]结束标记，连接不会关闭，内存持续上涨
6. 坑6：答案溯源引用错位，检索片段和AI回答对不上
7. 坑7：多轮对话上下文无限累加，请求越来越大，回答越来越慢
8. 坑8：没有手动中断机制，用户反复提问，多个SSE连接并发堆叠
9. 生产环境额外注意点
10. 总结

坑1：原生EventSource无法携带token鉴权

现象本地Demo用EventSource可以接收流式数据；接入项目鉴权后，后端需要header携带token，原生EventSource不支持自定义请求头，只能拼在url参数里，token暴露在日志中，存在安全风险。

根因浏览器标准API限制，EventSource构造函数第二个参数仅支持withCredentials，不能自定义headers。

解决方案放弃EventSource，使用fetch + ReadableStream手动解析SSE流，可以自由设置Authorization请求头。

/** fetch实现SSE流式请求，支持token鉴权 */ async function createSSEStream(query: string, sessionId: string) { const res = await fetch("/api/rag/stream/chat", { method: "POST", headers: { "Content‑Type": "application/json", "Authorization": `Bearer ${localStorage.getItem("token")}` }, body: JSON.stringify({ query, sessionId }), }); if (!res.ok || !res.body) throw new Error("流式接口请求失败"); // 获取可读流读取器 const reader = res.body.getReader(); const decoder = new TextDecoder("utf‑8"); let buffer = ""; // 分片缓冲区，解决跨chunk截断问题 while(true) { const { done, value } = await reader.read(); if(done) break; const chunk = decoder.decode(value, { stream: true }); buffer += chunk; // 按SSE标准双换行分割事件 const events = buffer.split("\n\n"); buffer = events.pop() || ""; for(const eventStr of events) { if(!eventStr.startsWith("data: ")) continue; const payload = eventStr.slice(6); if(payload === "[DONE]") return; try { const json = JSON.parse(payload); // 处理每一块delta数据 onStreamMessage(json); } catch(err) { console.warn("单条事件解析忽略", payload); } } } }

重点：一定要维护buffer缓冲区，不能直接解析每一次拿到的chunk，避免一个JSON被切分到两次网络包。

坑2：SSE流式高频追加文本，页面主线程卡顿、网页无响应

现象大模型输出速度快，每收到一小块就直接responseText.value += delta，Vue3响应式反复触发更新；回答内容较长时CPU飙升，页面滚动卡顿，浏览器弹出“网页无响应”。

错误写法（不要直接抄）

// ❌ 高频修改ref，每次都触发完整DOM更新 event.onmessage = (e)=>{ answerText.value += e.data.delta; }

根因每一次token推送都会触发Vue响应式更新、diff、DOM渲染；短时间内上千次更新把主线程占满。

解决方案

1. 使用防抖增量渲染，内存变量累积文本，间隔50ms再同步给响应式变量；
2. 聊天框开启虚拟滚动，避免DOM节点过多。

let rawAnswer = ""; // 内存原始字符串 let renderTimer:number|null = null; // 收到流数据，先写到内存变量 function onStreamMessage(json:any) { rawAnswer += json.delta || ""; // 防抖，合并多次更新，降低DOM渲染频次 if(renderTimer) return; renderTimer = window.setTimeout(()=>{ answerText.value = rawAnswer; renderTimer = null; // 聊天框自动滚动到底部 scrollToBottom(); }, 50) } // 流结束清空定时器 function onStreamEnd(){ if(renderTimer) clearTimeout(renderTimer); answerText.value = rawAnswer; }

坑3：SSE分片截断，JSON解析直接报错崩溃

现象控制台偶发JSON.parse: unexpected end of data；复现概率不高，长回答时更容易出现。

根因TCP流式传输，后端输出的一条完整JSON，可能被网络切分到两个ReadableStream数据包。第一次拿到半截JSON，直接JSON.parse就会抛异常，整个对话中断。

解决方案上面示例代码里的buffer缓冲区，把不完整片段留在buffer，等待下一次chunk拼接完整再解析，这是生产环境必不可少逻辑，Demo经常省略。

坑4：Markdown流式渲染错乱，换行、代码块格式全部失效

现象流式一边输出一边渲染Markdown，换行丢失、代码块符号错乱；如果对接收的每一段chunk做.trim()，会直接吃掉换行，格式彻底坏掉。

根因

1. 不要对分片数据随意trim()；
2. Markdown解析库（marked/markdown‑it）不适合“半截文本”实时解析，中途截断会破坏语法。

方案

不每收到delta就执行markdown解析；内存累积完整原始Markdown文本，防抖之后再交给渲染组件渲染。

• ❌ 错误：拿到一小段就丢给marked.parse
• ✅ 正确：内存累积完整字符串，防抖后一次性更新视图，由组件完整渲染markdown。

<!-- Vue模板示例 --> <div class="answer-box" v‑html="renderMarkdown(answerText)" />

坑5：没有处理[DONE]结束标记，连接不会关闭，内存持续上涨

现象问答结束，网络连接还挂在浏览器network面板；多次问答后连接越来越多，内存持续上涨。

根因后端SSE流结束时会发送data: [DONE]\n\n标记；前端如果没有捕获，Reader不会执行reader.cancel()，流资源不会释放。

处理要点

if(payload === "[DONE]") { await reader.cancel(); // 主动关闭流读取器，释放连接 onStreamEnd(); return; }

同时页面销毁（onUnmounted）的时候，也要调用reader.cancel做销毁兜底，防止组件销毁连接还在跑。

坑6：答案溯源引用错位，检索片段和AI回答对不上

现象AI回答附带引用序号，点击溯源，打开的文档片段和当前句子无关；幻觉情况下引用完全乱跳。

根因

1. 大模型流式输出，引用标记穿插在文本流中间，增量解析很难精准拆分；
2. 检索来源数据一次性返回，和流式answer时序不同步。

工程上折中方案：

1. 参考文档列表不跟着流实时渲染，等[DONE]接收完毕之后再渲染全部溯源来源卡片；
2. 模型输出内联引用标记，回答结束后整体正则解析引用编号，映射到来源数组；
3. UI明确区分：参考片段不等于答案一定正确，仅供核验，提示用户注意幻觉风险。

不要试图一边流式打字，一边实时解析内联引用，会出现大量时序bug。

坑7：多轮对话上下文无限累加，请求越来越大，回答越来越慢

现象连续十几轮对话，POST请求body体积暴涨；接口响应变慢，偶尔超时。

根因每一轮把全部历史对话原样塞进请求，上下文无上限累积，很快耗尽模型上下文窗口。

解决方案

1. 前端设置最大历史轮数，例如最多保留8轮历史；
2. 提供「清空上下文」按钮，允许用户重置会话；
3. 简单策略：超长时丢弃最早的历史消息，保留最近对话；复杂方案交给后端做摘要压缩。

// 控制历史消息数量 function pushChatHistory(msg:ChatItem) { chatHistory.value.push(msg); const MAX_HISTORY = 8; if(chatHistory.value.length > MAX_HISTORY) { chatHistory.value.splice(0, chatHistory.value.length‑MAX_HISTORY); } }

坑8：没有手动中断机制，用户反复提问，多个SSE连接并发堆叠

现象用户快速连续点发送按钮，同时存在多个SSE流，多条AI回答混杂输出，界面错乱。

解决方案

1. 设置状态锁，请求中禁用发送按钮；
2. 保存当前reader实例，新提问到来时调用上一个reader.cancel()，终止上一条流。

let currentReader:ReadableStreamDefaultReader|null = null; async function sendQuestion(query:string) { if(isLoading.value) return; // 如果上一个流还在跑，强制终止 if(currentReader) { await currentReader.cancel(); currentReader = null; } isLoading.value = true; rawAnswer = ""; try { const res = await fetch("/api/rag/stream/chat", {...}); currentReader = res.body!.getReader(); // ...读取流逻辑 } finally { isLoading.value = false; currentReader = null; } }

UI增加停止生成按钮，调用reader.cancel()，给用户手动中断能力。

生产环境额外注意点

1. Nginx代理SSE问题：Nginx默认开启缓冲，会把流式数据攒一大块再下发，打字机效果变成一大段一大段蹦出来。需要Nginx关闭proxy缓冲：

location /api/rag/stream { proxy_buffering off; proxy_cache off; }

1. 超时处理：大模型思考时间长，调大接口超时时间，前端设置超时定时器，长时间没返回主动cancel流并提示用户。
2. 异常兜底：网络断开、500、502，必须捕获异常，不要白屏，保留用户输入，提供重试按钮。
3. 鉴权销毁：用户退出登录，务必cancel全部活跃SSE连接，防止后台继续推送。

总结

很多同学做RAG前端，以为就是调一个SSE接口，把返回文本打印出来；真正上生产才发现坑大多集中在流处理、内存管理、时序同步、异常兜底。

1. Demo可以用EventSource，生产环境优先fetch+ReadableStream，解决token鉴权；
2. SSE务必做buffer分片拼接，处理[DONE]结束信号，及时cancel释放连接，防止内存泄漏；
3. 高频流式输出不要每块都触发完整DOM渲染，防抖合并更新，避免主线程卡死；
4. Markdown渲染、溯源引用，尽量等一轮回答结束后完整解析，不要在增量分片上做复杂解析；
5. 增加状态锁、手动中断、历史消息上限，避免用户乱操作带来的界面错乱；
6. 不要忽略Nginx反向代理对流式接口的影响。

RAG系统，后端决定能不能答，前端决定好不好用、稳不稳定。希望这篇踩坑记录帮大家少走弯路。