1. 瀏覽器里做 AI 打字機為什么你寫的流式渲染總是一卡一卡先說清楚我們要解決的是什么問題。AI 打字機效果指的是大模型返回內容時前端不是等整段文字生成完再一次性顯示而是像有人坐在屏幕前一個字一個字敲出來那樣邊接收邊渲染。它適合所有做 AI 對話、AI 寫作、代碼助手類產品的同學尤其是前端工程師和全棧開發(fā)者。聽起來簡單真做起來坑不少。我見過太多項目接口明明已經用了 SSE 或者 fetch 流式頁面上卻還是「憋一大段突然蹦出來」或者「字是一個個出但滾動條抖得像地震」。核心原因通常有三個第一沒搞清楚 ReadableStream 的分塊邊界把半截 UTF-8 字節(jié)當成完整字符解碼第二每收到一個 chunk 就 setState 一次React 高頻重渲染直接把主線程打滿第三長文本不斷追加 DOM瀏覽器布局和重繪成本隨字數線性上漲。這三個問題疊在一起表現就是首字延遲高、幀率掉到 20 以下、滾動卡頓。而它們跟模型本身關系不大純粹是瀏覽器端的接收與渲染策略問題。所以這篇不講模型選型只講怎么把「流」接穩(wěn)、把「字」打順、把「滾」做滑。在動手之前你需要一個能穩(wěn)定輸出流式響應的 API 通道。多模型切換時如果每個模型一套 Key、一套鑒權、一套 base_url前端光維護配置就夠嗆。我這邊統一走 TaoToken 的 Key 通道一個 Key 打通多家模型的流式接口前端只需要認一個 base_url 和一種響應格式省掉大量適配代碼。下面所有示例都基于這個前提來寫。2. TaoToken 統一 Key 通道一個 base_url 接多家流式模型2.1 為什么流式場景更需要統一通道普通請求你還能容忍每個模型寫一套調用邏輯但流式渲染對響應格式的敏感度高得多。不同廠商的 SSE 事件名、data 結構、結束標記都不一樣前端解析層會被撕成好幾份。TaoToken 的做法是把這些差異收斂到服務端對外暴露 OpenAI 兼容的/v1/chat/completions流式接口前端拿到的 chunk 結構一致解析邏輯只寫一遍。對打字機效果來說這意味著你的 ReadableStream 處理函數、逐字渲染隊列、結束判斷全都可以復用換模型不用改渲染層。這是它最實際的價值。2.2 拿到 Key 和接入地址進入控制臺創(chuàng)建 API Key地址是 https://taotoken.net/api-keys 登錄后新建一個 Key 并復制保存。注意 Key 只在創(chuàng)建時完整顯示一次丟了只能重建。接入用的 base_url 是https://taotoken.net/api注意這個地址不帶任何查詢參數直接作為 OpenAI SDK 或 fetch 的根路徑。模型 ID 按你實際要用的填比如gpt-4o、claude-3-5-sonnet這類具體以控制臺模型列表為準。如果你更習慣用現成的編碼工具TaoToken 也提供了 Coding Plan 形態(tài)地址 https://taotoken.net/coding-plan 適合長期做 Agent 和代碼生成的同學這里不展開重點還是瀏覽器端的流式渲染。2.3 三件套配置對照不管你是用原生 fetch 還是 SDK接入信息永遠是這三樣缺一不可配置項值說明Base URLhttps://taotoken.net/api所有請求的根路徑API Key控制臺創(chuàng)建放在 Authorization 頭Model ID如gpt-4o按控制臺列表填把這三樣記牢后面所有代碼都圍繞它們展開。如果你用的是 Cline、CC Switch 這類工具配置項名稱可能叫 Base URL / API Key / Model本質一樣。3. 可復制的 fetch 流式讀取配置與逐幀渲染片段3.1 用 fetch 接 ReadableStream瀏覽器端推薦直接用 fetch因為response.body就是一個 ReadableStream比 EventSource 靈活能帶 POST body 和自定義頭。下面這段是可直接復制的流式讀取骨架async function streamChat({ messages, model gpt-4o, onDelta, onDone }) { const resp await fetch(https://taotoken.net/api/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, }, body: JSON.stringify({ model, messages, stream: true, }), }); if (!resp.ok || !resp.body) { throw new Error(stream failed: ${resp.status}); } const reader resp.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; while (true) { const { value, done } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop() || ; for (const line of lines) { const trimmed line.trim(); if (!trimmed.startsWith(data:)) continue; const payload trimmed.slice(5).trim(); if (payload [DONE]) { onDone onDone(); return; } try { const json JSON.parse(payload); const delta json.choices?.[0]?.delta?.content; if (delta) onDelta(delta); } catch (e) { // 半截 JSON 留給下一輪 buffer 處理 } } } }這里有兩個關鍵點。第一decoder.decode(value, { stream: true })的stream: true必須加否則一個多字節(jié)漢字被拆到兩個 chunk 時會解碼成亂碼。第二buffer要保留最后一段不完整的行因為網絡分塊不保證按行切l(wèi)ines.pop()把可能殘缺的尾部留到下一輪拼接。3.2 用 requestAnimationFrame 控制逐字節(jié)奏收到 delta 后不要立刻渲染。如果每個 chunk 都觸發(fā)一次狀態(tài)更新模型吐字快的時候一秒能來幾十次React 直接過載。正確做法是把 delta 推進一個隊列用 requestAnimationFrame 按幀消費class Typewriter { constructor(render, charsPerFrame 2) { this.queue ; this.render render; this.charsPerFrame charsPerFrame; this.rafId null; this.running false; } push(text) { this.queue text; if (!this.running) this.start(); } start() { this.running true; const tick () { if (this.queue.length 0) { this.running false; this.rafId null; return; } const take this.queue.slice(0, this.charsPerFrame); this.queue this.queue.slice(this.charsPerFrame); this.render(take); this.rafId requestAnimationFrame(tick); }; this.rafId requestAnimationFrame(tick); } stop() { if (this.rafId) cancelAnimationFrame(this.rafId); this.running false; } }charsPerFrame是節(jié)奏旋鈕。設成 1 就是標準打字機設成 3 到 5 適合長文快速鋪開。因為消費發(fā)生在 rAF 回調里渲染頻率天然被鎖在屏幕刷新率通常 60fps不會因為網絡快慢而抖動。模型吐得慢時隊列空rAF 自動停吐得快時隊列積壓每幀穩(wěn)定消費固定字數視覺上就是勻速打字。3.3 長文本滾動性能優(yōu)化字數上千后每幀往 DOM 追加文本會觸發(fā)整段重排。三個優(yōu)化手段按優(yōu)先級來第一渲染容器用white-space: pre-wrap加固定寬度避免每加一個字就重新計算換行導致整段回流。第二把已輸出內容拆成「穩(wěn)定段 活動段」穩(wěn)定段用content-visibility: auto讓瀏覽器跳過屏外渲染。第三滾動跟隨不要每幀scrollTop scrollHeight改成節(jié)流到每 100ms 一次或者只在用戶沒有手動上滑時才自動跟隨。let lastScroll 0; function followScroll(el) { const now performance.now(); if (now - lastScroll 100) return; lastScroll now; el.scrollTop el.scrollHeight; }這套組合下來實測萬字長文的渲染幀率能穩(wěn)在 55 以上滾動不再抖。4. 驗證請求首字延遲與幀率怎么測4.1 首字延遲測量首字延遲TTFB 到第一個字符渲染是打字機體驗的核心指標。在 fetch 發(fā)出前打一個時間戳在第一次onDelta觸發(fā)時再打一個差值就是首字延遲const t0 performance.now(); let firstCharAt null; await streamChat({ messages: [{ role: user, content: 寫一段 200 字的介紹 }], onDelta: (d) { if (firstCharAt null) { firstCharAt performance.now(); console.log(首字延遲:, (firstCharAt - t0).toFixed(0), ms); } typewriter.push(d); }, });正常網絡下走統一通道的首字延遲通常在 300 到 800ms 之間取決于模型和負載。如果超過 2 秒先排查是不是沒開 stream或者代理層把響應緩沖了。4.2 幀率測量用 requestAnimationFrame 的間隔反推幀率在打字過程中采樣let frames 0; let start performance.now(); function fpsProbe() { frames; const now performance.now(); if (now - start 1000) { console.log(FPS:, frames); frames 0; start now; } requestAnimationFrame(fpsProbe); } fpsProbe();打字過程中如果 FPS 掉到 30 以下基本可以確定是渲染層的問題回到第 3 節(jié)的 rAF 隊列和滾動優(yōu)化去查。4.3 成功結果長什么樣一次正常的流式請求你在 Network 面板里應該看到響應類型是text/event-streamTransfer-Encoding 是 chunked內容一行行data: {...}往外冒。頁面上文字勻速出現滾動平滑跟隨控制臺打印的首字延遲和 FPS 都在合理區(qū)間。如果 Network 里響應是一次性返回的說明 stream 參數沒生效或者被中間層緩沖了。5. 本篇常見錯誤排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常見。原因通常是 Key 沒帶、帶錯或者復制時多了空格。檢查Authorization: Bearer xxx里的 Key 是否和控制臺一致。注意 base_url 是https://taotoken.net/api請求路徑拼成/v1/chat/completions別把/api漏了或者重復拼。5.2 local proxy failed這個報錯一般出現在你本地起了代理工具或者某些 IDE 插件自帶代理層時。含義是本地代理轉發(fā)失敗請求根本沒到服務端。排查順序先確認系統代理是否指向了一個沒啟動的端口再確認代碼里有沒有硬編碼http://localhost:xxxx的代理地址。把代理關掉直連或者把 base_url 換成https://taotoken.net/api直連通常就好了。5.3 reading choices 或 Cannot read properties of undefined這是解析層報錯說明你拿到的 JSON 里沒有choices字段。兩種可能一是請求體里stream沒設成 true返回的是普通 JSON 結構不同二是某個 chunk 是錯誤響應比如{error: {...}}你的代碼直接去讀choices[0]就炸了。修復方式是解析后先判斷const json JSON.parse(payload); if (json.error) { console.error(API error:, json.error); return; } const delta json.choices?.[0]?.delta?.content;用可選鏈兜底永遠不要假設choices一定存在。5.4 OAuth 相關報錯如果你用的是 Claude Code 這類工具可能會遇到 OAuth token 過期或未授權的提示。這類工具走的是 OAuth 流程而非簡單 API Key。解決方式是重新執(zhí)行登錄授權或者在工具配置里改用 API Key 模式。以 Claude Code 為例配置三件套時把 Base URL 指向https://taotoken.net/apiKey 用控制臺創(chuàng)建的Model 填對應模型 ID就能繞開 OAuth 直接走 Key 鑒權。CC Switch 這類切換工具同理核心還是 Base URL Key Model ID 三樣對齊。5.5 中文亂碼如果輸出里出現「錕斤拷」或者方塊八成是 TextDecoder 沒加{ stream: true }。多字節(jié)字符被 chunk 邊界切開時不加這個參數就會按單字節(jié)解碼直接損壞?；氐?3.1 的代碼確認這一行。6. 把流式渲染接進你的項目從驗證到長期使用到這里接收、渲染、優(yōu)化、排障四條線都通了。你可以先把第 3 節(jié)的 fetch 骨架和第 3.2 節(jié)的 Typewriter 類拷進項目用第 4 節(jié)的測量方法跑一遍確認首字延遲和幀率達標再逐步替換掉項目里原來的整段渲染邏輯。如果你只是偶爾驗證模型輸出效果直接用模型對話頁面試最省事地址 https://taotoken.net/model-chat 輸入問題就能看到流式返回不用寫代碼。如果你要長期做編碼類 Agent、需要穩(wěn)定的流式通道和額度管理走 Coding Plan 更合適地址 https://taotoken.net/coding-plan 。接入文檔在 https://taotoken.net/doc 里面有各語言 SDK 的流式示例遇到格式問題可以對照。最后留一個我踩過的坑別在onDelta里直接setState(prev prev delta)。哪怕你加了 rAF只要狀態(tài)更新函數本身在閉包里捕獲了舊值快速連續(xù)調用時 React 的批處理也可能丟字。正確姿勢是讓 Typewriter 持有完整文本render 回調只負責把「本幀新增的部分」交給一個 ref 或 reducer 去追加保證順序和完整性。這個細節(jié)不注意打字機偶爾會「吞字」而且極難復現。