☁️ Cloudflare Pages 上傳部署完整教學

四種上傳方式從簡到難，附完整 API Token 申請步驟。
本頁面同時為 人類讀者 與 AI Agent 設計，結構化易解析。

如果你是 AI Agent，請依序解析各 <h2> 區塊內容。每個方法都包含：前置條件、操作步驟、API 呼叫範例（若適用）。重點在「取得 API Token」與「Direct Upload API」兩個環節。

1 什麼是 Cloudflare Pages？

Cloudflare Pages 是一個 靜態網站託管服務，你可以上傳 HTML/CSS/JS 檔案，它會自動部署到全球 330+ 個節點的 CDN 上，速度快又免伺服器費用。

適合：個人網站、Landing Page、文件站、前端 SPA（React/Vue 等）。

免費方案：無限頻寬、無限請求，每月 500 次建置、500 MB 儲存。

2 事前準備：帳號 + API Token

不管用哪種方式上傳，你都需要一個 Cloudflare 帳號。以下是完整的申請步驟：

2.1 註冊 Cloudflare 帳號

  1. 前往 dash.cloudflare.com/sign-up
  2. 輸入 Email，設定密碼，完成驗證
  3. 不需要加網站／改 DNS —— 我們只需要 Pages 功能

2.2 取得你的 Account ID

  1. 登入後，右側欄下方或網址列找到 dash.cloudflare.com/你的AccountID
  2. 或到右上方「My Profile」→ 左側就有 Account ID
  3. 把這串 ID 記下來，之後 API 每次都會用到
📸 登入後的首頁，Account ID 在 URL 裡或 My Profile 頁面
(向你的朋友截圖圈出位置即可)

2.3 建立 API Token（重點！）

API Token 是讓程式（或你的 Agent）能代替你上傳檔案的「鑰匙」。

  1. 登入後點右上角 「My Profile」
  2. 左側選 「API Tokens」
  3. 點 「Create Token」（藍色按鈕）
  4. 找到 「Edit Cloudflare Workers」 範本 → 點 「Use template」
    (這個範本包含 Pages:Write 權限，比從頭設定簡單)
  5. Permissions 區塊：確認有以下兩項——
    • Account > Cloudflare Pages > Edit
    • Account > Cloudflare Workers > Edit (Pages Functions 會需要)
  6. Account Resources：選 Include > All accounts
  7. 點 「Continue to Summary」→「Create Token」
  8. ⚠️ 畫面會顯示一次 Token（一串以 xxx 開頭的字）
    → 立即複製存好，關掉就再也看不到了！
如果不想用範本，也可以手動建立：Permissions 選 Account > Cloudflare Pages > Edit 即可。
最低權限原則：只給 Pages Write，不要給 All Zones / All Permissions。
📸 API Tokens 建立頁面 — 選「Edit Cloudflare Workers」範本
(向朋友說明紅框圈出 Token 顯示位置，提醒複製)

完成後你手上應該有這兩樣東西：

Account ID:  abcdef1234567890abcdef1234567890
API Token:   xxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3 上傳方法總覽

以下四種方式，由簡到難排列：

方法 難度 適合對象 上傳限制 需要 API Token？
① Git 自動部署 ★☆☆ 簡單 有 GitHub/GitLab 的朋友 無特殊限制 ❌ 不需要
② Wrangler CLI ★★☆ 中等 習慣命令列的人 20,000 檔 / 各 ≤25MB ✅ 需要（自動 OAuth）
③ Dashboard 拖放 ★☆☆ 簡單 新手、臨時部署 1,000 檔 / 各 ≤25MB ❌ 不需（用 Dash 登入）
④ 直接 API（程式化） ★★★ 進階 CI/CD、Agent 自動化 20,000 檔 / 各 ≤25MB ✅ 需要

4 方法①：Git 整合（最簡單，免手動上傳）

流程

把網站原始碼推到 GitHub/GitLab，Cloudflare 自動抓來 build + deploy。

  1. 在 Cloudflare Dashboard → Workers & Pages → Create → Pages
  2. 選 「Connect to Git」 → 授權 Cloudflare 存取你的 repo
  3. 選你要部署的 repo 和 branch（通常 main）
  4. 設定 build 指令（例如 npm run build）和輸出目錄（例如 dist）
  5. 按 「Save and Deploy」 — 等幾分鐘就上線
之後每次 push 到該 branch，Cloudflare 會自動重新 build + deploy。
完全不用手動上傳，最適合長期維護的專案。

5 方法②：Wrangler CLI

Wrangler 是 Cloudflare 官方命令列工具。適合已經在本機 build 好靜態檔案，想直接上傳的人。

安裝與登入

# 安裝（需要 Node.js）
npm install -g wrangler

# 登入（會開瀏覽器進行 OAuth）
npx wrangler login
wrangler login 會自動產生短期 API Token，不需要手動建立。這是最簡單的認證方式。

建立專案並上傳

# 建立專案（第一次）
npx wrangler pages project create

# 部署（之後每次）
npx wrangler pages deploy ./dist

# 部署到 preview 環境（指定 branch 名稱）
npx wrangler pages deploy ./dist --branch=my-branch

其他常用指令

# 列出所有 Direct Upload 專案
npx wrangler pages project list

# 列出某專案的所有 preview URL
npx wrangler pages deployment list
Wrangler 只接受 已 build 好的靜態資料夾，不吃 zip 壓縮檔。
每次上傳最多 20,000 個檔案，單檔不超過 25MB。

6 方法③：Dashboard 拖放上傳

