外觀

語言

從 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-on-pages 現在的 README:套件已棄用、儲存庫已封存,新專案與遷移建議改用 vinext

所以那次的工作,除了升級 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。

遷移時的共同步驟

不管選哪條路,這幾件事都要做:

  1. 把 Cloudflare Pages 專案換成 Workers。 兩條路都部署到 Workers,原本 Pages 專案的建置設定(上面那三個欄位)不再使用。
  2. 重新接 GitHub 自動部署。 Workers 用 Workers Builds,設定方式和 Pages 不同。
  3. 搬環境變數。 Pages 專案裡設的變數不會自己跑到 Workers,要重新設,並分清楚建置時和執行時用的變數。
  4. 網域重新指向。 自訂網域要從 Pages 專案移到新的 Worker。
想深入 Cloudflare Workers 教學 2026:Astro 部署與 wrangler 設定 Workers Builds、環境變數、綁網域和部署失敗排查的完整步驟。

選框架前,先看部署支援

那次升級之後,我選框架時會多查幾件事:

  • 部署工具由誰維護? 框架官方、部署平台,還是社群?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 這個網站選型時比較過的選項。

資料來源

  1. 1. cloudflare/next-on-pages README · GitHub · 2026-11-07 查詢
  2. 2. Next.js · Cloudflare Workers docs · Cloudflare · 2026-11-07 查詢
  3. 3. OpenNext Cloudflare · OpenNext · 2026-11-07 查詢
  4. 4. vinext · Cloudflare · 2026-11-07 查詢
  5. 5. Vercel Hobby Plan · Vercel · 2026-11-07 查詢
  6. 6. @astrojs/cloudflare · Astro Docs

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我