RivetKit JavaScript 客戶端

當你建立 JavaScript 客戶端（瀏覽器、Node.js 或 Bun）並使用 rivetkit/client 連接 Rivet Actors 時，請使用此技能。

第一步

安裝客戶端（最新版：2.3.3-rc.2）
```
npm install rivetkit@2.3.3-rc.2
```
使用 createClient() 建立客戶端，並呼叫 actor 的動作。

錯誤處理原則

預設採用快速失敗（fail-fast）行為。
除非絕對必要，否則避免使用 try/catch。
如果使用了 catch，請明確處理錯誤，至少記錄下來。

開始使用

請參閱後端快速入門指南以開始使用。

最小客戶端

無狀態 vs 有狀態

取得 Actors

連線參數

使用 params 設定靜態連線參數。當值可能在連線嘗試之間變動時（例如每次 .connect() 或重新連線前重新整理 JWT），請使用 getParams。

訂閱事件

連線生命週期

低階 HTTP 與 WebSocket

對於實作了 onRequest 或 onWebSocket 的 actor，可以直接呼叫它們：

import { createClient } from "rivetkit/client";

const client = createClient();
const handle = client.chatRoom.getOrCreate(["general"]);

const response = await handle.fetch("history");
const history = await response.json();

const ws = await handle.webSocket("stream");
ws.addEventListener("message", (event) => {
  console.log("message:", event.data);
});
ws.send("hello");

從後端呼叫

錯誤處理

概念

鍵值（Keys）

鍵值唯一識別 actor 實例。使用複合鍵（陣列）來實現階層式定址：

當 userId 包含使用者資料時，不要使用字串插值（如 "org:${userId}"）來建立鍵值。請改用陣列以防止鍵值注入攻擊。

環境變數

createClient() 會自動讀取：

RIVET_ENDPOINT（端點）
RIVET_NAMESPACE
RIVET_TOKEN
RIVET_RUNNER

若未設定，預設為 http://localhost:6420。RivetKit 預設執行於 6420 埠。

端點格式

端點支援 URL 認證語法：

https://namespace:token@api.rivet.dev

你也可以傳入不含認證資訊的端點，並分別提供 RIVET_NAMESPACE 和 RIVET_TOKEN。對於無伺服器部署，請使用應用程式的 /api/rivet URL。詳情請參閱端點。

進階

跳過就緒等待（Skip Ready Wait）

一般情況下，請求會在閘道器端等待，直到 actor 準備好接收流量。Actor 在啟動期間（onWake 完成前）或處於休眠寬限期（執行 onSleep、waitUntil 及待處理的斷線）時，尚未就緒。

在低階 HTTP 與 WebSocket API 上傳遞 skipReadyWait: true，即可立即傳送請求並在以下兩種情況下到達 actor 的 onRequest / onWebSocket 處理器：

import { createClient } from "rivetkit/client";

const client = createClient();
const handle = client.chatRoom.getOrCreate(["general"]);

const response = await handle.fetch("/healthz", {
  skipReadyWait: true,
});

const ws = await handle.webSocket("probe", undefined, {
  skipReadyWait: true,
});

請求仍可能回傳暫時性的生命週期或閘道器錯誤。請在 actor 再次可用時重試。

actor.stopping：actor 已完全停止，即休眠寬限期已結束但尚未重新啟動。
guard.actor_stopped_while_waiting：請求已到達 actor 通道，但 actor 在閘道器收到回應前停止。
guard.tunnel_request_aborted：actor 通道在回應開始前中止了請求。
guard.tunnel_message_timeout：閘道器在其通道訊息逾時後，丟棄了進行中的通道請求。
guard.tunnel_response_closed：actor 通道在發送回應前關閉。
guard.gateway_response_start_timeout：閘道器等待 actor 回應開始時逾時。

API 參考

套件： rivetkit

請參閱 RivetKit 客戶端總覽。

createClient - 建立客戶端
Client - 客戶端型別

需要更多客戶端以外的功能？

如果你需要更多關於 Rivet Actors、註冊表或伺服器端 RivetKit 的資訊，請加入主要技能：

npx skills add rivet-dev/skills

然後使用 rivetkit 技能取得後端指引。

rivetkit-client-javascript

相關技能