架構藍圖：即時聊天室

一個即時聊天室：同一個房間裡的很多人，能「立刻」看到彼此的訊息。我們用 WebSocket（一條持續開啟、雙向的連線），讓伺服器可以主動把新訊息推下來，瀏覽器不必一直重複詢問。

關鍵在於：誰來握住這些開著的連線，並確保房間裡每個人都收到每則訊息？答案是 Durable Object（DO，可譯為「持久物件」）——一個單一、永遠都在的迷你伺服器。我們讓「每個房間」各擁有一個 Durable Object。前面放一個小小的 Worker 負責把每個瀏覽器路由到正確的房間，而 D1（Cloudflare 的 SQL 資料庫）負責保存訊息歷史。

總共有四個角色，每個角色只做一件清楚的事——把職責切乾淨，整個系統才好懂、好維護。

為什麼 Durable Object 天生就是「房間」？因為「相同的房間名稱」永遠會對應到「同一個」單一實例（instance），不管在地球哪個角落都一樣。這個單一實例就成了房間所有連線與狀態唯一的所在——不需要鎖（lock）、不需要訊息中介、也沒有競爭條件（race condition）。

即時訊息是在 Durable Object 的記憶體裡流動；永久的那一份則存在 D1。我們只需要一張資料表 messages，每則聊天訊息一列。room_id 把每則訊息綁回它所屬的房間。

CREATE TABLE IF NOT EXISTS messages (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  room_id    TEXT    NOT NULL,
  user       TEXT    NOT NULL,
  body       TEXT    NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_messages_room
  ON messages (room_id, created_at);

下面是「一則訊息的一生」——從瀏覽器連上線，到 Durable Object 把它廣播給所有人、並存進 D1。

1. 建立專案與一個 D1 資料庫

   先建立一個 Worker，再建立用來存歷史的 D1 資料庫。記下它印出的 database_id——下一步要貼進設定檔。

   bashcontent_copy複製

   npm create cloudflare@latest -- chat-room
   cd chat-room
   npx wrangler d1 create chat-history

2. 設定 wrangler.jsonc

   綁定 Durable Object 類別（ROOMS）、為它登記一個 SQLite migration（遷移），再綁定 D1 資料庫（DB）。migration 是在告訴 Cloudflare：ChatRoom 是一個新的、以 SQLite 儲存的類別。

   jsonccontent_copy複製

   {
     "name": "chat-room",
     "main": "src/index.js",
     "compatibility_date": "2025-01-01",
     "durable_objects": {
       "bindings": [
         { "name": "ROOMS", "class_name": "ChatRoom" }
       ]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] }
     ],
     "d1_databases": [
       { "binding": "DB", "database_name": "chat-history", "database_id": "<your-d1-database-id>" }
     ]
   }

3. 建立 messages 資料表

   把前面「資料模型」那段的 schema.sql 套用到你的 D1 資料庫，讓 messages 資料表先存在，之後才寫得進去。

   bashcontent_copy複製

   npx wrangler d1 execute chat-history --remote --file=./schema.sql

4. 寫 Worker（路由器）

   Worker 只做三件事：確認這是 WebSocket 升級請求、用 env.ROOMS.idFromName(room) 依名稱找到房間的 Durable Object、把請求轉送過去。它也把 ChatRoom 重新匯出（re-export），好讓執行環境找得到這個類別。

   jscontent_copy複製

   import { ChatRoom } from "./chat-room.js";
   export { ChatRoom };
   
   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
       const room = url.searchParams.get("room") || "lobby";
   
       // Only accept WebSocket upgrade requests
       if (request.headers.get("Upgrade") !== "websocket") {
         return new Response("Expected a WebSocket upgrade", { status: 426 });
       }
   
       // Resolve the ONE Durable Object for this room name
       const id = env.ROOMS.idFromName(room);
       const stub = env.ROOMS.get(id);
   
       // Forward the upgrade request to that room object
       return stub.fetch(request);
     },
   };

5. 寫房間 Durable Object

   DO 用 acceptWebSocket 完成 WebSocket 握手（採休眠模式）。每當有訊息進來，webSocketMessage 處理器就會執行：先寫一列到 D1，再把訊息廣播給 getWebSockets() 回傳的每一條連線。

   jscontent_copy複製

   import { DurableObject } from "cloudflare:workers";
   
   export class ChatRoom extends DurableObject {
     constructor(ctx, env) {
       super(ctx, env);
       this.ctx = ctx;
       this.env = env;
     }
   
     // Completes the WebSocket handshake and registers the socket
     async fetch(request) {
       const url = new URL(request.url);
       const room = url.searchParams.get("room") || "lobby";
   
       const pair = new WebSocketPair();
       const client = pair[0];
       const server = pair[1];
   
       // Hibernation: let the runtime hold the socket so the DO can sleep
       this.ctx.acceptWebSocket(server);
       server.serializeAttachment({ room });
   
       return new Response(null, { status: 101, webSocket: client });
     }
   
     // Runs whenever ANY connected client sends a message
     async webSocketMessage(ws, raw) {
       const { user, body } = JSON.parse(raw);
       const { room } = ws.deserializeAttachment();
       const created_at = Date.now();
   
       // 1) Persist to D1 history
       await this.env.DB
         .prepare("INSERT INTO messages (room_id, user, body, created_at) VALUES (?, ?, ?, ?)")
         .bind(room, user, body, created_at)
         .run();
   
       // 2) Broadcast to everyone connected to THIS room
       const payload = JSON.stringify({ user, body, created_at });
       for (const socket of this.ctx.getWebSockets()) {
         socket.send(payload);
       }
     }
   
     async webSocketClose(ws, code, reason, wasClean) {
       ws.close(code, "room closing socket");
     }
   }

6. 從瀏覽器連線

   在前端，用 ?room=lobby 對 Worker 開一條 WebSocket，把每則進來的訊息畫到畫面上，並把使用者輸入的文字以 JSON 送出。正式環境請用 wss://（加密版）。

   htmlcontent_copy複製

   <script>
     const room = "lobby";
     const ws = new WebSocket(`wss://chat-room.example.workers.dev/?room=${room}`);
   
     ws.addEventListener("open", () => console.log("connected to", room));
   
     ws.addEventListener("message", (event) => {
       const msg = JSON.parse(event.data);
       addLine(`${msg.user}: ${msg.body}`); // render into your chat list
     });
   
     // Call this when the user submits the chat box
     function send(user, text) {
       ws.send(JSON.stringify({ user, body: text }));
     }
   </script>

7. 部署

   發佈到 Cloudflare 的網路。你用每一個不同的 ?room= 值連線，都會自動拿到屬於它自己的 Durable Object。

   bashcontent_copy複製

   npx wrangler deploy

容易踩的坑

• 忘了在 Worker 入口檔把 ChatRoom 類別重新匯出（re-export）——執行環境會找不到它。
• 正式環境用 ws:// 而非 wss://；在 HTTPS 頁面上瀏覽器會擋掉不安全的 WebSocket。
• 在 webSocketMessage 裡做太重的工作，卡住廣播——順序維持簡單：先存檔，再廣播。
• 盲目相信訊息內容——寫進 D1 前先驗證 user 與 body。
• 以為 DO 的記憶體會永遠存在——它會休眠，所以請把 D1 當成持久的歷史來源。