求實(shí)戰(zhàn)：AbortSignal復(fù)用引發(fā)的failed to fetch排查)
1. 先交代背景我是怎么踩進(jìn)這個(gè)坑的最近在做一個(gè) AI 對(duì)話前端改造需要把大模型回答從“等半天一次性吐出來(lái)”改成“邊生成邊渲染”的流式效果。需求本身不復(fù)雜但落地時(shí)卻讓我在fetchEventSource和原生fetch之間反復(fù)橫跳折騰了整整兩天。最崩潰的一條報(bào)錯(cuò)長(zhǎng)這樣failed to fetch dynamically im 無(wú)法加載 agent 預(yù)設(shè) client api: agentpresets/list failed: failed to fetch明明上一秒接口還能通換掉請(qǐng)求方式之后水靈靈地就開(kāi)始failed to fetch而且只有流式相關(guān)接口跪了普通 JSON 接口一切正常。后來(lái)我把整套鏈路從瀏覽器到服務(wù)端到 SSL 全查了一遍最后才發(fā)現(xiàn)問(wèn)題不是網(wǎng)絡(luò)不是網(wǎng)關(guān)而是我跟fetchEventSource之間有層“沒(méi)有說(shuō)透的窗戶紙”。這篇文章不打算寫那種“fetchEventSource 比 fetch 好”的結(jié)論帖而是想把我這次真實(shí)的排查過(guò)程拆開(kāi)講清楚兩個(gè)東西在流式場(chǎng)景下的本質(zhì)區(qū)別。如果你也在做 SSE 流式輸出、大模型實(shí)時(shí)渲染或者遇到failed to fetch、agentpresets/list failed、abort被莫名觸發(fā)這類報(bào)錯(cuò)這篇文章里的排查思路和結(jié)論應(yīng)該能幫你少走不少?gòu)澛?。先說(shuō)結(jié)論要點(diǎn)原生fetch支持讀流但它只是“給了你水管”fetchEventSource則是一套完整的水泵系統(tǒng)。兩者在流式場(chǎng)景下的區(qū)別主要集中在四個(gè)地方——事件解析、斷線重連、請(qǐng)求頭約束、以及中止信號(hào)的語(yǔ)義。搞懂這四點(diǎn)幾乎所有流式報(bào)錯(cuò)都能定位。2. 重新認(rèn)識(shí)兩個(gè)讀取方式fetchEventSource 與 fetch 的本質(zhì)差別2.1 原生 fetch 的流式是“給了水管但沒(méi)給你水泵”原生fetch從很早開(kāi)始就支持讀取流式響應(yīng)了核心就三個(gè) APIconst response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt: 你好 }), }); const reader response.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { value, done } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); // 自己解析 buffer 里的數(shù)據(jù) // SSE 格式通常是data: {content:xxx}\n\n const events buffer.split(\n\n); buffer events.pop(); for (const event of events) { const dataLine event.startsWith(data:) ? event.slice(5).trim() : ; if (dataLine dataLine ! [DONE]) { const json JSON.parse(dataLine); renderContent(json.content); } } }你看原生fetch其實(shí)完全能干這事。它把response.body變成了一個(gè)ReadableStream你每次reader.read()拿到一塊 Uint8Array然后自己解碼、自己切分、自己解析事件。也就是說(shuō)原生 fetch 的能力邊界是“給你一根水管水流過(guò)來(lái)你自己接”。這里能滿足基本的流式需求而且足夠輕量。但問(wèn)題在于它太“原生”了很多坑留給了使用者。比如SSE 協(xié)議規(guī)定事件之間用空行分隔但網(wǎng)絡(luò)分包可能把一個(gè)事件切成兩半你得自己維護(hù) buffer如果服務(wù)端發(fā)了注釋行以:開(kāi)頭的行用于心跳?；钅愕米约禾^(guò)斷線了不會(huì)自動(dòng)重連得自己寫重試邏輯請(qǐng)求頭雖然隨便你加但服務(wù)端 CORS 是否會(huì)暴露、預(yù)檢請(qǐng)求能否通過(guò)依然要自己處理。這些“自己來(lái)”的部分看著都不難但疊加在一起就是典型的多處邏輯交織、邊界問(wèn)題頻發(fā)的狀態(tài)。我第一次用原生 fetch 寫流式60 行代碼里有 30 行都在處理字符串切分和異常兜底。2.2 fetchEventSource可以理解為“配備了泵、閥門和儀表盤的成套方案”fetchEventSource是微軟出的一個(gè)庫(kù)本質(zhì)是在fetch之上做了一層封裝專門針對(duì) SSE 流式場(chǎng)景。它解決的核心痛點(diǎn)是EventSource天然只支持 GET不能用 POST 傳業(yè)務(wù)參數(shù)也不能自定義請(qǐng)求頭比如帶上 Authorization 令牌而 AI 對(duì)話類接口幾乎都是 POST JSON 鑒權(quán)頭。fetchEventSource用fetch重新實(shí)現(xiàn)了 SSE 的完整行為保留了 EventSource 的事件語(yǔ)義同時(shí)突破了它的請(qǐng)求約束。它的基本用法很短import { fetchEventSource } from microsoft/fetch-event-source; const ctrl new AbortController(); await fetchEventSource(/api/chat, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${token}, }, body: JSON.stringify({ prompt: 你好 }), signal: ctrl.signal, openWhenHidden: true, // 頁(yè)面隱藏時(shí)保持連接 async onopen(response) { if (response.ok) { console.log(連接建立狀態(tài)碼, response.status); } else { throw new Error(HTTP ${response.status}); } }, onmessage(event) { const data JSON.parse(event.data); renderContent(data.content); }, onclose() { console.log(流正常關(guān)閉); }, onerror(error) { console.error(流異常嘗試重連, error); // 返回非 void 時(shí)庫(kù)會(huì)自動(dòng)重連 // 如果不想重連可以 throw error }, });這套 API 看起來(lái)清爽多了。onmessage幫你把 SSE 的data:行解析好event.data直接就是內(nèi)容onerror里返回一個(gè)值庫(kù)會(huì)幫你做自動(dòng)重連連接建立、打開(kāi)、失敗、關(guān)閉全都有回調(diào)鉤子。還有openWhenHidden這個(gè)參數(shù)處理了頁(yè)面切換 Tab 時(shí)瀏覽器對(duì)連接的限制原生 EventSource 在這個(gè)場(chǎng)景下有個(gè)痛點(diǎn)是隱藏頁(yè)面會(huì)掛起這庫(kù)能繞開(kāi)。用一句生活化的話說(shuō)原生 fetch 給你一根水管讓你自己裝水泵、裝水表、裝閥門fetchEventSource直接交付一套集成好的供水系統(tǒng)你只需要打開(kāi)龍頭。2.3 為什么說(shuō)“自定義 header”是分水嶺很多人在選型時(shí)糾結(jié)“為什么不用 EventSource它不也是 SSE 嗎”——這就是沒(méi)踩過(guò)真實(shí)需求場(chǎng)景才會(huì)有的疑問(wèn)。原生EventSource的問(wèn)題非常致命它不能帶自定義請(qǐng)求頭。你拿它調(diào)一個(gè)需要Authorization的私有化模型接口直接就是 401 甚至跨域預(yù)檢失敗?，F(xiàn)在不少 LLM 網(wǎng)關(guān)還要求請(qǐng)求里帶api-key、trace-id這玩意兒根本塞不進(jìn)去。所以這時(shí)候有兩類選擇用原生fetch自己解析流請(qǐng)求頭管夠代價(jià)是解析邏輯、斷線重連、心跳保護(hù)全手寫用fetchEventSource它內(nèi)部用 fetch 實(shí)現(xiàn)自定義 header、POST body 都支持同時(shí)把 SSE 協(xié)議的上層語(yǔ)義補(bǔ)齊。我在這次改造里選的是fetchEventSource理由很簡(jiǎn)單——我們的服務(wù)端網(wǎng)關(guān)要求每個(gè)流請(qǐng)求都帶內(nèi)部api-key和request-id原生 EventSource 直接出局而項(xiàng)目里又要求快速交付手寫解析器的維護(hù)成本不低用一個(gè)成熟封裝更穩(wěn)妥。但正是這次選型讓一個(gè)問(wèn)題暴露出來(lái)fetchEventSource太好用了以至于讓我忽略了它內(nèi)部對(duì)“錯(cuò)誤響應(yīng)”和“連接中止”有一套自己的處理邏輯而這套邏輯在某些場(chǎng)景下和原生fetch的語(yǔ)義完全不一致。3. 真實(shí)踩坑過(guò)程一次 agent 預(yù)設(shè)加載失敗引發(fā)的排查3.1 現(xiàn)象復(fù)盤先還原一下我當(dāng)時(shí)的場(chǎng)景。項(xiàng)目里有一個(gè)“智能體預(yù)設(shè)列表”的接口/api/agentpresets/list用來(lái)給對(duì)話頁(yè)加載可選的 AI 角色。這不是個(gè)大模型流式接口而是普通參數(shù)列表接口。但當(dāng)時(shí)前端統(tǒng)一把這類接口從fetch切換成了fetchEventSource——因?yàn)槲姨煺娴匾詾椤凹热欢际亲?HTTP統(tǒng)一封裝組件最省事”。切換之后一連串接口開(kāi)始報(bào)錯(cuò)failed to fetch 無(wú)法加載 agent 預(yù)設(shè) client api: agentpresets/list failed: failed to fetch注意最后一次報(bào)錯(cuò)這是瀏覽器終端的原始信息翻譯過(guò)來(lái)就是fetch在請(qǐng)求還沒(méi)有拿到任何響應(yīng)頭之前連接就被中止了。因?yàn)閒etchEventSource的onopen回調(diào)只有在收到響應(yīng)頭之后才會(huì)觸發(fā)而這次請(qǐng)求連這一步都沒(méi)走到。我第一反應(yīng)是服務(wù)端掛了。于是用 Postman 直接打同一個(gè)接口200秒回?cái)?shù)據(jù)完整。再用 curl 打200一切正常。那么問(wèn)題就出在前端請(qǐng)求本身。3.2 排查鏈路我按下面這個(gè)順序排除寫下來(lái)給同樣踩坑的人參考第一層看請(qǐng)求是否真正發(fā)出。打開(kāi) DevTools 的 Network 面板在agentpresets/list請(qǐng)求上右鍵復(fù)制為 curl命令行跑一遍。如果 curl 能通說(shuō)明服務(wù)端、網(wǎng)關(guān)、SSL 都沒(méi)問(wèn)題。剩下的問(wèn)題集中在瀏覽器環(huán)境和請(qǐng)求庫(kù)。第二層查 CORS 和預(yù)檢。我們的接口帶Authorization和api-key自定義頭瀏覽器會(huì)先發(fā)一個(gè)OPTIONS預(yù)檢請(qǐng)求?？?Network 面板里是否有預(yù)檢請(qǐng)求預(yù)檢是否返回了正確的Access-Control-Allow-Headers這一步很關(guān)鍵因?yàn)閒etchEventSource內(nèi)部即使設(shè)置了 headers如果服務(wù)端沒(méi)放行這些自定義頭請(qǐng)求在預(yù)檢階段就被瀏覽器攔截了表現(xiàn)就是failed to fetch。這個(gè)坑非常經(jīng)典尤其是從 Postman 測(cè)不出問(wèn)題的情況下十有八九卡在這。第三層查代理層和網(wǎng)關(guān)是否對(duì)流式請(qǐng)求做了特殊處理。我們服務(wù)端有個(gè) Nginx 網(wǎng)關(guān)檢查proxy_read_timeout、proxy_buffering這類配置。如果proxy_buffering開(kāi)著SSE 流的響應(yīng)會(huì)被 Nginx 攢著不吐客戶端遲遲收不到第一個(gè)字節(jié)容易觸發(fā)表層超時(shí)。雖然這里報(bào)的是“預(yù)設(shè)列表”接口但網(wǎng)關(guān)是統(tǒng)一入口配置影響所有接口。第四層查 AbortController 與頁(yè)面生命周期。我們的對(duì)話頁(yè)在組件卸載時(shí)會(huì)調(diào)用ctrl.abort()取消未完成的流式請(qǐng)求。如果請(qǐng)求時(shí)序上組件先卸載、請(qǐng)求后返回那么 abort 信號(hào)會(huì)導(dǎo)致 fetch 以AbortError結(jié)束最終同樣表現(xiàn)為failed to fetch。這個(gè)在所有異步請(qǐng)求中都可能發(fā)生屬于經(jīng)典競(jìng)態(tài)。四層查完前三層都沒(méi)問(wèn)題第四層嫌疑最大。于是我打開(kāi) Network 面板盯著預(yù)設(shè)列表請(qǐng)求的 timing發(fā)現(xiàn) Grunt 一個(gè)巧合這個(gè)接口發(fā)出的時(shí)機(jī)和上一個(gè)流式請(qǐng)求 abort 的時(shí)機(jī)幾乎重疊。3.3 根因定位到這里真相就比較清晰了。我們的對(duì)話頁(yè)切換 agent 預(yù)設(shè)時(shí)會(huì)先abort()上一個(gè)流式請(qǐng)求再發(fā)起新的預(yù)設(shè)列表請(qǐng)求。而fetchEventSource有個(gè)重要特性它內(nèi)部維護(hù)的是同一個(gè)AbortSignal信號(hào)鏈。如果你在fetchEventSource的選項(xiàng)里傳入某個(gè)signal它內(nèi)部的所有重連嘗試都會(huì)復(fù)用這個(gè)信號(hào)。問(wèn)題出在我沒(méi)有為每次請(qǐng)求創(chuàng)建獨(dú)立的AbortController而是模板里復(fù)用了同一個(gè)。第一次請(qǐng)求 abort 后這個(gè) controller 的 signal 狀態(tài)變成了aborted接下來(lái)所有復(fù)用這個(gè) signal 的請(qǐng)求fetch 都會(huì)立即拒絕根本不會(huì)發(fā)出網(wǎng)絡(luò)請(qǐng)求。換句話說(shuō)fetchEventSource的signal一旦 abort 就永久失效它是“一次性信號(hào)”。而原生fetch遇到同樣的情況也一樣是被 abort 拉住——這不算 fetchEventSource 獨(dú)有的問(wèn)題但因?yàn)閒etchEventSource內(nèi)部消息循環(huán)和重連機(jī)制的存在這種“被 abort 拒絕”的請(qǐng)求其錯(cuò)誤信息里沒(méi)有明確的AbortError標(biāo)記而是被轉(zhuǎn)換成了TypeError: Failed to fetch所以排查時(shí)很容易誤判成網(wǎng)絡(luò)問(wèn)題。再進(jìn)一步看為什么這個(gè)報(bào)錯(cuò)會(huì)串到agentpresets/list這樣完全無(wú)關(guān)的接口上就是因?yàn)槲野淹粋€(gè)AbortController傳給了所有接口請(qǐng)求。表面上代碼是這個(gè)樣子的// 錯(cuò)誤示范所有請(qǐng)求復(fù)用一個(gè) controller const sharedController new AbortController(); async function loadPresets() { await fetchEventSource(/api/agentpresets/list, { signal: sharedController.signal, onmessage(msg) { /* 處理 */ }, }); } async function chatStream() { await fetchEventSource(/api/chat, { signal: sharedController.signal, onmessage(msg) { /* 處理 */ }, }); }一旦某個(gè)環(huán)節(jié)調(diào)用了sharedController.abort()后面再發(fā)的任何復(fù)用請(qǐng)求都不再有意義。這不是fetchEventSource的問(wèn)題而是我對(duì)“AbortSignal 是一次性狀態(tài)”這個(gè)底層語(yǔ)義理解不到位——所以我在標(biāo)題里強(qiáng)調(diào)這是一次“本質(zhì)區(qū)別”本質(zhì)不是 API 長(zhǎng)什么樣而是狀態(tài)語(yǔ)義。修復(fù)辦法非常簡(jiǎn)單每次請(qǐng)求都 new 一個(gè)獨(dú)立的AbortControllerasync function loadPresets() { const ctrl new AbortController(); await fetchEventSource(/api/agentpresets/list, { signal: ctrl.signal, onmessage(msg) { /* 處理 */ }, }); } async function chatStream() { const ctrl new AbortController(); await fetchEventSource(/api/chat, { signal: ctrl.signal, onmessage(msg) { /* 處理 */ }, }); }如果你真的需要在某個(gè)頁(yè)面級(jí)別統(tǒng)一取消所有請(qǐng)求也建議維護(hù)一個(gè) controller 集合而不是共用一個(gè)AbortController。每次請(qǐng)求創(chuàng)建獨(dú)立 controller頁(yè)面卸載時(shí)統(tǒng)一調(diào)用集合里的abort()。注意AbortSignal一旦進(jìn)入 aborted 狀態(tài)是無(wú)法恢復(fù)的。你沒(méi)法把同一個(gè) signal 取消后再?gòu)?fù)用。這是 web 平臺(tái)的固定語(yǔ)義跟庫(kù)無(wú)關(guān)。4. 避坑經(jīng)驗(yàn)與報(bào)錯(cuò)速查表4.1 選型建議什么時(shí)候用 fetchEventSource什么時(shí)候用原生 fetch這次踩坑之后我把“流式讀取”的選型標(biāo)準(zhǔn)重新梳理了一遍。沒(méi)有哪個(gè)方式是絕對(duì)正確的只有更適合你當(dāng)前場(chǎng)景的。場(chǎng)景推薦方式原因大模型對(duì)話需要 POST 自定義 header SSEfetchEventSource自動(dòng)解析事件、自動(dòng)重連、支持 POST 和 header后端就是標(biāo)準(zhǔn) GET SSE比如某些開(kāi)源消息推送原生EventSource瀏覽器原生能力不需要引庫(kù)天然支持自動(dòng)重連只需要非常輕量的單次響應(yīng)讀取不關(guān)心重連原生fetchReadableStream依賴少代碼可控涉及復(fù)雜的多遍流處理、事件類型多樣、需要精細(xì)控制每類事件fetchEventSource它的onopen/onmessage/onerror/onclose鉤子比原生fetch的裸流處理清晰得多項(xiàng)目對(duì)依賴包體積極其敏感原生fetch少一個(gè)運(yùn)行時(shí)依賴打包體積自然減小我個(gè)人的經(jīng)驗(yàn)是如果你在做 AI 對(duì)話類功能第一選擇就是fetchEventSource。它讓你把精力花在業(yè)務(wù)邏輯上不用每次糾結(jié)字符串切拆和心跳處理。但代價(jià)是——它是個(gè)封裝層你踩的坑往往不是它本身不夠好而是你沒(méi)搞懂它背后依賴的底層語(yǔ)義比如 AbortSignal 的一次性特性、自動(dòng)重連可能帶來(lái)的重復(fù)數(shù)據(jù)問(wèn)題。4.2 常見(jiàn)報(bào)錯(cuò)速查表把這次項(xiàng)目里遇到的和網(wǎng)上高頻出現(xiàn)的問(wèn)題整理成了一張速查表按failed to fetch相關(guān)錯(cuò)誤類型和排查路徑給出來(lái)報(bào)錯(cuò)關(guān)鍵詞可能原因排查順序failed to fetch跨域預(yù)檢失敗、服務(wù)端未響應(yīng)、連接被 abort、網(wǎng)關(guān) buffer1. Network 復(fù)制 curl 驗(yàn)證服務(wù)端 2. 檢查 OPTIONS 預(yù)檢 3. 檢查 body 是否被 abortfailed to fetch dynamically只用于動(dòng)態(tài)導(dǎo)入和運(yùn)行時(shí) fetch 無(wú)直接關(guān)系但報(bào)錯(cuò)前常伴隨網(wǎng)絡(luò)不可達(dá)或單頁(yè)應(yīng)用資源加載失敗檢查靜態(tài)資源 CDN 可達(dá)性、路由目錄是否正確agentpresets/list failed: failed to fetch請(qǐng)求被 AbortSignal 攔截、或者自定義 header 未通過(guò) CORS重點(diǎn)查 AbortController 是否被復(fù)用、預(yù)檢響應(yīng)頭connect econnrefused服務(wù)端端口未監(jiān)聽(tīng)、防火墻攔截、服務(wù)未啟動(dòng)curl -v看握手過(guò)程檢查服務(wù)日志failed to fetch version from claude.ai這是某些工具在檢測(cè)網(wǎng)絡(luò)或版本源時(shí)的通用錯(cuò)誤多數(shù)和代理/證書/網(wǎng)絡(luò)隔離相關(guān)換網(wǎng)絡(luò)源看是否能通檢查系統(tǒng)代理設(shè)置git fetch或git pull很慢緩沖區(qū)容量、協(xié)議差異、DNS 解析慢git config --global http.postBuffer調(diào)大檢查https.sslVerifyVS Code 服務(wù)器failed to fetch遠(yuǎn)程環(huán)境下載 server 包失敗手動(dòng)下載vscode-server-linux-x64.tar.gz放到指定目錄這里必須強(qiáng)調(diào)failed to fetch是前端最常見(jiàn)但又最沒(méi)有信息量的錯(cuò)誤。小技巧是在onerror回調(diào)里加一層錯(cuò)誤轉(zhuǎn)換把error.name和error.message都打出來(lái)。如果error.name AbortError說(shuō)明是主動(dòng)中止如果error.message含NetworkError說(shuō)明是連接層面的問(wèn)題如果是TypeError: Failed to fetch但實(shí)際請(qǐng)求沒(méi)有發(fā)出大概率是 CORS 或 signal 問(wèn)題。這一手能在你上 DevTools 之前先快速縮小范圍。另外一個(gè)小技巧如果你需要排查“請(qǐng)求到底有沒(méi)有發(fā)到服務(wù)器”可以在組件里臨時(shí)給fetchEventSource加一個(gè)onopen回調(diào)onopen(response) { console.log(HTTP 狀態(tài), response.status, 說(shuō)明服務(wù)端已收到請(qǐng)求); }只要onopen執(zhí)行了說(shuō)明服務(wù)端已返回響應(yīng)頭問(wèn)題不在“服務(wù)端沒(méi)收到請(qǐng)求”。如果onopen一直不執(zhí)行那就是請(qǐng)求沒(méi)到服務(wù)端優(yōu)先查 CORS、DNS、證書、signal。這個(gè)“響應(yīng)頭是否返回”的判斷思路能把你從“服務(wù)端到底通沒(méi)通”的泥潭里拉出來(lái)。4.3 一個(gè)額外的坑重連造成的重復(fù)數(shù)據(jù)除了 AbortSignal 的坑fetchEventSource自動(dòng)重連機(jī)制還會(huì)帶來(lái)另一個(gè)問(wèn)題斷線重連后消息可能重復(fù)。比如你調(diào)大模型接口流式返回了一部分內(nèi)容后網(wǎng)絡(luò)閃斷fetchEventSource會(huì)自動(dòng)重連并重新發(fā)送請(qǐng)求。如果服務(wù)端沒(méi)有做“斷點(diǎn)續(xù)傳”或者“請(qǐng)求去重”那前端就會(huì)再次收到從第一條開(kāi)始的內(nèi)容界面上就出現(xiàn)了重復(fù)的渲染。我當(dāng)時(shí)調(diào)的是一個(gè)內(nèi)部 LLM 網(wǎng)關(guān)網(wǎng)關(guān)并不緩存歷史輸出重連后從零開(kāi)始生成前端渲染里就出現(xiàn)了兩遍回答拼接的詭異效果。這類問(wèn)題的處理思路有兩個(gè)方向前端做消息冪等靠event.id或遞增序號(hào)重復(fù)內(nèi)容直接丟棄重連后讓用戶手動(dòng)確認(rèn)“是否繼續(xù)上次回答”而不是無(wú)感重放。對(duì)于 AI 對(duì)話這種場(chǎng)景自動(dòng)重連不總是好事。服務(wù)端生成狀態(tài)已經(jīng)在第一輪請(qǐng)求里消耗過(guò)一遍了重連不是在“繼續(xù)生成”而是在“重新生成”此時(shí)自動(dòng)重連反而制造混亂。所以我后來(lái)把onerror改成了手動(dòng)控制onerror(err) { // 打印原始錯(cuò)誤 console.error(流產(chǎn)生錯(cuò)誤, err.name, err.message); // 如果是 AbortError說(shuō)明是用戶/組件主動(dòng)中止不重連 if (err.name AbortError) { throw err; } // 其他錯(cuò)誤默認(rèn)自動(dòng)重連這里不返回具體值即可 // 如果你希望手動(dòng)控制直接 throw 出去 throw err; }實(shí)際項(xiàng)目里我會(huì)區(qū)分錯(cuò)誤類型來(lái)決策是否重連。主動(dòng) abort 的重試毫無(wú)意義網(wǎng)絡(luò)抖動(dòng)且服務(wù)端支持冪等時(shí)自動(dòng)重連才值得開(kāi)。這樣的決策能力是裸fetch和fetchEventSource都很難替你做主的都需要你對(duì)業(yè)務(wù)流有清晰判斷。5. 寫在最后的個(gè)人體會(huì)這次踩坑讓我最深的感受是凡是封裝良好的庫(kù)都會(huì)在“易用性”和“可控性”之間做選擇。fetchEventSource把 SSE 流式處理中繁瑣的部分——事件解析、重連、打開(kāi)關(guān)閉回調(diào)——全封裝了這是它的價(jià)值但這也意味著你對(duì)底層fetch行為、AbortSignal 語(yǔ)義、甚至是 HTTP 連接生命周期的理解成了你能不能用好它的關(guān)鍵。踩過(guò)幾次坑之后我現(xiàn)在寫流式請(qǐng)求代碼時(shí)一定會(huì)遵循幾個(gè)鐵律每個(gè)AbortController只服務(wù)一個(gè)請(qǐng)求絕不復(fù)用onerror里至少要打一行錯(cuò)誤日志包含error.name和error.messageonopen回調(diào)里記錄 HTTP 狀態(tài)碼方便日后判斷問(wèn)題在“服務(wù)端”還是“連接”服務(wù)端要支持冪等時(shí)再開(kāi)自動(dòng)重連否則必須在業(yè)務(wù)層做去重依賴包升級(jí)后重新過(guò)一遍openWhenHidden、signal、onerror的默認(rèn)行為是否變化。如果讓我對(duì)正在做 AI 應(yīng)用、或者準(zhǔn)備做流式渲染的朋友說(shuō)一句掏心窩的話別急著把所有接口都換到fetchEventSource它不是萬(wàn)能的也別因?yàn)橐淮蝔ailed to fetch就退回原生 fetch那個(gè)坑更大。先想清楚你的業(yè)務(wù)究竟需要什么控制粒度再?zèng)Q定用哪把工具。最后再分享一個(gè)我在排查任何failed to fetch時(shí)的定式先看error.name再看onopen是否執(zhí)行然后復(fù)制 curl 驗(yàn)證服務(wù)端最后檢查 CORS 預(yù)檢和 AbortSignal 狀態(tài)。按這個(gè)順序走目前我還沒(méi)遇到定位不出來(lái)的failed to fetch。希望這篇踩坑記錄能幫你少熬一個(gè)夜。 fetchEventSource與fetch流式請(qǐng)求實(shí)戰(zhàn)：AbortSignal復(fù)用引發(fā)的failed to fetch排查
1. 先交代背景我是怎么踩進(jìn)這個(gè)坑的最近在做一個(gè) AI 對(duì)話前端改造需要把大模型回答從“等半天一次性吐出來(lái)”改成“邊生成邊渲染”的流式效果。需求本身不復(fù)雜但落地時(shí)卻讓我在fetchEventSource和原生fetch之間反復(fù)橫跳折騰了整整兩天。最崩潰的一條報(bào)錯(cuò)長(zhǎng)這樣failed to fetch dynamically im 無(wú)法加載 agent 預(yù)設(shè) client api: agentpresets/list failed: failed to fetch明明上一秒接口還能通換掉請(qǐng)求方式之后水靈靈地就開(kāi)始failed to fetch而且只有流式相關(guān)接口跪了普通 JSON 接口一切正常。后來(lái)我把整套鏈路從瀏覽器到服務(wù)端到 SSL 全查了一遍最后才發(fā)現(xiàn)問(wèn)題不是網(wǎng)絡(luò)不是網(wǎng)關(guān)而是我跟fetchEventSource之間有層“沒(méi)有說(shuō)透的窗戶紙”。這篇文章不打算寫那種“fetchEventSource 比 fetch 好”的結(jié)論帖而是想把我這次真實(shí)的排查過(guò)程拆開(kāi)講清楚兩個(gè)東西在流式場(chǎng)景下的本質(zhì)區(qū)別。如果你也在做 SSE 流式輸出、大模型實(shí)時(shí)渲染或者遇到failed to fetch、agentpresets/list failed、abort被莫名觸發(fā)這類報(bào)錯(cuò)這篇文章里的排查思路和結(jié)論應(yīng)該能幫你少走不少?gòu)澛?。先說(shuō)結(jié)論要點(diǎn)原生fetch支持讀流但它只是“給了你水管”fetchEventSource則是一套完整的水泵系統(tǒng)。兩者在流式場(chǎng)景下的區(qū)別主要集中在四個(gè)地方——事件解析、斷線重連、請(qǐng)求頭約束、以及中止信號(hào)的語(yǔ)義。搞懂這四點(diǎn)幾乎所有流式報(bào)錯(cuò)都能定位。2. 重新認(rèn)識(shí)兩個(gè)讀取方式fetchEventSource 與 fetch 的本質(zhì)差別2.1 原生 fetch 的流式是“給了水管但沒(méi)給你水泵”原生fetch從很早開(kāi)始就支持讀取流式響應(yīng)了核心就三個(gè) APIconst response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt: 你好 }), }); const reader response.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { value, done } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); // 自己解析 buffer 里的數(shù)據(jù) // SSE 格式通常是data: {content:xxx}\n\n const events buffer.split(\n\n); buffer events.pop(); for (const event of events) { const dataLine event.startsWith(data:) ? event.slice(5).trim() : ; if (dataLine dataLine ! [DONE]) { const json JSON.parse(dataLine); renderContent(json.content); } } }你看原生fetch其實(shí)完全能干這事。它把response.body變成了一個(gè)ReadableStream你每次reader.read()拿到一塊 Uint8Array然后自己解碼、自己切分、自己解析事件。也就是說(shuō)原生 fetch 的能力邊界是“給你一根水管水流過(guò)來(lái)你自己接”。這里能滿足基本的流式需求而且足夠輕量。但問(wèn)題在于它太“原生”了很多坑留給了使用者。比如SSE 協(xié)議規(guī)定事件之間用空行分隔但網(wǎng)絡(luò)分包可能把一個(gè)事件切成兩半你得自己維護(hù) buffer如果服務(wù)端發(fā)了注釋行以:開(kāi)頭的行用于心跳?；钅愕米约禾^(guò)斷線了不會(huì)自動(dòng)重連得自己寫重試邏輯請(qǐng)求頭雖然隨便你加但服務(wù)端 CORS 是否會(huì)暴露、預(yù)檢請(qǐng)求能否通過(guò)依然要自己處理。這些“自己來(lái)”的部分看著都不難但疊加在一起就是典型的多處邏輯交織、邊界問(wèn)題頻發(fā)的狀態(tài)。我第一次用原生 fetch 寫流式60 行代碼里有 30 行都在處理字符串切分和異常兜底。2.2 fetchEventSource可以理解為“配備了泵、閥門和儀表盤的成套方案”fetchEventSource是微軟出的一個(gè)庫(kù)本質(zhì)是在fetch之上做了一層封裝專門針對(duì) SSE 流式場(chǎng)景。它解決的核心痛點(diǎn)是EventSource天然只支持 GET不能用 POST 傳業(yè)務(wù)參數(shù)也不能自定義請(qǐng)求頭比如帶上 Authorization 令牌而 AI 對(duì)話類接口幾乎都是 POST JSON 鑒權(quán)頭。fetchEventSource用fetch重新實(shí)現(xiàn)了 SSE 的完整行為保留了 EventSource 的事件語(yǔ)義同時(shí)突破了它的請(qǐng)求約束。它的基本用法很短import { fetchEventSource } from microsoft/fetch-event-source; const ctrl new AbortController(); await fetchEventSource(/api/chat, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${token}, }, body: JSON.stringify({ prompt: 你好 }), signal: ctrl.signal, openWhenHidden: true, // 頁(yè)面隱藏時(shí)保持連接 async onopen(response) { if (response.ok) { console.log(連接建立狀態(tài)碼, response.status); } else { throw new Error(HTTP ${response.status}); } }, onmessage(event) { const data JSON.parse(event.data); renderContent(data.content); }, onclose() { console.log(流正常關(guān)閉); }, onerror(error) { console.error(流異常嘗試重連, error); // 返回非 void 時(shí)庫(kù)會(huì)自動(dòng)重連 // 如果不想重連可以 throw error }, });這套 API 看起來(lái)清爽多了。onmessage幫你把 SSE 的data:行解析好event.data直接就是內(nèi)容onerror里返回一個(gè)值庫(kù)會(huì)幫你做自動(dòng)重連連接建立、打開(kāi)、失敗、關(guān)閉全都有回調(diào)鉤子。還有openWhenHidden這個(gè)參數(shù)處理了頁(yè)面切換 Tab 時(shí)瀏覽器對(duì)連接的限制原生 EventSource 在這個(gè)場(chǎng)景下有個(gè)痛點(diǎn)是隱藏頁(yè)面會(huì)掛起這庫(kù)能繞開(kāi)。用一句生活化的話說(shuō)原生 fetch 給你一根水管讓你自己裝水泵、裝水表、裝閥門fetchEventSource直接交付一套集成好的供水系統(tǒng)你只需要打開(kāi)龍頭。2.3 為什么說(shuō)“自定義 header”是分水嶺很多人在選型時(shí)糾結(jié)“為什么不用 EventSource它不也是 SSE 嗎”——這就是沒(méi)踩過(guò)真實(shí)需求場(chǎng)景才會(huì)有的疑問(wèn)。原生EventSource的問(wèn)題非常致命它不能帶自定義請(qǐng)求頭。你拿它調(diào)一個(gè)需要Authorization的私有化模型接口直接就是 401 甚至跨域預(yù)檢失敗?，F(xiàn)在不少 LLM 網(wǎng)關(guān)還要求請(qǐng)求里帶api-key、trace-id這玩意兒根本塞不進(jìn)去。所以這時(shí)候有兩類選擇用原生fetch自己解析流請(qǐng)求頭管夠代價(jià)是解析邏輯、斷線重連、心跳保護(hù)全手寫用fetchEventSource它內(nèi)部用 fetch 實(shí)現(xiàn)自定義 header、POST body 都支持同時(shí)把 SSE 協(xié)議的上層語(yǔ)義補(bǔ)齊。我在這次改造里選的是fetchEventSource理由很簡(jiǎn)單——我們的服務(wù)端網(wǎng)關(guān)要求每個(gè)流請(qǐng)求都帶內(nèi)部api-key和request-id原生 EventSource 直接出局而項(xiàng)目里又要求快速交付手寫解析器的維護(hù)成本不低用一個(gè)成熟封裝更穩(wěn)妥。但正是這次選型讓一個(gè)問(wèn)題暴露出來(lái)fetchEventSource太好用了以至于讓我忽略了它內(nèi)部對(duì)“錯(cuò)誤響應(yīng)”和“連接中止”有一套自己的處理邏輯而這套邏輯在某些場(chǎng)景下和原生fetch的語(yǔ)義完全不一致。3. 真實(shí)踩坑過(guò)程一次 agent 預(yù)設(shè)加載失敗引發(fā)的排查3.1 現(xiàn)象復(fù)盤先還原一下我當(dāng)時(shí)的場(chǎng)景。項(xiàng)目里有一個(gè)“智能體預(yù)設(shè)列表”的接口/api/agentpresets/list用來(lái)給對(duì)話頁(yè)加載可選的 AI 角色。這不是個(gè)大模型流式接口而是普通參數(shù)列表接口。但當(dāng)時(shí)前端統(tǒng)一把這類接口從fetch切換成了fetchEventSource——因?yàn)槲姨煺娴匾詾椤凹热欢际亲?HTTP統(tǒng)一封裝組件最省事”。切換之后一連串接口開(kāi)始報(bào)錯(cuò)failed to fetch 無(wú)法加載 agent 預(yù)設(shè) client api: agentpresets/list failed: failed to fetch注意最后一次報(bào)錯(cuò)這是瀏覽器終端的原始信息翻譯過(guò)來(lái)就是fetch在請(qǐng)求還沒(méi)有拿到任何響應(yīng)頭之前連接就被中止了。因?yàn)閒etchEventSource的onopen回調(diào)只有在收到響應(yīng)頭之后才會(huì)觸發(fā)而這次請(qǐng)求連這一步都沒(méi)走到。我第一反應(yīng)是服務(wù)端掛了。于是用 Postman 直接打同一個(gè)接口200秒回?cái)?shù)據(jù)完整。再用 curl 打200一切正常。那么問(wèn)題就出在前端請(qǐng)求本身。3.2 排查鏈路我按下面這個(gè)順序排除寫下來(lái)給同樣踩坑的人參考第一層看請(qǐng)求是否真正發(fā)出。打開(kāi) DevTools 的 Network 面板在agentpresets/list請(qǐng)求上右鍵復(fù)制為 curl命令行跑一遍。如果 curl 能通說(shuō)明服務(wù)端、網(wǎng)關(guān)、SSL 都沒(méi)問(wèn)題。剩下的問(wèn)題集中在瀏覽器環(huán)境和請(qǐng)求庫(kù)。第二層查 CORS 和預(yù)檢。我們的接口帶Authorization和api-key自定義頭瀏覽器會(huì)先發(fā)一個(gè)OPTIONS預(yù)檢請(qǐng)求?？?Network 面板里是否有預(yù)檢請(qǐng)求預(yù)檢是否返回了正確的Access-Control-Allow-Headers這一步很關(guān)鍵因?yàn)閒etchEventSource內(nèi)部即使設(shè)置了 headers如果服務(wù)端沒(méi)放行這些自定義頭請(qǐng)求在預(yù)檢階段就被瀏覽器攔截了表現(xiàn)就是failed to fetch。這個(gè)坑非常經(jīng)典尤其是從 Postman 測(cè)不出問(wèn)題的情況下十有八九卡在這。第三層查代理層和網(wǎng)關(guān)是否對(duì)流式請(qǐng)求做了特殊處理。我們服務(wù)端有個(gè) Nginx 網(wǎng)關(guān)檢查proxy_read_timeout、proxy_buffering這類配置。如果proxy_buffering開(kāi)著SSE 流的響應(yīng)會(huì)被 Nginx 攢著不吐客戶端遲遲收不到第一個(gè)字節(jié)容易觸發(fā)表層超時(shí)。雖然這里報(bào)的是“預(yù)設(shè)列表”接口但網(wǎng)關(guān)是統(tǒng)一入口配置影響所有接口。第四層查 AbortController 與頁(yè)面生命周期。我們的對(duì)話頁(yè)在組件卸載時(shí)會(huì)調(diào)用ctrl.abort()取消未完成的流式請(qǐng)求。如果請(qǐng)求時(shí)序上組件先卸載、請(qǐng)求后返回那么 abort 信號(hào)會(huì)導(dǎo)致 fetch 以AbortError結(jié)束最終同樣表現(xiàn)為failed to fetch。這個(gè)在所有異步請(qǐng)求中都可能發(fā)生屬于經(jīng)典競(jìng)態(tài)。四層查完前三層都沒(méi)問(wèn)題第四層嫌疑最大。于是我打開(kāi) Network 面板盯著預(yù)設(shè)列表請(qǐng)求的 timing發(fā)現(xiàn) Grunt 一個(gè)巧合這個(gè)接口發(fā)出的時(shí)機(jī)和上一個(gè)流式請(qǐng)求 abort 的時(shí)機(jī)幾乎重疊。3.3 根因定位到這里真相就比較清晰了。我們的對(duì)話頁(yè)切換 agent 預(yù)設(shè)時(shí)會(huì)先abort()上一個(gè)流式請(qǐng)求再發(fā)起新的預(yù)設(shè)列表請(qǐng)求。而fetchEventSource有個(gè)重要特性它內(nèi)部維護(hù)的是同一個(gè)AbortSignal信號(hào)鏈。如果你在fetchEventSource的選項(xiàng)里傳入某個(gè)signal它內(nèi)部的所有重連嘗試都會(huì)復(fù)用這個(gè)信號(hào)。問(wèn)題出在我沒(méi)有為每次請(qǐng)求創(chuàng)建獨(dú)立的AbortController而是模板里復(fù)用了同一個(gè)。第一次請(qǐng)求 abort 后這個(gè) controller 的 signal 狀態(tài)變成了aborted接下來(lái)所有復(fù)用這個(gè) signal 的請(qǐng)求fetch 都會(huì)立即拒絕根本不會(huì)發(fā)出網(wǎng)絡(luò)請(qǐng)求。換句話說(shuō)fetchEventSource的signal一旦 abort 就永久失效它是“一次性信號(hào)”。而原生fetch遇到同樣的情況也一樣是被 abort 拉住——這不算 fetchEventSource 獨(dú)有的問(wèn)題但因?yàn)閒etchEventSource內(nèi)部消息循環(huán)和重連機(jī)制的存在這種“被 abort 拒絕”的請(qǐng)求其錯(cuò)誤信息里沒(méi)有明確的AbortError標(biāo)記而是被轉(zhuǎn)換成了TypeError: Failed to fetch所以排查時(shí)很容易誤判成網(wǎng)絡(luò)問(wèn)題。再進(jìn)一步看為什么這個(gè)報(bào)錯(cuò)會(huì)串到agentpresets/list這樣完全無(wú)關(guān)的接口上就是因?yàn)槲野淹粋€(gè)AbortController傳給了所有接口請(qǐng)求。表面上代碼是這個(gè)樣子的// 錯(cuò)誤示范所有請(qǐng)求復(fù)用一個(gè) controller const sharedController new AbortController(); async function loadPresets() { await fetchEventSource(/api/agentpresets/list, { signal: sharedController.signal, onmessage(msg) { /* 處理 */ }, }); } async function chatStream() { await fetchEventSource(/api/chat, { signal: sharedController.signal, onmessage(msg) { /* 處理 */ }, }); }一旦某個(gè)環(huán)節(jié)調(diào)用了sharedController.abort()后面再發(fā)的任何復(fù)用請(qǐng)求都不再有意義。這不是fetchEventSource的問(wèn)題而是我對(duì)“AbortSignal 是一次性狀態(tài)”這個(gè)底層語(yǔ)義理解不到位——所以我在標(biāo)題里強(qiáng)調(diào)這是一次“本質(zhì)區(qū)別”本質(zhì)不是 API 長(zhǎng)什么樣而是狀態(tài)語(yǔ)義。修復(fù)辦法非常簡(jiǎn)單每次請(qǐng)求都 new 一個(gè)獨(dú)立的AbortControllerasync function loadPresets() { const ctrl new AbortController(); await fetchEventSource(/api/agentpresets/list, { signal: ctrl.signal, onmessage(msg) { /* 處理 */ }, }); } async function chatStream() { const ctrl new AbortController(); await fetchEventSource(/api/chat, { signal: ctrl.signal, onmessage(msg) { /* 處理 */ }, }); }如果你真的需要在某個(gè)頁(yè)面級(jí)別統(tǒng)一取消所有請(qǐng)求也建議維護(hù)一個(gè) controller 集合而不是共用一個(gè)AbortController。每次請(qǐng)求創(chuàng)建獨(dú)立 controller頁(yè)面卸載時(shí)統(tǒng)一調(diào)用集合里的abort()。注意AbortSignal一旦進(jìn)入 aborted 狀態(tài)是無(wú)法恢復(fù)的。你沒(méi)法把同一個(gè) signal 取消后再?gòu)?fù)用。這是 web 平臺(tái)的固定語(yǔ)義跟庫(kù)無(wú)關(guān)。4. 避坑經(jīng)驗(yàn)與報(bào)錯(cuò)速查表4.1 選型建議什么時(shí)候用 fetchEventSource什么時(shí)候用原生 fetch這次踩坑之后我把“流式讀取”的選型標(biāo)準(zhǔn)重新梳理了一遍。沒(méi)有哪個(gè)方式是絕對(duì)正確的只有更適合你當(dāng)前場(chǎng)景的。場(chǎng)景推薦方式原因大模型對(duì)話需要 POST 自定義 header SSEfetchEventSource自動(dòng)解析事件、自動(dòng)重連、支持 POST 和 header后端就是標(biāo)準(zhǔn) GET SSE比如某些開(kāi)源消息推送原生EventSource瀏覽器原生能力不需要引庫(kù)天然支持自動(dòng)重連只需要非常輕量的單次響應(yīng)讀取不關(guān)心重連原生fetchReadableStream依賴少代碼可控涉及復(fù)雜的多遍流處理、事件類型多樣、需要精細(xì)控制每類事件fetchEventSource它的onopen/onmessage/onerror/onclose鉤子比原生fetch的裸流處理清晰得多項(xiàng)目對(duì)依賴包體積極其敏感原生fetch少一個(gè)運(yùn)行時(shí)依賴打包體積自然減小我個(gè)人的經(jīng)驗(yàn)是如果你在做 AI 對(duì)話類功能第一選擇就是fetchEventSource。它讓你把精力花在業(yè)務(wù)邏輯上不用每次糾結(jié)字符串切拆和心跳處理。但代價(jià)是——它是個(gè)封裝層你踩的坑往往不是它本身不夠好而是你沒(méi)搞懂它背后依賴的底層語(yǔ)義比如 AbortSignal 的一次性特性、自動(dòng)重連可能帶來(lái)的重復(fù)數(shù)據(jù)問(wèn)題。4.2 常見(jiàn)報(bào)錯(cuò)速查表把這次項(xiàng)目里遇到的和網(wǎng)上高頻出現(xiàn)的問(wèn)題整理成了一張速查表按failed to fetch相關(guān)錯(cuò)誤類型和排查路徑給出來(lái)報(bào)錯(cuò)關(guān)鍵詞可能原因排查順序failed to fetch跨域預(yù)檢失敗、服務(wù)端未響應(yīng)、連接被 abort、網(wǎng)關(guān) buffer1. Network 復(fù)制 curl 驗(yàn)證服務(wù)端 2. 檢查 OPTIONS 預(yù)檢 3. 檢查 body 是否被 abortfailed to fetch dynamically只用于動(dòng)態(tài)導(dǎo)入和運(yùn)行時(shí) fetch 無(wú)直接關(guān)系但報(bào)錯(cuò)前常伴隨網(wǎng)絡(luò)不可達(dá)或單頁(yè)應(yīng)用資源加載失敗檢查靜態(tài)資源 CDN 可達(dá)性、路由目錄是否正確agentpresets/list failed: failed to fetch請(qǐng)求被 AbortSignal 攔截、或者自定義 header 未通過(guò) CORS重點(diǎn)查 AbortController 是否被復(fù)用、預(yù)檢響應(yīng)頭connect econnrefused服務(wù)端端口未監(jiān)聽(tīng)、防火墻攔截、服務(wù)未啟動(dòng)curl -v看握手過(guò)程檢查服務(wù)日志failed to fetch version from claude.ai這是某些工具在檢測(cè)網(wǎng)絡(luò)或版本源時(shí)的通用錯(cuò)誤多數(shù)和代理/證書/網(wǎng)絡(luò)隔離相關(guān)換網(wǎng)絡(luò)源看是否能通檢查系統(tǒng)代理設(shè)置git fetch或git pull很慢緩沖區(qū)容量、協(xié)議差異、DNS 解析慢git config --global http.postBuffer調(diào)大檢查https.sslVerifyVS Code 服務(wù)器failed to fetch遠(yuǎn)程環(huán)境下載 server 包失敗手動(dòng)下載vscode-server-linux-x64.tar.gz放到指定目錄這里必須強(qiáng)調(diào)failed to fetch是前端最常見(jiàn)但又最沒(méi)有信息量的錯(cuò)誤。小技巧是在onerror回調(diào)里加一層錯(cuò)誤轉(zhuǎn)換把error.name和error.message都打出來(lái)。如果error.name AbortError說(shuō)明是主動(dòng)中止如果error.message含NetworkError說(shuō)明是連接層面的問(wèn)題如果是TypeError: Failed to fetch但實(shí)際請(qǐng)求沒(méi)有發(fā)出大概率是 CORS 或 signal 問(wèn)題。這一手能在你上 DevTools 之前先快速縮小范圍。另外一個(gè)小技巧如果你需要排查“請(qǐng)求到底有沒(méi)有發(fā)到服務(wù)器”可以在組件里臨時(shí)給fetchEventSource加一個(gè)onopen回調(diào)onopen(response) { console.log(HTTP 狀態(tài), response.status, 說(shuō)明服務(wù)端已收到請(qǐng)求); }只要onopen執(zhí)行了說(shuō)明服務(wù)端已返回響應(yīng)頭問(wèn)題不在“服務(wù)端沒(méi)收到請(qǐng)求”。如果onopen一直不執(zhí)行那就是請(qǐng)求沒(méi)到服務(wù)端優(yōu)先查 CORS、DNS、證書、signal。這個(gè)“響應(yīng)頭是否返回”的判斷思路能把你從“服務(wù)端到底通沒(méi)通”的泥潭里拉出來(lái)。4.3 一個(gè)額外的坑重連造成的重復(fù)數(shù)據(jù)除了 AbortSignal 的坑fetchEventSource自動(dòng)重連機(jī)制還會(huì)帶來(lái)另一個(gè)問(wèn)題斷線重連后消息可能重復(fù)。比如你調(diào)大模型接口流式返回了一部分內(nèi)容后網(wǎng)絡(luò)閃斷fetchEventSource會(huì)自動(dòng)重連并重新發(fā)送請(qǐng)求。如果服務(wù)端沒(méi)有做“斷點(diǎn)續(xù)傳”或者“請(qǐng)求去重”那前端就會(huì)再次收到從第一條開(kāi)始的內(nèi)容界面上就出現(xiàn)了重復(fù)的渲染。我當(dāng)時(shí)調(diào)的是一個(gè)內(nèi)部 LLM 網(wǎng)關(guān)網(wǎng)關(guān)并不緩存歷史輸出重連后從零開(kāi)始生成前端渲染里就出現(xiàn)了兩遍回答拼接的詭異效果。這類問(wèn)題的處理思路有兩個(gè)方向前端做消息冪等靠event.id或遞增序號(hào)重復(fù)內(nèi)容直接丟棄重連后讓用戶手動(dòng)確認(rèn)“是否繼續(xù)上次回答”而不是無(wú)感重放。對(duì)于 AI 對(duì)話這種場(chǎng)景自動(dòng)重連不總是好事。服務(wù)端生成狀態(tài)已經(jīng)在第一輪請(qǐng)求里消耗過(guò)一遍了重連不是在“繼續(xù)生成”而是在“重新生成”此時(shí)自動(dòng)重連反而制造混亂。所以我后來(lái)把onerror改成了手動(dòng)控制onerror(err) { // 打印原始錯(cuò)誤 console.error(流產(chǎn)生錯(cuò)誤, err.name, err.message); // 如果是 AbortError說(shuō)明是用戶/組件主動(dòng)中止不重連 if (err.name AbortError) { throw err; } // 其他錯(cuò)誤默認(rèn)自動(dòng)重連這里不返回具體值即可 // 如果你希望手動(dòng)控制直接 throw 出去 throw err; }實(shí)際項(xiàng)目里我會(huì)區(qū)分錯(cuò)誤類型來(lái)決策是否重連。主動(dòng) abort 的重試毫無(wú)意義網(wǎng)絡(luò)抖動(dòng)且服務(wù)端支持冪等時(shí)自動(dòng)重連才值得開(kāi)。這樣的決策能力是裸fetch和fetchEventSource都很難替你做主的都需要你對(duì)業(yè)務(wù)流有清晰判斷。5. 寫在最后的個(gè)人體會(huì)這次踩坑讓我最深的感受是凡是封裝良好的庫(kù)都會(huì)在“易用性”和“可控性”之間做選擇。fetchEventSource把 SSE 流式處理中繁瑣的部分——事件解析、重連、打開(kāi)關(guān)閉回調(diào)——全封裝了這是它的價(jià)值但這也意味著你對(duì)底層fetch行為、AbortSignal 語(yǔ)義、甚至是 HTTP 連接生命周期的理解成了你能不能用好它的關(guān)鍵。踩過(guò)幾次坑之后我現(xiàn)在寫流式請(qǐng)求代碼時(shí)一定會(huì)遵循幾個(gè)鐵律每個(gè)AbortController只服務(wù)一個(gè)請(qǐng)求絕不復(fù)用onerror里至少要打一行錯(cuò)誤日志包含error.name和error.messageonopen回調(diào)里記錄 HTTP 狀態(tài)碼方便日后判斷問(wèn)題在“服務(wù)端”還是“連接”服務(wù)端要支持冪等時(shí)再開(kāi)自動(dòng)重連否則必須在業(yè)務(wù)層做去重依賴包升級(jí)后重新過(guò)一遍openWhenHidden、signal、onerror的默認(rèn)行為是否變化。如果讓我對(duì)正在做 AI 應(yīng)用、或者準(zhǔn)備做流式渲染的朋友說(shuō)一句掏心窩的話別急著把所有接口都換到fetchEventSource它不是萬(wàn)能的也別因?yàn)橐淮蝔ailed to fetch就退回原生 fetch那個(gè)坑更大。先想清楚你的業(yè)務(wù)究竟需要什么控制粒度再?zèng)Q定用哪把工具。最后再分享一個(gè)我在排查任何failed to fetch時(shí)的定式先看error.name再看onopen是否執(zhí)行然后復(fù)制 curl 驗(yàn)證服務(wù)端最后檢查 CORS 預(yù)檢和 AbortSignal 狀態(tài)。按這個(gè)順序走目前我還沒(méi)遇到定位不出來(lái)的failed to fetch。希望這篇踩坑記錄能幫你少熬一個(gè)夜。