從 0 建設個人網站
Next.js 部署到 Cloudflare 2026:next-on-pages 停止維護後,升級該怎麼走
Cloudflare 的 next-on-pages 已經棄用,repo 在 2026 年 10 月封存。現在 Next.js 要放上 Cloudflare,官方建議用 vinext 部署到 Workers,還沒辦法換的用 OpenNext;附我們 2023 年從 Next.js 13 升到 14 時被部署工具卡住的經過,和選框架前該先查的事。
Kelvin Wang · · 6 分鐘閱讀
只是靜態網站的話,在 next.config 設 output: 'export' 產生靜態檔,直接放上 Cloudflare 也可以。我們 2023 年把一個 Next.js 專案從 13 升到 14 時,next-on-pages 還不支援新版,升級就卡住了,最後連部署方式也一起改。這段經驗讓我後來選框架時,會先看部署工具由誰維護。
我們遇到什麼?
當時我們用 Next.js 開發網站,希望能自動部署到 Cloudflare Pages。中間用到的工具,就是 @cloudflare/next-on-pages。翻回當時的部署設定,可以看到這些欄位:
Build command: npx @cloudflare/next-on-pages@
Build output: .vercel/output/static
Build comments: Enabled
它像一個轉接頭,把 Next.js 的建置結果整理成能部署到 Cloudflare Pages 的形式。所以除了 Next.js 和 Cloudflare,我們還得留意這個轉接工具能支援哪些版本。
我們原本就打算升級 Next.js,想用新版本的功能。2023 年從 13 升到 14 時,@cloudflare/next-on-pages 還不支援新版,原本搭配舊版 Next.js 的部署方式,成了這次升級要一起處理的部分。這個工具後來被官方棄用;現在的 README 已經明確標示 deprecated,儲存庫在 2026 年 10 月封存,並指向遷移到其他工具的方向。

