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

js-flipper 使用指南在 Web 与 Node.js 中通过 WebSocket 连接 Flipper 桌面调试平台【免费下载链接】flipperA desktop debugging platform for mobile developers.项目地址: https://gitcode.com/gh_mirrors/fli/flipperjs-flipper 是 Flipper 官方提供的 JavaScript 客户端绑定它让运行在浏览器或 Node.js 环境中的应用可以绕过原生客户端Android/iOS直接通过 WebSocket 与 Flipper 桌面端建立连接并注册调试插件。阅读本文后你将掌握 js-flipper 的安装方式、flipperClient的完整 APIaddPlugin/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.1addPlugin(plugin)注册客户端插件addPlugin接受一个符合FlipperPlugin接口的对象注册后当 Flipper 桌面端选中对应插件时相关回调会被触发。接口定义位于 src/plugin.tsexport 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.2start(appName, options?)建立连接start启动客户端其签名与全部选项定义于 src/client.ts 和 src/client.tsinterface 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?: () Promisestring | string; }各参数的作用与源码实现如下参数默认值作用与源码依据appName必填无显示在 Flipper 桌面端应用列表中的应用名会拼入连接 URL 的app参数client.tsurlBaselocalhost:8333Flipper 服务地址不含协议前缀最终拼成ws://${urlBase}?...的连接串client.tswebsocketFactory(url) new WebSocket(url)覆盖 WebSocket 实现。Node.js 环境必须注入第三方实现见下文Node.js 接入onErrorconsole.error(WebSocket error, e)统一错误回调。WebSocket 错误、消息解析失败、插件回调异常都会走这里client.tsreconnectTimeout1000毫秒见 consts.ts断线后重连的等待时长。onclose事件中只有关闭码不是1000NormalClosure或1001GoingAway才会触发重连client.tsgetDeviceId随机 ID 并持久化到localStoragekey 为js-flipper-device-id用于在 URL 中标识设备。默认实现见 util.tsNode.js 下localStorage不存在会退化为每次生成新 IDstart返回一个 Promise在 WebSocket 首次onopen时才 resolveclient.ts因此可以用await flipperClient.start(...)确保连接就绪后再进行插件操作。3.3 连接握手与 URL 构成connectToFlipperclient.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_idgetDeviceId()的返回值device设备标识。浏览器下为window.navigator.userAgentNode.js 下为require(os).release()util.tsappstart传入的appNameos操作系统取值iOS / Android / Metro / Windows / MacOS / Browser / Linux。浏览器环境固定为BrowserNode.js 下通过os.type()判定util.ts。3.4 断开与停止stop()client.ts 中的stop()会清除重连定时器、以关闭码1000主动关闭 WebSocket并对所有已注册插件逐个调用onDisconnect()。注意stop()之后addPlugin注册的插件仍然保留在内存中再次start即可恢复连接。四、示例WebReact 中的 Tic-Tac-Toe 客户端插件官方示例是 React 版井字棋对应源码为 js/react-flipper-example/src/FlipperTicTacToe.tsx其桌面端插件默认随 Flipper 内置分发对应仓库目录 desktop/plugins/rn-tic-tac-toe因此你只需把FlipperTicTacToe /组件放进自己的应用即可开箱即用。示例中的关键模式// 仅开发/测试环境才启动 Flipper 客户端 let flipperClientPromise: PromiseFlipperClient | undefined; if (process.env.NODE_ENV ! production) { flipperClientPromise import(js-flipper).then(({flipperClient}) { flipperClient.start(React Tic-Tac-Toe); return flipperClient; }); }插件注册与消息收发FlipperTicTacToe.tsxflipperClient.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使用真实的wsWebSocketServer 在随机端口上模拟 Flipper 服务端覆盖了getPlugins注册插件后返回插件 ID 列表测试断言返回{plugins: [42]}错误处理服务端发送畸形消息如{{{时onError被调用、连接被关闭并触发重连连接握手verifyClient控制是否放行与消息收发校验。这些测试直接验证了上文所述的消息协议与重连机制也是你编写自己的客户端插件时可以参考的联调范本。六、深入原理客户端与服务端的消息协议6.1 消息格式所有消息经JSON.stringify后通过 WebSocket 传输。FlipperClient.sendDataclient.ts是唯一的出口FlipperRequest与FlipperResponse类型定义在 src/message.ts请求{method, params?}其中execute请求的params形如{api, method, params}响应{id, success}或{id, error: {message, name?, stacktrace?}}id与请求一一对应。6.2 服务端 → 客户端的指令分派onMessageReceivedclient.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并以关闭码1002InternalError见 client.ts 中的WSCloseCode枚举主动关闭连接随后自动触发重连。七、写在最后js-flipper 让任意 Web 应用或 Node.js 进程都能成为 Flipper 的调试客户端成为现实浏览器端零配置接入Node.js 端只需注入一个 WebSocket 实现并正确处理Origin头。无论你的场景是 React 应用调试、服务端进程观测还是自定义设备插件核心工作流都是一致的——start()建立连接、addPlugin()注册插件、onConnect中通过send/receive与桌面端双向通信。继续深入可参考插件接口定义js/js-flipper/src/plugin.ts客户端核心实现js/js-flipper/src/client.ts连接与响应实现js/js-flipper/src/connection.ts、js/js-flipper/src/responder.ts单元测试js/js-flipper/src/tests/client.spec.tsReact 示例插件js/react-flipper-example/src/FlipperTicTacToe.tsx【免费下载链接】flipperA desktop debugging platform for mobile developers.项目地址: https://gitcode.com/gh_mirrors/fli/flipper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考