Cloudflare Pages 託管讓前端團隊能夠發布快速、安全且無需伺服器管理的程式碼。透過使用 Cloudflare Pages ，開發者獲得了一個高效能的邊緣原生平台，用於部署靜態 Web 應用、單頁應用（SPA）和伺服器端渲染（SSR）框架。透過直接連接到你的 Git 儲存庫，Cloudflare 自動化建置流水線、產生預覽部署，並在全球範圍內託管資源。本指南將說明如何連接 Git、設定建置設定、設定自訂網域以及設定重新導向。

重點摘要（TL;DR）

  • 部署邊緣原生前端應用；Cloudflare Pages 從 Cloudflare 網路在全球範圍內提供資源，確保次秒級載入時間。
  • 自動化 Git 整合；連結你的儲存庫以觸發自動建置，並為每次提交產生預覽 URL。
  • 設定框架建置設定；為 React、Vue、Next.js、Hugo 或 Astro 設定輸出目錄和命令。
  • 使用 public 資料夾中的純文字 _redirects 和 _headers 檔案套用重新導向和標頭規則。
  • 使用由 Cloudflare 管理的免費、自動續期的 SSL 憑證對應自訂網域。

什麼是 Cloudflare Pages？

Cloudflare Pages 是一個面向前端開發者的無伺服器託管平台，類似於 Netlify 或 Vercel，直接建構於 Cloudflare 的全球基礎設施之上。

Cloudflare Pages 並非將檔案託管在單一雲端伺服器上，而是將你的 HTML、CSS、JavaScript 和圖片分發到世界各地的邊緣節點。當使用者請求你的網站時，資源會從最近的位置提供，從而降低網路延遲。對於需要伺服器端邏輯的專案，Pages 會與 Cloudflare Workers 整合以執行後端函式。若要將 Pages 與其他邊緣運算服務進行比較，請閱讀我們關於 Cloudflare Pages vs Workers 的指南。

先決條件

開始之前，請確保你已準備好以下各項：

  • 一個位於 GitHub 或 GitLab 上、包含你專案的 Git 儲存庫（或已建置好、可直接上傳的檔案）。
  • 一個輸出靜態資源的框架 —— React（Vite）、Vue、Astro、SvelteKit、Hugo 或純 HTML。伺服器端渲染框架也可以透過 Pages Functions 執行。
  • 一個可正常運作的本機建置。 在連接任何東西之前，執行你的建置命令（例如 npm run build）並確認輸出資料夾能夠無錯誤地產生。
  • 一個免費的 Cloudflare 帳戶。 免費方案無需信用卡。
  • 在本機安裝 Node.js（建議），以便你可以重現建置並使用 Wrangler 命令列工具。

一次快速的合理性檢查能在日後節省數小時的除錯時間：如果你的網站在自己的機器上無法乾淨地建置，那麼它在 Cloudflare 的建置器上也無法建置。請先解決本機錯誤。

步驟 1：連接你的 Git 儲存庫

首先，登入 Cloudflare Dashboard，導覽至 Compute > Pages，然後點選 Create a project。

選擇 Connect to Git 以連結你的 GitHub 或 GitLab 帳戶。選擇包含你靜態 Web 應用的儲存庫。這種整合非常有價值，因為它建立了一條持續整合（CI）流水線：每次你將程式碼推送到生產分支時，Cloudflare 都會自動建置並部署更新。對於其他提交，Cloudflare 會產生唯一的「預覽 URL」，以便你在合併之前測試變更。

步驟 2：設定建置設定

Cloudflare Pages 支援熱門的靜態網站產生器和前端框架。在設定精靈過程中，根據你的技術堆疊設定以下設定：

  • 建置命令：在你的 package.json 中定義的建置指令碼（例如 npm run build 或 hugo --minify）。
  • 建置輸出目錄：包含已編譯靜態檔案的資料夾（例如 dist、build 或 public）。
  • 環境變數：如果你的建置指令碼需要 API 金鑰或設定變數，請在此處定義它們。

Cloudflare 會自動偵測許多框架，但確認預設可以避免首次建置失敗。常見的組合有：