所以那次的工作,除了升級 Next.js,還包括調整部署方式。那時還沒有 AI 輔助,我們花了不少力氣,才完成從 13 到 14 的升級,並讓 Cloudflare 上的自動部署流程跑起來。
工具棄用不代表舊網站當下就不能跑,已經部署好的版本會繼續運作。但對想繼續升級的專案來說,部署路線要重新評估。
next-on-pages 是什麼、現在是什麼狀態?
next-on-pages 是 Cloudflare 做的轉接工具:先跑 Next.js 的建置,再把輸出轉成 Cloudflare Pages 能執行的格式。它只支援 Next.js 的 Edge runtime,用不到 Node.js runtime 的功能3。
現在的狀態:
- README 寫明套件已棄用、repo 已封存,新專案和遷移都指向 vinext1。
- repo 在 2026 年 10 月 1 日封存,之後不會再有更新或修正1。
- Cloudflare 的 Next.js 指南以 Workers 為目標,Pages 只在你特別要把靜態匯出放 Pages 時才提到2。
如果你的專案還在用 next-on-pages,網站可以繼續跑,但下一次升級 Next.js 大版本時,要預期部署方式得一起換。
2026 年 Next.js 放上 Cloudflare 的路
| 做法 | 適合誰 | 狀態(2026-11-07) |
|---|---|---|
| vinext,部署到 Workers | 新專案,或想從 next-on-pages 遷移的專案 | Cloudflare 的 Next.js 指南列為預設做法。它是用 Vite 重新實作 Next.js API 的開源專案,官網寫涵蓋 Next.js 16 API 約 94%;Cloudflare 指南標示它仍在 beta |
OpenNext 的 Cloudflare adapter(@opennextjs/cloudflare),部署到 Workers | 已經在用 OpenNext、vinext 還有相容缺口的專案 | 用 Next.js 的 Node.js runtime;支援 Next.js 16 全部版本和 15 的最新小版本(14 的支援官方預告在 2026 年第一季結束)。Next.js 15.2 起的 Node Middleware 還不支援 |
| 靜態匯出,放 Cloudflare 靜態檔 | 沒有伺服器端功能的網站 | 只有靜態檔,沒有 SSR、API route |
| 留在 Vercel | 想用 Next.js 原生平台的人 | Hobby 方案免費,但限個人、非商業用途 |
來源:Cloudflare Next.js 指南 [2]、vinext [4]、OpenNext Cloudflare [3]、Vercel Hobby [5]。
幾個要注意的地方:
- vinext 不是 Next.js 本身。 它重新實作 Next.js 的 API,所以你的
app/、pages/、next.config.js可以照用,但它涵蓋的範圍不是 100%4。Cloudflare 的指南建議正式網站先跑npx vinext check再決定2。 - OpenNext 是把 Next.js 的建置結果轉成 Workers 能跑的格式,比較接近原本 next-on-pages 的做法,但用的是 Node.js runtime,能用的功能比 Edge runtime 多3。
- Vercel Hobby 限制的是用途。 Vercel 的文件寫明 Hobby 方案只能用在非商業的個人用途5。個人網站沒問題;要放廣告或接案收費的網站,要看 Pro 方案。
從 next-on-pages 遷移的步驟
用 vinext
Cloudflare 指南列的遷移流程2:
# 1. 先檢查相容性,會列出不支援的地方
npx vinext check
# 2. 加上 vinext:產生 Vite 設定、安裝套件,新增 vinext 專用的 scripts
npx vinext init
# 3. 在本機用 vinext 跑起來、建置
npm run dev:vinext
npm run build:vinext
# 4. 部署到 Cloudflare Workers
npx @vinext/cloudflare deploy
vinext init 不會動到原本的設定,next dev 照樣能用4,所以可以兩邊並行,確認沒問題再切換。如果你用 AI 寫程式工具,Cloudflare 也提供 vinext 的 agent skill(npx skills add cloudflare/vinext),讓工具照官方步驟遷移2。
新專案直接用 C3 建:
npm create cloudflare@latest -- my-next-app --framework=next
用 OpenNext
已經有 Next.js 專案、vinext check 列出的缺口一時補不起來時,改用 OpenNext 的 Cloudflare adapter。新專案的建立指令是3:
npm create cloudflare@latest -- my-next-app --framework=next --platform=workers
既有專案照 OpenNext 文件的 Get Started 做:adapter 會先跑 Next.js 的建置,再把輸出轉成 Wrangler 能部署的格式3。
遷移時的共同步驟
不管選哪條路,這幾件事都要做:
- 把 Cloudflare Pages 專案換成 Workers。 兩條路都部署到 Workers,原本 Pages 專案的建置設定(上面那三個欄位)不再使用。
- 重新接 GitHub 自動部署。 Workers 用 Workers Builds,設定方式和 Pages 不同。
- 搬環境變數。 Pages 專案裡設的變數不會自己跑到 Workers,要重新設,並分清楚建置時和執行時用的變數。
- 網域重新指向。 自訂網域要從 Pages 專案移到新的 Worker。
選框架前,先看部署支援
那次升級之後,我選框架時會多查幾件事:
- 部署工具由誰維護? 框架官方、部署平台,還是社群?next-on-pages 是 Cloudflare 自己的工具,一樣被棄用了,所以「官方」兩個字不夠,還要看它還有沒有在維護。
- 框架的文件有沒有寫這個平台? 框架自己的部署文件裡有寫的平台,升級時比較不會被落下。
- 最近一次更新是什麼時候? 看 repo 的 release 和 issue,封存或很久沒動就是警訊。
- 支援哪些框架版本? 部署工具通常會落後框架的新版本,升級大版本前先查清楚。
- 用哪一種 runtime? Edge 和 Node.js runtime 能用的 API 不同,轉接工具只支援其中一種時,有些功能會不能用。
這個網站為什麼改用 Astro?
所以做這個網站(我的第四個網站)時,我先看框架和部署平台怎麼配合。已經決定繼續用 Cloudflare,就更在意這條部署路徑由誰維護、版本升級時要跟著改什麼。
這也是這次選 Astro 的原因。Cloudflare adapter 是 Astro 的官方整合,部署文件就寫在 Astro 官網6,升級 Astro 時要改什麼,它的升級說明會寫。不過整合路線也會變:Astro 6 的 adapter 就移除了 Cloudflare Pages 支援,改部署到 Workers6。所以看到「官方支援」,我還是會留意它的維護狀態和升級說明。
經歷過那次升級,框架寫起來順不順手只是一部分,改完程式能不能順利上線、之後的維護成本,也要一起算進去。
想深入 個人網站技術架構怎麼選:為什麼用 Astro + Cloudflare,不用 Next.js 或 WordPress 這個網站選型時比較過的選項。資料來源