js-flipper 使用指南:在 Web 与 Node.js 中通过 WebSocket 连接 Flipper 桌面调试平台

原创2026-09-21 13:23:581,374 阅读
文章标签:开发工具调试器移动开发桌面应用插件系统前端

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...');
  },
});

两个模式值得复用:

  1. 按环境动态加载:用 process.env.NODE_ENV 判断,仅在生产环境之外 import js-flipper,避免调试代码进入线上包;
  2. 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 与桌面端双向通信。

继续深入可参考:

登录后查看全文
flipper