js-flipper 使用指南:在 Web 与 Node.js 中通过 WebSocket 连接 Flipper 桌面调试平台
js-flipper 使用指南:在 Web 与 Node.js 中通过 WebSocket 连接 Flipper 桌面调试平台
js-flipper 是 Flipper 官方提供的 JavaScript 客户端绑定,它让运行在浏览器或 Node.js 环境中的应用可以绕过原生客户端(Android/iOS),直接通过 WebSocket 与 Flipper 桌面端建立连接并注册调试插件。阅读本文后,你将掌握 js-flipper 的安装方式、flipperClient 的完整 API(addPlugin / start / stop / sendData)、FlipperClientOptions 各配置项的底层作用,以及如何在 Web 与 Node.js 两种环境下写出可运行的 Flipper 客户端插件。
一、js-flipper 是什么:一段面向 Web / Node.js 的 Flipper 连接通道
Flipper 是一套面向移动开发者的桌面调试平台,其插件体系由两部分组成:运行在 Flipper 桌面端(Electron)的 Desktop 插件,以及运行在"设备"上的客户端插件。传统上,"设备"指 Android / iOS 真机或模拟器;而 js-flipper 包(package.json 中描述为 "Flipper bindings for Node.js and web")把"设备"扩展到了网页与 Node.js 进程:
- 在浏览器中,它直接复用标准 WebSocket API;
- 在 Node.js 中,由于运行时没有内置 WebSocket,它允许你通过
websocketFactory注入任意与浏览器 WebSocket 接口兼容的实现(如ws库)。
从仓库结构看,js/js-flipper/src/index.ts 中 export const flipperClient = new FlipperClient() 即文档所述的 flipperClient 单例;js/js-flipper/package.json 通过 browser: {"os": false} 字段将 os 模块在浏览器构建中置空,确保同一份代码可以在两种环境下打包运行。
二、安装
在项目中使用 yarn 安装:
yarn add js-flipper
安装后即可获得两个入口能力(均来自 src/index.ts):
- 默认导出的
flipperClient单例(FlipperClient类的实例); FlipperPlugin、FlipperClientOptions、FlipperWebSocket等相关类型与常量。
三、快速上手:插件生命周期与两个核心方法
构建 Flipper 插件的完整流程在官方 Flipper 文档中有说明:你需要同时开发"Flipper 桌面端插件"与"运行在设备(Web / Node.js)上的插件",而 js-flipper 只负责设备端通过 WebSocket 与桌面端通信的那一部分。flipperClient 提供了两个核心方法:
3.1 addPlugin(plugin):注册客户端插件
addPlugin 接受一个符合 FlipperPlugin 接口的对象,注册后,当 Flipper 桌面端选中对应插件时,相关回调会被触发。接口定义位于 src/plugin.ts:
export interface FlipperPlugin {
getId(): string; // 插件 ID,必须与 Desktop 插件 id 一致,作为消息路由的命名空间
onConnect(connection: FlipperPluginConnection): void; // 连接建立时回调,connection 直到 onDisconnect 前有效
onDisconnect(): void; // 连接失效回调,此后不应再使用 connection
runInBackground?(): boolean; // 可选:是否在后台运行(用于 getBackgroundPlugins 判定)
}
在 src/client.ts 的实现中,addPlugin 会把插件存入内部 Map,并且如果当前已连接,会立即发送 refreshPlugins 消息通知桌面端插件列表已更新——这正是"运行时动态增删插件"得以生效的机制。
FlipperPluginConnection 同样定义在 src/plugin.ts,是插件与桌面端通信的唯一入口:
export interface FlipperPluginConnection {
send(method: string, params?: unknown): void; // 向 Flipper 发送 execute 消息
receive(method: string, receiver: FlipperPluginReceiver): void; // 监听桌面端下发的消息并回调
}
其中 receive 的回调语义值得注意(connection.ts 中 wrappedReceiver 的封装):
- 回调同步返回任意值(包括
undefined),会作为成功结果发回桌面端; - 回调返回 Promise,则以 resolve 的值作为成功结果发回;
- 回调抛异常或返回 rejected Promise,则自动构造
{name, message, stacktrace}形式的错误消息发回桌面端。
3.2 start(appName, options?):建立连接
start 启动客户端,其签名与全部选项定义于 src/client.ts 和 src/client.ts:
interface FlipperClientOptions {
// Make the client connect to a different URL
urlBase?: string;
// Override WebSocket implementation (Node.js folks, it is for you!)
websocketFactory?: (url: string) => FlipperWebSocket;
// Override how errors are handled (it is simple `console.error` by default)
onError?: (e: unknown) => void;
// Timeout after which client tries to reconnect to Flipper
reconnectTimeout?: number;
// Set device ID. Default: random ID persisted to local storage.
getDeviceId?: () => Promise<string> | string;
}
各参数的作用与源码实现如下:
| 参数 | 默认值 | 作用与源码依据 |
|---|---|---|
appName(必填) |
无 | 显示在 Flipper 桌面端应用列表中的应用名,会拼入连接 URL 的 app 参数(client.ts) |
urlBase |
'localhost:8333' |
Flipper 服务地址(不含协议前缀),最终拼成 ws://${urlBase}?... 的连接串(client.ts) |
websocketFactory |
(url) => new WebSocket(url) |
覆盖 WebSocket 实现。Node.js 环境必须注入第三方实现(见下文"Node.js 接入") |
onError |
console.error('WebSocket error', e) |
统一错误回调。WebSocket 错误、消息解析失败、插件回调异常都会走这里(client.ts) |
reconnectTimeout |
1000(毫秒,见 consts.ts) |
断线后重连的等待时长。onclose 事件中只有关闭码不是 1000(NormalClosure)或 1001(GoingAway)才会触发重连(client.ts) |
getDeviceId |
随机 ID 并持久化到 localStorage(key 为 js-flipper-device-id) |
用于在 URL 中标识设备。默认实现见 util.ts;Node.js 下 localStorage 不存在,会退化为每次生成新 ID |
start 返回一个 Promise,在 WebSocket 首次 onopen 时才 resolve(client.ts),因此可以用 await flipperClient.start(...) 确保连接就绪后再进行插件操作。
3.3 连接握手与 URL 构成
connectToFlipper(client.ts)展示了实际发出的连接请求:
const url = `ws://${this.urlBase}?device_id=${this.device}${this.deviceId}&device=${this.device}&app=${this.appName}&os=${this.os}`;
const encodedUrl = encodeURI(url);
URL 查询参数含义:
device_id:getDeviceId()的返回值;device:设备标识。浏览器下为window.navigator.userAgent,Node.js 下为require('os').release()(util.ts);app:start传入的appName;os:操作系统,取值iOS / Android / Metro / Windows / MacOS / Browser / Linux。浏览器环境固定为Browser,Node.js 下通过os.type()判定(util.ts)。
3.4 断开与停止:stop()
client.ts 中的 stop() 会清除重连定时器、以关闭码 1000 主动关闭 WebSocket,并对所有已注册插件逐个调用 onDisconnect()。注意:stop() 之后 addPlugin 注册的插件仍然保留在内存中,再次 start 即可恢复连接。
四、示例(Web):React 中的 Tic-Tac-Toe 客户端插件
官方示例是 React 版井字棋,对应源码为 js/react-flipper-example/src/FlipperTicTacToe.tsx,其桌面端插件默认随 Flipper 内置分发(对应仓库目录 desktop/plugins/rn-tic-tac-toe),因此你只需把 <FlipperTicTacToe /> 组件放进自己的应用即可开箱即用。示例中的关键模式:
// 仅开发/测试环境才启动 Flipper 客户端
let flipperClientPromise: Promise<FlipperClient> | undefined;
if (process.env.NODE_ENV !== 'production') {
flipperClientPromise = import('js-flipper').then(({flipperClient}) => {
flipperClient.start('React Tic-Tac-Toe');
return flipperClient;
});
}
插件注册与消息收发(FlipperTicTacToe.tsx):
flipperClient.addPlugin({
getId() {
return 'ReactNativeTicTacToe'; // 必须与桌面端插件 id 一致
},
onConnect(connection) {
setStatus('Desktop player present');
setConnection(connection);
// 接收桌面端推送的棋盘状态
connection.receive('SetState', (gameState: GameState) => {
setStatus(gameState.winner !== ' ' ? `Winner is ${gameState.winner}!` : '');
setGameState(gameState);
});
// 主动请求初始状态
connection.send('GetState');
},
onDisconnect() {
setConnection(undefined);
setStatus('Desktop player gone...');
},
});
两个模式值得复用:
- 按环境动态加载:用
process.env.NODE_ENV判断,仅在生产环境之外 import js-flipper,避免调试代码进入线上包; - onConnect 内完成一切初始化:注册
receive监听并主动send请求初始数据,onDisconnect中清理状态。
五、Node.js 接入:注入 WebSocket 实现
Node.js 没有内置 WebSocket,需要安装任意与浏览器 WebSocket 接口兼容的实现(如 ws)。README 中的完整示例:
import flipperClient from 'js-flipper';
import WebSocket from 'ws';
// 第二个参数 origin 必不可少:
// Flipper 桌面端会校验每个 WS 连接的 Origin 头,必须设置为白名单值之一
// (对应 Flipper 服务端的 VALID_WEB_SOCKET_REQUEST_ORIGIN_PREFIXES)
flipperClient.start('My cool nodejs app', {
websocketFactory: url => new WebSocket(url, {origin: 'localhost:'}),
});
两点源码印证:
FlipperWebSocket接口(client.ts)只要求onclose / onerror / onmessage / onopen / close / send / readyState这些浏览器 WebSocket 的公共子集,因此ws库基本可以直接注入;client.spec.ts 中的测试也是用new WebSocket(url) as unknown as FlipperWebSocket完成注入的;- 关于
origin: 'localhost:':Flipper 服务端对所有 WebSocket 连接的Origin头做白名单校验,Node.js 客户端默认不带该头会被拒绝,所以必须显式传入。这是 Node.js 接入最常见的坑之一。
5.1 测试验证
仓库为客户端编写了完整的单元测试,见 js/js-flipper/src/tests/client.spec.ts,使用真实的 ws WebSocketServer 在随机端口上模拟 Flipper 服务端,覆盖了:
getPlugins:注册插件后返回插件 ID 列表(测试断言返回{plugins: ['42']});- 错误处理:服务端发送畸形消息(如
'{{{')时,onError被调用、连接被关闭并触发重连; - 连接握手(
verifyClient控制是否放行)与消息收发校验。
这些测试直接验证了上文所述的消息协议与重连机制,也是你编写自己的客户端插件时可以参考的联调范本。
六、深入原理:客户端与服务端的消息协议
6.1 消息格式
所有消息经 JSON.stringify 后通过 WebSocket 传输。FlipperClient.sendData(client.ts)是唯一的出口,FlipperRequest 与 FlipperResponse 类型定义在 src/message.ts:
- 请求:
{method, params?},其中execute请求的params形如{api, method, params}; - 响应:
{id, success}或{id, error: {message, name?, stacktrace?}},id与请求一一对应。
6.2 服务端 → 客户端的指令分派
onMessageReceived(client.ts)是客户端的中枢,根据 method 分派:
| 指令 | 客户端行为 |
|---|---|
getPlugins |
返回已注册插件 ID 列表 {plugins: [...]} |
getBackgroundPlugins |
仅返回 runInBackground() 为 true 的插件 |
init |
按 params.plugin 找到插件并调用 onConnect,建立连接 |
deinit |
调用 onDisconnect 并移除连接 |
execute |
按 params.api 找到连接,调用对应 receiver 执行方法 |
isMethodSupported |
返回 {isSupported: connection.hasReceiver(method)} |
每次响应都通过 src/responder.ts 中的 FlipperResponder.success()/error() 构造——它把 id、success 或 error 封装成标准响应消息发出,保证与桌面端的双向契约一致。
6.3 重连与容错
连接断开时(关闭码非 1000/1001),客户端会等待 reconnectTimeout 后重新发起连接(client.ts)。若收到的消息不是合法 JSON,客户端会调用 onError 并以关闭码 1002(InternalError,见 client.ts 中的 WSCloseCode 枚举)主动关闭连接,随后自动触发重连。
七、写在最后
js-flipper 让"任意 Web 应用或 Node.js 进程都能成为 Flipper 的调试客户端"成为现实:浏览器端零配置接入,Node.js 端只需注入一个 WebSocket 实现并正确处理 Origin 头。无论你的场景是 React 应用调试、服务端进程观测,还是自定义设备插件,核心工作流都是一致的——start() 建立连接、addPlugin() 注册插件、onConnect 中通过 send/receive 与桌面端双向通信。
继续深入可参考: