2026 Next.js 16.1 PPR 在 Cloudflare Workers 上會自動使用分塊編碼嗎?

Cloudflare Workers 官方文件確認支援 ReadableStream 串流回應,並說明以 ReadableStream 作為回應本文時會使用分塊編碼;這是平台傳輸機制,不足以單獨證明 Next.js 16.1 PPR 故障由此引起。若你正在查頁面串流異常,先核對請求路徑、協定與本文是否完整結束,再依對照結果調整應用或部署設定。
本文適合正在驗證 Next.js 16.1 PPR 與 Cloudflare Workers 回應行為的前端、全端及平台工程師。
需要共用開發環境重現問題的技術負責人,也可參考本文;雲端 Mac 可作為開發工作區,但不是 Workers 執行環境的替代品。
Workers 的 ReadableStream 回應如何傳輸?
Cloudflare 官方的 Workers Streams 文件說明,Workers 支援串流處理;其 Response 文件則說明,以 ReadableStream 作為回應本文時會使用分塊編碼。這些資訊能確認 Workers 的串流能力與特定回應本文的傳輸行為,不能據此推論每一條 Next.js 部署路徑都會保留串流,也不能證明分塊編碼會截斷 PPR 頁面。
還要區分 HTTP 版本。HTTP/1.1 的分塊傳輸編碼有明確的訊息格式與結束標記,可參照 RFC 9112 的 Transfer-Encoding 規範。瀏覽器面板中若看不到 Transfer-Encoding: chunked,不代表回應沒有逐步到達:瀏覽器與中間層可能使用不同協定,且 HTTP/2 不使用 HTTP/1.1 的分塊傳輸編碼欄位。應以實際協商的協定和本文是否完成作判斷,而不是只搜尋單一標頭。
對 Next.js 版本設定也要分開核實。Next.js 官方版本 16 升級指南指出,Next.js 16 以 cacheComponents 設定啟用 PPR,並移除實驗性 PPR 標記及相關設定選項。這與傳輸層如何傳送 ReadableStream 是兩件事;看到舊版 experimental_ppr 設定,不應直接當成分塊編碼故障證據。
注意:回應標頭只描述可觀察到的傳輸資訊,不會自動交代適配器中間是否讀取、緩衝或重新建立了本文。故障結論需要對應到實際部署路徑。
瀏覽器直連與中間轉換
同一路徑的瀏覽器請求
先選定一個可穩定重現的 PPR 路由,從瀏覽器直接請求。記錄狀態碼、瀏覽器顯示的 HTTP 協定、可見回應標頭,以及頁面是否完整結束。若動態區域一直載入,記下它停在哪個位置,並保留該次請求的時間與識別資訊,方便與伺服器端記錄比對。
標頭能協助辨識回應型態與傳輸線索,卻無法單獨證明是哪一層中止了本文。Transfer-Encoding 欄位不出現,也無法單獨說明本文是一次送達、串流送達,或在中間層被轉換。一次請求成功或失敗同樣只代表該次條件下的結果,不能推廣成平台普遍行為。
適配器與自訂 Worker 的回應路徑
沿部署鏈路逐段確認是否有適配器或自訂 Worker 介入。重點是檢視實際程式碼與設定:它是否直接轉送回應,是否呼叫 text() 或 arrayBuffer() 讀取完整本文,是否組裝新回應,是否將資料暫存後才送出。Cloudflare 的 Response API 說明可用來核對回應物件的行為;但適配器是否保留串流,仍須以該適配器的版本文件、程式碼或部署紀錄判定。
操作時可依序執行:
- 固定受影響路由、部署版本與請求條件,避免比較不同頁面或不同部署。
- 由瀏覽器直連取得一次基準結果,保存狀態碼、協定、標頭及本文結束狀態。
- 沿部署設定找出適配器、自訂 Worker、快取與壓縮等中間環節。
- 逐段檢查回應本文是否被完整讀取、緩衝或重新建立,記下程式碼位置與設定。
- 在同一條部署路徑重送相同請求,將結果與基準逐項比對。
- 若變更設定或程式碼,每次只改一項,並以相同請求重測;保留成功與失敗的記錄。
這套流程不是預先認定某個適配器必然會中斷串流,而是把「可能改變本文傳送方式的位置」變成可核對的證據。
快取與壓縮請求的對照
快取命中、未命中及壓縮狀態可能改變請求經過的處理路徑,因此宜逐項對照,而不是直接把它們定為根因。Cloudflare 的快取回應排查文件可協助判讀快取狀態;內容壓縮說明則可供核對壓縮行為。
對同一路徑至少保留兩組可比較請求:一組確認快取命中狀態,另一組確認未命中狀態;再分別觀察壓縮啟用與關閉時的回應。每次都記錄狀態碼、協定、可見標頭、本文是否完成及頁面動態區域是否結束載入。若快取或壓縮改變結果,這是排查線索,仍需檢視實際回應路徑和重複結果,才能建立因果關係。
PPR 對照與回退條件
建立啟用 PPR 與不啟用 PPR 的同路由對照。兩者使用一致的部署路徑、請求條件與快取及壓縮設定,並分別保留結果。若只改了 PPR 設定,同時更換適配器或清除快取,結果便不能明確歸因於單一變更。
決策條件列表:
- 若兩種設定都在相同請求條件下出現相同截斷,先查部署鏈路與回應轉換,不要把 PPR 定為唯一原因。
- 若只有啟用 PPR 時可重複出現異常,停用 PPR 後相同請求完成,才有理由把暫時回退列為止血選項;仍需繼續確認部署路徑及版本差異。
- 若異常只在快取命中或壓縮啟用時出現,先固定該條件重測,再檢查對應處理環節;不要直接判定快取或壓縮就是根因。
- 若直連與經過自訂 Worker 的結果不同,逐段核對轉送及本文處理程式碼,並將差異定位到可重現的部署路徑。
使用者若看到 502,也要分辨由哪一層回應。Cloudflare 的502/504 錯誤排查文件指出,可依回應表現及相關記錄檢查錯誤來源。應保存實際回應內容與請求記錄,再判斷是 Cloudflare 回傳的錯誤,還是應用程式自行產生的 502;狀態碼相同不等於來源相同。
三組結果記錄表
| 核對情境 | 必須記錄 | 可以支持的判斷 | 不能單獨證明 |
|---|---|---|---|
| 瀏覽器直連 | 狀態碼、協定、可見標頭、本文是否結束 | 該次請求的回應表現 | 所有節點或所有請求都相同 |
| 經過適配器或自訂 Worker | 轉送方式、本文讀取或重建位置、部署設定 | 中間層是否可能改變回應本文 | 某類適配器必然中斷串流 |
| 快取或壓縮請求 | 快取狀態、壓縮設定、本文完成狀態 | 特定條件下結果是否不同 | 快取或壓縮就是故障根因 |
| PPR 對照 | 請求與部署條件 | 結果用途 |
|---|---|---|
| 啟用 PPR | 路由、部署路徑、快取與壓縮條件固定 | 建立動態區域的基準表現 |
| 不啟用 PPR | 沿用相同請求及部署條件 | 判斷改變 PPR 設定是否伴隨結果變化 |
| 修改單一中間環節 | 只改一項程式碼或設定 | 定位差異是否與該環節相關 |
| 結論層級 | 記錄內容 | 表述方式 |
|---|---|---|
| 官方確認 | Next.js 與 Cloudflare 官方文件中的設定及傳輸說明 | 說明文件確認了什麼,不延伸成故障因果 |
| 部署觀測 | 路由、請求條件、回應協定、狀態碼及本文完成結果 | 限定為該部署路徑與該次可重複條件 |
| 待驗證假設 | 尚未排除的適配器、快取、壓縮或應用程式因素 | 明確標為假設,待新測試或版本文件確認 |
共享開發環境與線上執行環境
本機開發環境適合檢查 Next.js 程式碼,但團隊若使用不同設定、依賴版本或請求入口,重現結果可能不一致;單靠本機瀏覽器也不等於驗證了 Workers 上的真實回應路徑。另一方面,雲端 Mac 可用來統一建置與協作工作區,但不能代替 Cloudflare Workers 的線上執行環境,也不能代替對正式部署回應的觀測。
需要把復現步驟交接給團隊時,可先查看 ProxyMac 使用說明,確認遠端開發工作區的使用方式。若比較租用與自建工作區的成本,再以 ProxyMac 方案與計價資訊核實實際條件,不應把工作區成本和 Workers 執行成本混為一談。
現有本機環境可能有設定不一致、難以共享及無法直接代表線上邊緣路徑等限制;添置實體 Mac 則需自行管理設備與維護。若問題需要團隊共用的遠端開發工作區,ProxyMac 可作為租用 Mac 的選項;若要驗證 Cloudflare Workers 的實際回應,仍須在目標部署路徑完成相同請求測試。只有把工作區與線上執行環境分開看,才能避免用一種環境的成功或失敗替另一種環境下結論。