框架建置命令輸出目錄
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (static export)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

固定你的 Node 版本。 「本機能用，Cloudflare 上失敗」的一個常見原因是建置執行器預設使用的 Node 版本與你專案期望的版本不相符。請明確宣告它，可以作為 dashboard 中的環境變數：

1NODE_VERSION = 20

或者透過向儲存庫根目錄提交一個 .node-version 檔案：

120

步驟 3：設定重新導向和標頭

對於單頁應用（如 React Router）或舊版 URL 遷移，你必須設定路由和重新導向規則。Pages 透過放置在你輸出目錄中的簡單文字檔案來處理這一點。

重新導向 (_redirects)

在你的 public 資料夾中建立一個名為 _redirects 的檔案。為了讓 React SPA 乾淨地處理用戶端路由，請新增後備規則：

1/*  /index.html  200

這會強制所有請求解析到 index.html，從而允許 JavaScript 路由器管理路徑。

順序很重要。Cloudflare 從上到下評估規則並在第一次相符時停止，因此具體的重新導向必須位於萬用後備規則之上：

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

:splat 佔位符會將路徑中相符到的部分傳遞到目標位址。免費方案允許每個專案最多 2,000 條靜態重新導向規則；超出該數量後，請將邏輯遷移到 Pages Function 或 Bulk Redirects 中。

自訂標頭 (_headers)

建立一個名為 _headers 的檔案，以套用安全規則、Referrer-Policy 或自訂快取控制：

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

同一個檔案也是調整快取的合適位置。帶指紋的不可變資源可以快取一年，而 HTML 則保持新鮮，以便使用者始終收到最新的建置：

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

若要了解這些規則與傳統後端路由的對比，請閱讀使用 Cloudflare Workers 建構無伺服器 API 。

步驟 4：對應自訂網域

部署完成後，Cloudflare 會提供一個預設子網域（例如 your-project.pages.dev）。

若要對應你的自訂網域，請導覽至 Pages 專案中的 Custom Domains 索引標籤，並輸入你的網域（例如 yourcompany.com）。如果你的 DNS 由 Cloudflare 管理，平台會設定 CNAME 記錄並立即佈建一個免費、自動續期的 SSL 憑證。如果你在管理網域對應、DNS 或伺服器安全方面需要協助，請查看網站安全稽核 頁面。

步驟 5：使用 Wrangler CLI 部署（直接上傳）

Git 整合適合大多數團隊，但你也可以使用 Cloudflare 的命令列工具 Wrangler 直接從你的機器或現有流水線進行部署。當你的建置已經在 GitHub Actions 或 GitLab CI 中執行，而你只想上傳已完成的輸出時，這會很有用。

安裝 Wrangler 並進行身分驗證：

1npm install -g wrangler
2wrangler login

在本機建置，然後將輸出目錄推送到一個已命名的專案：

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

首次執行時，如果專案尚不存在，則會建立它。在 CI 中，請將互動式的 wrangler login 替換為透過環境變數提供的、範圍受限的 API 權杖，這樣就不需要瀏覽器步驟：

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

直接上傳會跳過 Cloudflare 自己的建置步驟，從而規避建置環境問題，並讓你完全掌控工具鏈。

常見陷阱與疑難排解

少數幾個問題佔據了大多數首次部署失敗的原因：

  • 重新整理 SPA 路由時出現 404 錯誤。 諸如 /dashboard 之類的用戶端路由會傳回 「Nothing is here yet」，因為磁碟上不存在相符的檔案。解決方法是在 _redirects 中使用 /* /index.html 200 後備規則，並確認該檔案落在建置輸出中，而不是你的原始資料夾中。
  • _redirects 或 _headers 似乎被忽略。 這些檔案必須位於已發布的輸出目錄中，而不僅僅是儲存庫中。對於 Vite、Astro 或 SvelteKit，請將它們放在 public/（或 static/）資料夾中，以便建置時將其原樣複製過去。
  • 本機建置成功但在 Cloudflare 上失敗。 這幾乎總是 Node 版本不相符或缺少建置時變數所致。請固定 Node 版本並重新宣告建置所讀取的任何變數——它們與執行階段繫結是分開的。
  • 「Too many files」或部署過大。 單次部署上限為 20,000 個檔案，每個檔案限制為 25 MiB。大型媒體應放在 R2 或圖片服務中，而不是靜態套件內。
  • 發布後資源陳舊。 諸如 app.4f2c.js 之類的帶雜湊檔案可以被積極地快取，但 index.html 不應如此。請讓 HTML 保持較短的快取，並讓帶指紋的資源保持不可變，如前所示。

測試與生產考量

Cloudflare 會為每個非生產分支和拉取請求建置一個預覽部署，每個都有自己的 URL（例如 abc123.my-web-app.pages.dev）。由於預覽執行在與你線上網站相同的邊緣網路上，它們是在合併前審查變更的可靠場所。

對於真正的發布，幾項控制機制決定了它究竟是一個託管服務還是一套可靠的工作流程：

  • 回滾。 每次部署都會被保留，因此有問題的發布可以透過在 dashboard 中將先前的建置重新提升到生產環境來回退，幾秒鐘即可完成，無需重新建置。
  • 環境隔離。 為生產環境和預覽環境設定不同的變數，以便預覽建置指向暫存 API 而不是線上資料。
  • 分析與 Core Web Vitals。 啟用 Cloudflare Web Analytics——注重隱私且無 cookie——以在不載入第三方指令碼的情況下追蹤真實使用者的 LCP、CLS 和流量。
  • 預覽的存取控制。 預覽 URL 預設是公開的。如果某個分支暴露了未發布的工作，請將其置於 Cloudflare Access 之後，以便只有你的團隊才能開啟它。

盡早落實這些措施，可以在專案不斷壯大、越來越多人向其推送程式碼時，讓你的部署保持可預測。

關鍵要點

  • Cloudflare Pages 將靜態 Web 應用託管在 Cloudflare 的全球邊緣網路上，最佳化載入速度。
  • 透過連結 GitHub 或 GitLab 在每次提交時編譯程式碼，從而自動化部署。
  • 定義與你的框架（Astro、Next.js、Hugo、React）相符的建置命令和輸出目錄。
  • 在你的輸出目錄中使用簡單的 _redirects 和 _headers 文字檔案設定重新導向和安全標頭。
  • 使用由 Cloudflare 直接管理的免費、自動續期的 SSL 憑證對應自訂網域。

最佳化你的 Web 基礎設施

部署快速、安全的前端需要選擇正確的託管架構和快取規則。Mecanik 專注於網站開發服務 ，並提供專業的技術 SEO 稽核服務 。我們建構針對 Core Web Vitals 最佳化並部署在 Cloudflare 上的客製化 React、Next.js 和 Astro 平台。立即聯絡我們，商討你的下一個建置專案。

常見問題（FAQ）

什麼是 Cloudflare Pages 託管？ 它是一個無伺服器前端託管平台，在 Cloudflare 的 CDN 上於全球範圍內建置並提供靜態 Web 應用、React SPA 以及靜態網站產生器的輸出（如 Astro 或 Hugo）。

Cloudflare Pages 是否支援伺服器端渲染（SSR）？ 是的。Pages 透過在建置過程中自動將伺服器邏輯轉換為無伺服器的 Cloudflare Workers，來支援 SSR 框架（如 Next.js、Astro、SvelteKit）。

如何在 Cloudflare Pages 上設定重新導向？ 你在建置輸出目錄中建立一個名為 _redirects 的純文字檔案，並撰寫重新導向規則，定義來源路徑、目標路徑和 HTTP 狀態碼。

Cloudflare Pages 是免費的嗎？ 是的。Cloudflare Pages 提供了慷慨的免費方案，包含無限次部署、無限頻寬和自訂網域，使其在靜態託管方面極具成本效益。

如何在 Pages 上設定自訂網域？ 導覽至你的 Pages 專案 dashboard 中的 Custom Domains 索引標籤，輸入你的網域名稱，Cloudflare 便會設定 DNS 記錄並簽發一個免費的 SSL 憑證。