流式输出到底是个啥？我用大白话捋明白了

很多人第一次见流式输出。觉得挺神奇，点一下按钮字一个一个往外蹦，像有人在对面打字一样。其实拆开看特别朴素，

你就这么想的观点是。普通的接口请求，就像你去饭店点菜，厨房把整道菜做好了服务员才端给你。等菜的过程你啥也看不见，只能干坐着。流式输出呢，就像去吃铁板烧，厨师煎好一块就给你夹一块，你边吃他边做。总耗时其实没差多少，但你不用干等，全程都有反馈，体感上就快了很多。

放到技术上讲，大模型生成内容本来就不是一下子算完的。它是一个 token 一个 token 往后推的。其实，普通请求是等所有 token 都生成完。打包成一个 JSON 一次性返回给你；流式输出就是生成一个 token 就往连接里写一个。前端接收到一点就拼到页面上一点，看起来就成了打字机效果。

这里面其实没什么黑科技，就是两边提前约定好了：

• 客户端请求的时候带个 stream: true告诉服务端我要流式的，别攒着
• 服务端收到之后就不一次性返回了保持连接不断。生成一点发一点
• 数据格式也约定好，每一段数据都以 data: 开头，一行一条，结束的时候发个 data: 标记

就这么简单。按理说，本质上还是 HTTP 请求。只是服务端不马上断开连接，持续往响应体里写数据而已。不过，

先把基础的 Vue 页面搭起来

说回我的页面我用 Vue3 写的。就一个单文件组件，特别简单。实际来说我之前对 Vue 的组件化理解一直停留在 “就是把代码拆成文件”，这次写小 demo 反而突然想通了。你就把每个.vue 文件当成一块乐高积木。这块积木自己带样子、带逻辑、带样式，拼到一起就是一整个页面。不用像以前那样 html、css、js 文件分开找。改一个功能就在一个文件里搞定，小功能快速迭代更省心。

痛点提示： - 输入框无响应时会出现卡顿 - 长文本时界面完全冻结。让人难以判断是否真正得到结果 - 多次点击提交导致请求堆积，占用网络资源

这里说句题外话：v-model 这东西刚学时觉得挺玄乎，但后来发现它只是一种语法糖，把双向绑定隐藏起来让开发者专注业务逻辑，而不是手动处理事件和 DOM 更新。按理说，

import { ref } from 'vue';const question = ref;const stream = ref;const content = ref;

再看第一版，非流式请求。即使跑通也难用

最开始我写的是最普通的 POST 请求，没有任何流式支持。按理说，实现方式与调用其他 REST API 没区别：

const update = async => {
if return;content.value = '思考中...';const response = await fetch(import.meta.env.VITE_DEEPSEEK_API_BASE_URL,{
至于method，'POST',headers: {
'Authorization': `Bearer ${import.meta.env.VITE_DEEPSEEK_API_KEY}`。'Content-Type': 'application/json',},body: JSON.stringify({
model这方面，import.meta.env.VITE_DEEPSEEK_API_MODEL,messages:,stream: false,// 关闭流式，一次性返回
})
});const data = await response.json;content.value = data.choices.message.content;
}

痛点： - 长文本生成时页面会“挂起”数秒，让使用者误以为已崩溃 - 多次点击导致同一请求被重复发送，占用资源 - 使用者无法感知进度，只能等到结果才能判断是否成功

再看改成流式，踩到第一个大坑 —— 中文乱码

I turned on stream mode,n read `response.body` with a reader. At first glance it seemed trivial – just decode chunks and append m to DOM – but I encountered sporadic Chinese garbles when outputting Chinese characters.

• The issue stems from UTF‑8 encoding where a single Chinese character spans multiple bytes.
• The reader may split a character across two chunks。causing partial decoding and garbled symbols.
• A proper solution requires using a streaming TextDecoder that buffers incomplete characters.
• You also need an additional line buffer to handle incomplete SSE lines across reads.

if {
content.value = '';const reader = response.body?.getReader，// 必须开启 TextDecoder 流模式，否则中文易乱码
const decoder = new TextDecoder;let doneReading = false;let buffer = '';while {
const { value,done } = await reader.read;doneReading = done;// 解码并缓存未完成字符
buffer += decoder.decode;// 按换行切分每条 SSE 数据
const lines = buffer.split;buffer = lines.pop || '';for {
const trimmed = line.trim;if ) continue;按理说，const jsonStr = trimmed.slice.trim;// 去掉 "data:" 前缀
if continue;try {
const parsed = JSON.parse;const delta = parsed?.choices，.?.delta，.content?，'';if content.value += delta;} catch { /* ignore malformed data */ }
}
}
}

关键提示： - 开启 { stream:true } 解码器才能正确处理多字节字符 - 每次读取后务必按行切分，并保留最终未完整的一行到下轮处理

环境变量坑补丁

I initially stored API key directly in code。which is insecure and frowned upon. I moved it to a `.env.local` file:

# .env.local
VITE_DEEPSEEK_API_KEY=YOUR_KEY_HERE
VITE_DEEPSEEK_API_BASE_URL=https://api.deepseek.com/v1/chat/completions
VITE_DEEPSEEK_API_MODEL=gpt-4o-mini

• If you forget `VITE_` prefix,Vite will not expose variable to your bundle – you'll get `undefined`.
• Your front‑end should never expose sensitive keys in production—proxy through a back‑end server instead.

从主要原理揭秘来看，SSE vs WebSocket 与大模型推理流程匹配度高于预期？

• SSE 是单向推送协议；WebSocket 是双向通信。我只需要从服务器单方向推送实时 token 给浏览器，所以 SSE 更轻量且足够使用。
• SSE 使用标准 ``>` 行分隔格式。在大模型返回的数据结构中被直接利用，以 ``>` 为前缀标识数据行。
• SSE 与大模型内部按 token 推理天然匹配——不需要额外加速。仅仅是在网络层把每一步即时暴露给使用者，这样就能实现“打字机”体验。老实说，

坑清单

1. 中文乱码：   + 缓冲区处理完整行/字符；
2. SSE 行不完整：  ；
3. 环境变量前缀错误：  ；
4. Error handling：   防止单条错误影响整体流；
5. 标记解析：  ;

何时使用流式输出？何时避免，

• 📖#使用者体验至上：* 当结果需要实时展示给终端使用者时引入流式可明显提高感知速度*。
• 💾#后端代理必不可少：* 若需在生产环境公开 API。请通过后端代理隐藏密钥，而非直接放在前端代码中*。
• 📈#数据完整性关键场景慎用：* 如果业务需要先拿到完整内容再做批量处理或分析，则一次性返回更合适*。