技術記錄書

補部署 SOP 與問題排查 | 2026-04-24

Cloudflare Pages wrangler 陷阱實戰經驗

如何找出「24小時內已部署但未正確上傳」的文件並進行一次性補部署

一、問題現象

在使用 wrangler pages deploy 部署 Cloudflare Pages 專案時，可能出現以下假象：

終端顯示部署成功（無錯誤訊息）
但實際上 0 files uploaded，文件並未真正上傳
瀏覽器訪問時返回 404

二、根因分析

觸發條件

wrangler 會比較本地文件時間戳與雲端記錄。當本地文件自上次部署後無任何變更，wrangler 會判定「無需上傳」並直接返回，終端只顯示：

✨ Deployment complete!
✨ 0 files uploaded
✨ Built successfully

為何危險

終端不回報錯誤（看起來像成功）
用戶以為已上線，實際文件不存在
排查方向錯誤（懷疑 URL 路由、CORS 等）
緩存問題掩蓋真相（部分用戶運氣好能訪問舊版本）

三識別方法（完整流程）

Step 1：查詢 Cloudflare 部署歷史

# 查詢最近 24 小時的部署記錄
npx wrangler pages deployment list --project-name=aiforall

重點關注：

Deployment ID（deployment hash）
Created 時間
Files uploaded 數量

Step 2：比對本地與線上文件

建立本地文件清單（含時間戳）：

Get-ChildItem -Path "C:\path\to\project" -Filter "*.html" -Recurse |
  Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-1) } |
  Select-Object FullName, LastWriteTime |
  Sort-Object LastWriteTime -Descending

對比線上 deployment 的文件列表，檢查以下條件：

該 deployment 的 Files uploaded > 0
本地文件在 deployment 時間之後有更新
這些文件在線上 URL 可正常訪問

Step 3：檢查 memodata 覆蓋完整性

若項目使用 memodata 管理導航入口，檢查：

memodata.html 中的 backups 區域是否包含所有最近部署的文件 ID
data/memodata.json 的 count 是否與備忘卡片數量一致
是否有 tomemo-*.html 文件在 memodata 中缺失條目

四、一次性補部署 SOP

觸發條件（滿足任一即需補部署）

wrangler 顯示 0 files uploaded
線上 URL 返回 404，但本地文件存在
memodata 覆蓋缺口報告顯示「已部署但缺失」

Step 1：確認缺失文件清單

# 檢查本地文件 vs 線上狀態
from datetime import datetime, timedelta
import os

local_dir = "C:\\path\\to\\project"
cutoff = datetime.now() - timedelta(hours=24)

for f in os.listdir(local_dir):
    if f.endswith('.html'):
        mtime = datetime.fromtimestamp(os.path.getmtime(f))
        if mtime > cutoff:
            print(f"最近修改: {f} ({mtime})")

Step 2：強制變更時間戳觸發上傳

# 方式一：touch 所有最近修改的文件
Get-ChildItem -Path "C:\path\to\project" -Filter "*.html" |
  Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-1) } |
  ForEach-Object { $_.LastWriteTime = Get-Date }

# 方式二：只 touch index.html（wrangler 以此為觸發）
(Get-Item "index.html").LastWriteTime = Get-Date

Step 3：執行部署

npx wrangler pages deploy C:\path\to\project --project-name=your-project

⚠️ 驗證 Files uploaded 數量 必須 > 0

Step 4：驗證線上狀態

直接訪問 deployment hash URL（如 d71d8a7d.project.pages.dev）
繞過 CDN 緩存立即看到真實狀態
檢查目標文件是否存在

五、預防機制

自動化監控腳本

import subprocess
import json
from datetime import datetime, timedelta

def check_recent_deployments(project_name):
    """檢查最近部署是否有異常"""
    result = subprocess.run(
        ['npx', 'wrangler', 'pages', 'deployment', 'list',
         f'--project-name={project_name}', '--json'],
        capture_output=True, text=True
    )
    deployments = json.loads(result.stdout)

    for dep in deployments[:5]:  # 最近的 5 個
        created = datetime.fromisoformat(dep['created_on'].replace('Z', '+00:00'))
        if datetime.now() - created < timedelta(hours=24):
            if dep['files_count'] == 0:
                print(f"⚠️ 異常部署：{dep['id']} - 0 files uploaded")
                return False
    return True

memodata 一致性檢查

每次部署後自動執行：

讀取 memodata.html 的 backups 區域
檢查每個 ID 對應的 .html 文件是否在線
產出缺口報告

六、案例記錄（2026-04-24）

項目	內容
專案	aiforall
問題	wrangler deploy 返回「0 files uploaded」
根因	本地文件自上次部署後無變更，wrangler 跳過上傳
症狀	瀏覽器 404，但部署 API 回報成功
解決	touch index.html 後重新部署
驗證	deployment hash URL 可正常訪問
經驗	任何部署後立即檢查 files uploaded 數量

七、快速參考卡

⚠️ 部署成功的假象：
  ✅ 無錯誤訊息
  ✅ "Deployment complete"
  ❌ 但 "0 files uploaded"

✅ 正確部署的標誌：
  ✅ "N files uploaded"（N > 0）
  ✅ deployment hash 生成
  ✅ 線上 URL 可訪問
  ✅ wrangler.toml 正確配置