Skip to content
Cloudflare Workers / OpenNext runtime

Subsystem: Cloudflare Workers / OpenNext runtime

View raw
On this page

ตั้งแต่ v0.3.0 (commit f9ef054) แอปถูก build เป็น Cloudflare Worker ด้วย @opennextjs/cloudflare 1.20.x และ Wrangler 4 คู่มือ deploy ทีละขั้นอยู่ที่ DEPLOY.md และ operations/deploy-cloudflare.md หน้านี้อธิบายว่า runtime ประกอบกันอย่างไรและทำไม

ทำไม Cloudflare Workers + OpenNext#

  • แอปเกือบทั้งหมดเป็นหน้า prerendered + API เล็ก ๆ หนึ่งตัว เหมาะกับ edge runtime ที่เสิร์ฟ static ได้เร็วและคิดเงินตามคำขอ
  • Workers มี Rate Limiting API ในตัว (ไม่ต้องสร้าง KV/Redis) ใช้ปกป้อง /api/plan
  • OpenNext แปลงผล build ของ Next.js เป็น Worker ที่รองรับ App Router ได้โดยไม่ต้องเขียน adapter เอง
  • ไม่ผูกกับ Cloudflare: npm run build && npm start ยังรันบน Node ได้ (rate limit ใช้ in-memory)

ไฟล์ config#

ไฟล์ สาระสำคัญ
wrangler.jsonc name: nvx-stack-builder, main: .open-next/worker.js, compatibility_flags: [nodejs_compat, global_fetch_strictly_public], workers_dev: true, preview_urls: false, ไม่มี routes, assets (binding ASSETS), service self-reference WORKER_SELF_REFERENCE, vars (OPENAI_MODEL, OPENAI_MAX_OUTPUT_TOKENS, OPENAI_TIMEOUT_MS), ratelimits (สอง limiter), observability.enabled, upload_source_maps
open-next.config.ts incrementalCache: staticAssetsIncrementalCache เพราะทุกหน้า prerender และไม่มี revalidate ตอน runtime จึงไม่ต้องใช้ R2/KV
cloudflare-env.d.ts ชนิดของ binding (สร้างด้วย npm run cf:typegen)
.dev.vars.example ต้นแบบ .dev.vars สำหรับ npm run preview (ห้าม commit .dev.vars)
public/_headers headers ของ static assets ที่เสิร์ฟตรงจาก .open-next/assets
scripts/patch-opennext.mjs patch ตอน postinstall ให้ adapter inline preview-props.json ของ Next 16.4 (ไม่งั้นทุกคำขอ error Unexpected loadManifest(...preview-props.json)) idempotent และเตือนถ้า pattern เปลี่ยน ลบได้เมื่อ adapter แก้เอง
next.config.ts headers, 404 rewrite, และ initOpenNextCloudflareForDev() ใน dev เพื่อให้ next dev เห็น binding

การทำงานตอนรัน#

  1. คำขอเข้าที่ Worker → ถ้าเป็นไฟล์ใน .open-next/assets (เช่น /_next/static/*, HTML ที่ prerender) เสิร์ฟผ่าน ASSETS
  2. ไม่ใช่ → handler ของ Next (OpenNext) ซึ่งรวมถึง /api/plan
  3. /api/plan เรียก getCloudflareContext().env เพื่อหา rate-limit binding (dynamic import จึงไม่พังนอก Workers)
  4. secret OPENAI_API_KEY และ vars เข้าถึงผ่าน process.env (ด้วย nodejs_compat) แล้วตรวจด้วย serverEnv()

ข้อจำกัดและข้อควรรู้#

  • Wrangler 4 ต้องใช้ Node 22+
  • build ใช้เวลาประมาณ 1 นาที (npx opennextjs-cloudflare build) ผลลัพธ์อยู่ใน .open-next/ (gitignored)
  • npm run preview รันใน workerd จริงที่ http://localhost:8787 ใช้ตรวจภาพและพฤติกรรมให้ตรงกับ production มากกว่า next dev
  • rate-limit counters เป็นต่อ Cloudflare location
  • ห้าม เพิ่ม routes หรือ custom domain จนกว่าจะได้รับอนุมัติตาม custom-domain.md

D1 (ฐานข้อมูล)#

Worker มี binding DB ชี้ D1 nvx-db (ประกาศใน d1_databases ของ wrangler.jsonc พร้อม migrations_dir) ตอนนี้ยังไม่มีโค้ดเรียกใช้ D1 ดู schema ที่ chat-data-model.md และวิธีดูแลที่ d1-database.md ส่วน R2 ยังไม่ได้เปิดใช้

สถานะ deploy ล่าสุด#

Production (v0.6.0) ที่ https://devstack.bid และ www.devstack.bid (Workers Custom Domains, redirect www → apex) บัญชี 2d92bd5b25768fa9093d6adc0a8887fc เวอร์ชันปัจจุบัน 7ddd9404-a31f-4e31-8460-82b3b90c7d0e (ก่อนหน้า 671b6b3b-1074-40cb-84b0-0df2681b69ce v0.5.1) workers.dev สำรอง https://nvx-stack-builder.examplessdk.workers.dev ส่วน deploy เดิม (v0.3.0) ที่ https://nvx-stack-builder.agen-sdk-work.workers.dev บัญชี f70d35188a3c56b9781538c73a86e04e ยังเปิดอยู่และไม่ถูกแก้ไข

Source: docs/architecture/cloudflare-runtime.md · /docs/architecture/cloudflare-runtime.md