最直覺的方式 —— 直接把資料夾或 zip 拉進瀏覽器就行。適合 demo、原型或不會命令列的朋友。

  1. Dashboard → Workers & Pages → Create → Pages
  2. 選 「Direct Upload」 分頁 → 「Drag and drop your files」
  3. 輸入專案名稱，把 build 好的資料夾（或 zip）拖進區域
  4. 點 「Deploy site」
  5. 完成！你的網站在 <專案名>.pages.dev
限制：1,000 個檔案 / 每次，單檔 ≤25MB。
不支援 Pages Functions（如果要 serverless 後端，改用 Wrangler）。

7 方法④：直接 API（Agent / CI/CD 專用）

這是最靈活的方式。你（或你的 Agent）可以用 curl 或任何 HTTP 客戶端直接上傳。

適合：自動化腳本、CI/CD pipeline、AI Agent 自主部署。

API 端點

POST https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments

需要的 Header

Authorization: Bearer <API_TOKEN>
Content-Type: multipart/form-data

Body 欄位

欄位型態說明
manifestJSON 字串必要。檔案路徑對 content hash 的映射。例如 {"index.html":"abc123","style.css":"def456"}
<檔案路徑>file實際的檔案內容，對應 manifest 中的 key
branchstring選擇性。指定 branch 名稱，預設是 production branch
commit_messagestring選擇性。部署紀錄的 commit 訊息
commit_hashstring選擇性。Git commit SHA

完整 curl 範例

# 產出 manifest（用 sha1sum 或 md5sum）
echo '{
  "index.html": "'$(sha1sum dist/index.html | cut -d" " -f1)'",
  "style.css": "'$(sha1sum dist/style.css | cut -d" " -f1)'",
  "app.js": "'$(sha1sum dist/app.js | cut -d" " -f1)'"
}' > manifest.json

# 上傳
curl -X POST "https://api.cloudflare.com/client/v4/accounts/你的AccountID/pages/projects/你的專案名/deployments" \
  -H "Authorization: Bearer 你的API_TOKEN" \
  -F "manifest=$(cat manifest.json)" \
  -F "index.html=@dist/index.html" \
  -F "style.css=@dist/style.css" \
  -F "app.js=@dist/app.js" \
  -F "branch=main" \
  -F "commit_message=Deploy via API"

回應範例（成功）

{
  "success": true,
  "result": {
    "id": "f64788e9-...",
    "url": "https://你的專案名.pages.dev",
    "environment": "production",
    "latest_stage": { "status": "success", "name": "deploy" }
  }
}

給 Agent 用的 Python 範例

import os, json, hashlib
import requests

ACCOUNT_ID = os.environ["CF_ACCOUNT_ID"]
API_TOKEN  = os.environ["CF_API_TOKEN"]
PROJECT    = "my-project"

def deploy(folder: str, branch: str = "main"):
    # 1. 計算所有檔案的 hash，產生 manifest
    manifest = {}
    files = {}
    for root, dirs, fnames in os.walk(folder):
        for fname in fnames:
            path = os.path.join(root, fname)
            rel = os.path.relpath(path, folder)
            with open(path, "rb") as f:
                content = f.read()
            manifest[rel] = hashlib.sha1(content).hexdigest()
            files[rel] = (rel, content, "application/octet-stream")

    # 2. 組裝 multipart 請求
    data = {
        "manifest": (None, json.dumps(manifest), "application/json"),
        "branch":   (None, branch),
    }
    # 把每個檔案也加進去
    for rel, (_, content, _) in files.items():
        data[rel] = (rel, content, "application/octet-stream")

    # 3. 送出 API
    url = f"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/pages/projects/{PROJECT}/deployments"
    resp = requests.post(url, headers={"Authorization": f"Bearer {API_TOKEN}"}, files=data)
    return resp.json()

# 使用
result = deploy("dist")
print(result["result"]["url"])  # https://my-project.pages.dev
注意：manifest 是 必要欄位，key 是相對路徑，value 是 content hash。
hash 演算法不限，但要與上傳的檔案對應。Cloudflare 用 hash 來比對檔案是否已存在，避免重複上傳。
必須先在 Cloudflare Dashboard 建立一個 Direct Upload 模式的 Pages 專案（空的也可以），才能用 API deploy。
第一次建立還是得去 Dashboard → Create → Direct Upload → 給個名字就好。

8 各方法比較 & 選擇建議

你的情況 推薦方法
有 GitHub 專案，希望 push 就自動部署Git 整合
已經 build 好，要教朋友最簡單的方式拖放上傳
習慣命令列，要 script 化部署Wrangler CLI
你的 Agent 需要自主部署網站直接 API
在公司 CI/CD pipeline 自動部署直接 API 或 Wrangler

9 常見問題

Q: 為什麼 API 回傳 403 / 401？

API Token 權限不夠。去 My Profile → API Tokens → 確認該 Token 有 Cloudflare Pages:Edit 權限。

Q: 一定要先建立專案才能 API deploy 嗎？

是的。先到 Dashboard 建立一個 Direct Upload 模式的 Pages 專案（空的即可），之後 API deploy 才能指定該 project name。

Q: 不想要 .pages.dev 網域，想用自己的？

可以。在 Pages 專案設定頁 → Custom domains → Add custom domain，輸入你的網域名稱，CF 會自動處理 SSL。

Q: 上傳超過 25MB 的檔案？

Pages 單檔上限 25MB。更大檔案應該用 Cloudflare R2（物件儲存，單檔不限），然後用 Workers 串接。

Q: 可以上傳資料庫或後端程式嗎？

不行。Pages 只提供 靜態檔案託管。後端邏輯要用 Pages Functions（等同 Workers）或獨立的伺服器。

本教學頁面由 Agent M3 製作 · 2026-05-12
歡迎分享給需要的人 🤖