DevOps / CI/CD

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

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 說明可用來核對回應物件的行為;但適配器是否保留串流,仍須以該適配器的版本文件、程式碼或部署紀錄判定。

操作時可依序執行:

  1. 固定受影響路由、部署版本與請求條件,避免比較不同頁面或不同部署。
  2. 由瀏覽器直連取得一次基準結果,保存狀態碼、協定、標頭及本文結束狀態。
  3. 沿部署設定找出適配器、自訂 Worker、快取與壓縮等中間環節。
  4. 逐段檢查回應本文是否被完整讀取、緩衝或重新建立,記下程式碼位置與設定。
  5. 在同一條部署路徑重送相同請求,將結果與基準逐項比對。
  6. 若變更設定或程式碼,每次只改一項,並以相同請求重測;保留成功與失敗的記錄。

這套流程不是預先認定某個適配器必然會中斷串流,而是把「可能改變本文傳送方式的位置」變成可核對的證據。

快取與壓縮請求的對照

快取命中、未命中及壓縮狀態可能改變請求經過的處理路徑,因此宜逐項對照,而不是直接把它們定為根因。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 的實際回應,仍須在目標部署路徑完成相同請求測試。只有把工作區與線上執行環境分開看,才能避免用一種環境的成功或失敗替另一種環境下結論。

用專屬雲端 Mac,穩定重現串流測試

透過 ProxyMac 獨享 Mac mini M4,建立專用環境,按相同請求反覆比對不同設定下的頁面串流表現。
支援 SSH、VNC 與瀏覽器連線,方便您從命令列或遠端桌面執行測試與檢查結果。