AI Skills
rivetkit-client-javascript

rivetkit-client-javascript

RivetKit JavaScript 客户端指南。适用于使用 rivetkit/client 连接到 Rivet Actor 的浏览器、Node.js 或 Bun 客户端，用于创建客户端、调用操作或管理连接。

16Star
6Fork
更新于 2026/7/13
获取 Skill源代码

相关 Skills

fastapi10万image-generation7.8万zustand8.1万
SKILL.md
readonly只读
name
rivetkit-client-javascript
description

RivetKit JavaScript 客户端指南。适用于使用 rivetkit/client 连接到 Rivet Actor 的浏览器、Node.js 或 Bun 客户端，用于创建客户端、调用操作或管理连接。

RivetKit JavaScript 客户端

在构建连接到 Rivet Actor 的 JavaScript 客户端（浏览器、Node.js 或 Bun）时，使用此技能，并配合 rivetkit/client。

第一步

  1. 安装客户端（最新版本：2.3.3-rc.2）
    npm install rivetkit@2.3.3-rc.2
  2. 使用 createClient() 创建客户端并调用 Actor 操作。

错误处理策略

  • 默认优先采用快速失败行为。
  • 除非绝对必要，否则避免使用 try/catch。
  • 如果使用了 catch，请显式处理错误，至少记录日志。

快速开始

请参阅后端快速入门指南以开始使用。

最小客户端

无状态与有状态

获取 Actor

连接参数

对于静态连接参数，使用 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");

从后端调用

错误处理

概念

键

键唯一标识 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。详情请参阅端点。

高级

跳过就绪等待

请求通常会在网关处等待，直到 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 客户端概述。

需要更多客户端功能？

如果你需要更多关于 Rivet Actor、注册表或服务器端 RivetKit 的信息，请添加主技能：

npx skills add rivet-dev/skills

然后使用 rivetkit 技能获取后端指导。