CrossBridge 项目状态报告

更新时间: 2025-04-02 当前版本: 1.0.0

🎯 项目概述

@pt/cross-bridge 是一个高性能、全场景的跨域通信插件。 它旨在解决前端开发中复杂的跨域通信痛点，支持从同域 Tab 到跨一级域名的全场景消息同步。

---

🗺️ 能力地图

1. 通信能力

场景	推荐方案	适配器名称	后端依赖
同域 - 页面嵌套	PostMessage	post-message	无
同域 - 多标签页	SharedWorker	shared-worker	无
同域 - 多标签页 (轻量)	BroadcastChannel	broadcast-channel	无
跨域 - 实时通信 (推荐)	WebSocket	websocket-relay	✅ 需要 (已提供参考)
跨域 - 无后端	Iframe Bridge	iframe-bridge	❌ 无 (仅需静态页)

2. 核心特性

• ✅ 消息零丢失：内置消息队列，支持离线消息缓存，页面上线后自动投递。
• ✅ 数据持久化：支持将重要消息存入 LocalStorage/IndexedDB，刷新不丢失。
• ✅ 智能路由：根据连接状态自动选择最优发送通道。
• ✅ 全生命周期：完整的连接、断开、重连、心跳机制。

---

📂 关键文件结构

packages/cross-bridge/
├── src/
│   ├── core/
│   │   ├── cross-bridge.ts       # 核心主类 (集成队列与存储)
│   │   ├── message-queue.ts      # 消息队列管理器
│   │   └── storage-manager.ts    # 存储管理器
│   ├── adapters/
│   │   ├── websocket-relay.ts    # WebSocket 适配器
│   │   ├── iframe-bridge.ts      # Bridge 适配器
│   │   ├── broadcast-channel.ts  # Broadcast 适配器
│   │   └── ... (其他基础适配器)
│   └── workers/
│       └── cross-bridge-worker.ts # SharedWorker 脚本
├── server/
│   ├── relay-server.ts           # WebSocket 参考服务端 (直接可用)
│   └── bridge.html               # 静态桥接页面 (直接可用)
└── .docs/                        # 完整设计文档

---

🚀 快速启动指南

1. 启动跨域支持 (选择其一)

方案 A: WebSocket 服务 (高性能)

# 安装依赖
npm install ws

# 启动服务
npx ts-node server/relay-server.ts
# 服务运行在 ws://localhost:8080

方案 B: 静态桥接页 (无后端) 将 server/bridge.html 部署到你的 CDN 或静态服务器上。

https://your-cdn.com/bridge.html

2. 客户端调用

import { CrossBridge } from '@pt/cross-bridge';

const bridge = new CrossBridge({
  pageId: 'my-app',
  role: 'parent',
  // 同时支持多种模式
  adapters: [
    'shared-worker', 
    'post-message',
    {
        type: 'websocket-relay',
        config: { relayServer: 'ws://localhost:8080' }
    }
  ],
  // 开启消息队列（默认开启）
  queue: {
    maxQueueSize: 500
  }
});

await bridge.connect();

---

📝 待扩展功能 (Future)

1. WebRTC P2P: 适用于超大数据流传输。
2. 性能优化: 消息批量发送与压缩算法。