# Cloudflare 官方文件認知底稿（2026-05-12 UTC）
> 用途：本專案所有 Cloudflare 教學、Prompt、架構建議與上線 Checklist 都必須以這份底稿為準；如果之後 Cloudflare 官方文件更新，先更新本檔，再改產品內容。
## 官方來源（必須優先查這些）
- Nuxt on Cloudflare Pages：
- Pages Functions Bindings：
- Workers storage / database choice：
- Cron Triggers：
- Wrangler commands：
- Cloudflare docs for LLM：、Workers：、Pages：
## Nuxt + Cloudflare Pages 正確上線方式
### 官方建議的新專案方式
Cloudflare 官方 Nuxt guide 建議使用 C3（`create-cloudflare`）產生相容 Cloudflare Pages 的 Nuxt 專案：
```bash
npm create cloudflare@latest -- my-nuxt-app --framework=nuxt --platform=pages
```
C3 會用官方 Nuxt CLI 建專案、安裝 Cloudflare adapters / Wrangler，並讓專案相容 Cloudflare Pages。
### 已有 Nuxt 專案的部署設定
如果不是從 C3 建專案，仍可部署到 Pages：
- Cloudflare Pages Git Integration：連 GitHub/GitLab repo，push commit 後自動 build/deploy。
- Direct Upload：本地 build 後用 Wrangler 上傳。
- 官方 Nuxt Pages guide 的 Git integration 設定：
- Production branch：`main`
- Build command：`npm run build`
- Build directory：`dist`
本專案目前採用已存在 repo 升級，不重建新 repo；因此會保留 source，補齊 Nuxt、Nitro `cloudflare-pages` preset、`wrangler.toml` 與 `dist` build output。
## Wrangler 使用原則
Cloudflare 官方 Wrangler commands 文件說明：
- Cloudflare 建議把 Wrangler 安裝在專案本地，而不是依賴全域安裝。
- 執行方式依 package manager：
```bash
npx wrangler [COMMAND] [OPTIONS]
yarn wrangler [COMMAND] [OPTIONS]
pnpm wrangler [COMMAND] [OPTIONS]
```
本專案 package scripts 會使用 `npx wrangler ...` 或 npm scripts 包裝常用命令，避免假設使用者有全域 Wrangler。
## Pages Functions Bindings 正確認知
Cloudflare Pages Functions 的 binding 是讓 Pages Functions 與 Cloudflare Developer Platform 產品互動的方式。官方列出的 binding 類型包含：
- KV namespaces
- Durable Objects
- R2 buckets
- D1 databases
- Vectorize indexes
- Workers AI
- Service bindings
- Queue producers
- Hyperdrive configs
- Analytics Engine datasets
- Environment variables and secrets
重要規則：
1. binding 可以用 Wrangler config 或 Cloudflare Dashboard 設定。
2. Production 與 Preview 環境要分別確認。
3. 底層資源（例如 D1 database、R2 bucket、KV namespace）通常要先存在，才能被綁定到 Pages project。
4. 設定 binding / variables / secrets 後，必須 redeploy，新的部署才會取得新環境。
5. Pages Functions 中透過 `context.env` 讀取 binding；Nuxt/Nitro 在 Cloudflare runtime 下要透過對應 runtime context / Nitro preset 取得 Cloudflare env，不可把 dashboard 設定誤寫成前端常數。
## Cloudflare storage / database 選型
依官方 Workers storage options：
- **Workers KV**：高讀取量、讀多寫少、可接受 eventual consistency 的 key-value；適合 session/config/feature flags/路由 metadata。官方文件提醒 KV 對單一 key 有寫入速率限制，不適合高頻同 key 寫入或強一致交易。
- **R2**：object/blob storage；適合圖片、使用者上傳檔案、web assets、ML dataset、log/event data。不是 SQL database。
- **D1**：serverless SQL database；適合關聯資料，例如 user profiles、product listings、orders、customer data。適合輕量、read-heavy、希望不管理傳統 DB 的 Workers app。
- **Durable Objects**：stateful serverless、global coordination、WebSocket、強一致/transactional state；D1 與 Queues 底層也建立在 Durable Objects 之上。
- **Queues**：background job processing、batching、message queue、deferred tasks，例如 email、通知、外部 API 呼叫。
- **Hyperdrive**：連接既有 Postgres/MySQL，保留現有 DB driver / ORM，適合已有大型資料庫。
- **Vectorize**：embedding / semantic search。
- **Analytics Engine**：高基數 time-series metrics。
本產品不能把所有需求都粗暴建議 D1：
- 使用者資料、方案、文章草稿 metadata：D1。
- 圖片、PDF、template package：R2。
- Session/config/低頻變更設定：KV。
- 產圖、寄信、爬資料、批次分析：Queues 或 Workflows。
- 排程觸發每日任務：Workers Cron Trigger（通常是 Worker，不是 Pages 靜態頁本身）。
## Cron Triggers 正確認知
官方 Cron Triggers 文件重點：
- Cron Triggers 讓 Worker 依 cron expression 執行 `scheduled()` handler。
- 時間以 UTC 為準。
- 新增、更新、刪除 Cron Trigger 可能需要數分鐘，最長約 15 分鐘，才會傳播到 Cloudflare global network。
- Cloudflare 支援五欄 cron expression 與多數 Quartz-like extensions。
- 星期數字為 `1 = Sunday` 到 `7 = Saturday`；為避免混淆，建議用 `SUN`、`MON` 等三字母縮寫。
- 如果 Worker 由 Wrangler 管理，Cron Triggers 應集中用 Wrangler config 管理。
Wrangler TOML 範例：
```toml
[triggers]
crons = [ "0 23 * * MON-FRI" ]
```
Worker scheduled handler 範例：
```ts
export default {
async scheduled(controller, env, ctx) {
console.log('cron processed')
},
}
```
## 本專案對外教學不能說錯的界線
- Pages 是前端與 Pages Functions 部署平台；有排程需求時，應設計 Worker + Cron Trigger，或使用 Workflows/Queues 做多步或背景任務。
- Direct Upload 與 Git Integration 都是 Pages 可用部署路徑；新手教學可以以 Git Integration 為主，Direct Upload 作為快速驗證。
- Build directory 對 Nuxt on Pages 官方範例是 `dist`；若 Nitro/版本改變輸出資料夾，必須以實際 build log 與 Nuxt/Nitro 文件確認。
- Secrets 不應 commit；Cloudflare Pages / Workers secrets 應透過 Dashboard 或 Wrangler secret 管理，且設定後要 redeploy。
- Preview 與 Production 可能有不同 binding / env；教學與 Checklist 必須要求兩邊確認。
- 官方文件可能更新；產品中所有命令旁邊要保留「最後校對日期」與來源連結。