nwc:用 Rust 写一个 2MB 的局域网剪贴板同步工具
2026.11 · 项目地址:NetWorkClipboard (nwc)
一台 Windows、一台 macOS,来回切换时"这段文字在那台机器上"大概是双机办公最烦人的时刻之一。微信传输助手、网盘中转都太重了——我就想把 Ctrl+C 和 Cmd+V 之间那条缝焊上。
nwc(NetWorkClipboard)就是我焊缝的工具:两台机器各跑一个约 2MB 的二进制,托盘常驻,共享一个口令,之后 Windows 上复制的文字、截图、文件,macOS 上直接粘贴,反之亦然。传输全程 AES-256-GCM 加密。
它有个前身——一个 Node.js 版。这次是用 Rust 从零重写,并且要求和老版本字节级互通。这篇文章记录这次重写的设计取舍和踩过的坑。
先定产品目标,再谈技术
动笔前我先给自己划了三条线,后面所有技术决策都从这三条推出来:
- 单文件、免安装、无运行时——下载解压双击就能用,不要求用户装任何东西
- 托盘常驻——它是基础设施,不是应用,不该有窗口
- 足够小——Windows 端单个 exe 约 2.1MB,常驻私有内存约 1.8MB
第三条最狠。它直接意味着:不能用 Electron/Tauri 之外的任何 GUI 框架——不对,连 Tauri 也不用,两端 UI 全部直接贴系统 API 手写。代价后面细说,收益是整个依赖树薄到 Cargo.lock 只有 21KB,编译产物 strip + LTO + panic=abort 之后压进 2MB。
架构:一个 core,两个壳
Workspace 三个 crate:
crates/
├── nwc-core # 纯逻辑:协议、加密、传输、发现、同步引擎(约 4800 行)
├── nwc-win # Windows 壳:Win32 托盘、剪贴板、设置对话框(约 2400 行)
└── nwc-mac # macOS 壳:AppKit 菜单栏、NSPasteboard(约 1500 行)依赖方向只有一条箭头:nwc-win / nwc-mac → nwc-core。core 不知道托盘长什么样,不知道 Win32 和 AppKit 的存在。它和壳之间只有三条缝隙:
ClipboardWritertrait——壳层把"写剪贴板"的能力注入引擎IfaceProvider回调——壳层负责枚举网卡,core 只做纯逻辑的 CIDR 数学- 一对 channel——壳发
EngineCmd(剪贴板变化、暂停/恢复、退出……),引擎回EngineEvent(日志、状态、通知)
同步引擎本体是单线程事件循环:剪贴板事件、对端消息、控制命令全部经同一个 channel 串行处理。对端读线程的事件也通过桥接转投回主循环。单线程听起来"不并发",但对这种状态密集的小型引擎,串行化是消灭竞态最便宜的方式——剪贴板同步的 bug 十有八九出在"两边同时写"的时序上,架构上直接不给它发生的机会。
发现对端:为什么不用 UDP 广播
局域网找对端,常规答案是 UDP 广播或 mDNS。我都没用,用的是看起来最"笨"的方案:
枚举本机网卡 → 展开所在网段 → 256 并发 TCP connect 探测 8767 端口,连上即命中。
原因有三:
- mDNS/组播在 macOS 14+ 上要过"本地网络权限"弹窗,还要处理各种组播被路由器/防火墙吞掉的环境,水很深
- TCP connect 探测天然幂等、无状态,扫一个 /24 网段 300ms 超时,体感是秒级
- 老 Node 版就是这么做的,Rust 版要保持行为一致
笨方案也有笨方案的坑。比如虚拟网卡过滤:WSL、Docker、Hyper-V、VMware、Tailscale、WireGuard……这些虚拟网段里扫不到对端还浪费时间,core 里维护了一份正则清单统一过滤,连中文的"蓝牙""回环"都在里面。
最有趣的是 198.18.0.0/15 这个网段——RFC 的基准测试保留段,如今被 Clash / Mihomo 等的 fake-IP TUN 模式拿来做虚拟地址池。对着这类网卡探测任何端口都会"命中",导致误判找到了对端。老 Node 版同样中招,这次直接把整个网段拉黑。
角色协商也是自动的,一图胜千言:
两端同时启动,最终总是一听一连,不需要用户理解"服务端/客户端"。
协议与加密:PSK 模型够用了
传输是 TCP 长连接,两阶段:
第一阶段,明文握手(紧凑 JSON 一行):
{"t":"hello","magic":"NWC1","ver":1,"nodeId":"...","name":"...","salt":"<base64>"}交换的东西:版本、设备 ID、双方各自随机生成的 16 字节盐、能力协商(比如 fileChunk 表示支持分块传输)。服务端正忙就回一条 busy,客户端静默退避。
第二阶段,加密帧。口令 + 双方盐拼接,经 scrypt(N=16384, r=8, p=1)派生 256 位密钥;之后每一帧:
[4B 长度][12B IV][16B GCM tag][密文]认证是隐式的:密钥建立后客户端发一条加密的 auth,服务端能正确解密并回 auth_ok,就证明双方口令一致。GCM 的完整性顺带防了篡改。
有人会问:为什么不上 Noise、不做 ECDH?因为这是局域网 + 双人场景的 PSK(预共享口令)模型——信任建立在"你知道口令"上,中间人攻击的威胁模型里没有它要保护的东西。没有密钥交换,就没有证书、没有指纹确认,两端输同一个口令就完事,这符合"给我妈也能装"的目标。当然,空口令时会明确告警:链路仍然加密,但任何知道端口的人都能连上。
大文件走 256KB 分块流式传输,内存占用恒定,末块校验整文件 sha256。文本上限 2MB、单文件 100MB、单批 500MB——够用,也防失控。
剪贴板:两端机制完全不同,但问题相同
剪贴板同步的真正难点不在读写,在回声抑制:A 复制 → 同步到 B → B 写入剪贴板 → B 的监听器看见了这次写入 → 再同步回 A → ……乒乓死循环。
解法是两道防线:自己写入后记下系统序列号/changeCount,接下来的事件对得上号就吸收;再叠一层内容令牌(文本前缀、图片 sha256)带 TTL 的指纹,序列号被别的程序抢写穿了,内容指纹还能兜底:
目录树同步时还有补发机制——同批文件部分命中回声时必须补发,否则对端目录残缺。
两端的监听机制差异很大:
- Windows:隐藏窗口 +
AddClipboardFormatListener,系统有变化就推WM_CLIPBOARDUPDATE,纯事件驱动,零轮询 - macOS:
NSPasteboard没有通知 API,只能轮询changeCount,400ms 一次,微秒级判断,几乎无感
这里必须吐槽 Node 前身:它在 Windows 上常驻 PowerShell 脚本 60ms 轮询,macOS 上每 400ms spawn 四到六个 osascript/pbpaste/sips 子进程。Rust 版 Windows 端零轮询、macOS 端零子进程——这也是这次重写最直接的动机之一。
图片是格式地狱。Windows 截图放进剪贴板的是 DIB 位图,要转 PNG 才能跨平台;反过来写入时要 PNG + CF_DIBV5 双格式挂上,老应用才认。macOS 更讲究:只写 PNG,不少聊天软件和旧应用 Cmd+V 就是空的——必须 public.tiff + public.png + 旧式 PNGf 三格式齐挂,因为 TIFF 才是 AppKit 世界"粘贴图片"的事实标准。这些格式互转(DIB 的 24/32bpp、BI_BITFIELDS、自底向上行序……)全在 core 里手写了 340 行,没有引图像库。
三个"从未真机验证"的 bug
这是整个项目最疼也最值钱的一段。
v0.1 发出去之后真机一跑,三个 bug 现形,每一个都属同一种病:平台集成层,编译通过 ≠ 能跑。
Bug 1:Windows→macOS 的图片,从第一版起就没成功过。 DIB 位图头的 biBitCount 字段是 16 位 WORD,我按 32 位 DWORD 去读,从偏移 16 读出来的是 16/20/36,而真实值在偏移 14——字段整体错位两字节。结果就是 Win+Shift+S 的截图(32bpp BI_BITFIELDS)被误判成"3bpp 未知压缩"拒收。单元测试的用例恰好没覆盖这个组合,一切绿灯。
Bug 2:macOS 的 TIFF→PNG 转换,同样从未工作过。 给 ImageIO 传目标 UTI 时,我把 NSString 的内容当成裸 UTF-16 数组传了进去——那根本不是 CF 对象,CoreFoundation 内部 __CF_IS_OBJC 断言直接崩溃。正确做法是利用 NSString 与 CFStringRef 的 toll-free bridge,直接传对象指针。
Bug 3:退出卡死。 Shutdown 被设计成一次性命令,结果在某个会话循环里被消费掉之后,外层循环永远等不到它,进程挂在那不退。
三个 bug 修完,我做了一件比修复更重要的事:测试金字塔。单元测试(DIB 编解码、协议字节、加密)、平台真机测试(真实剪贴板读写、托盘生命周期)、双引擎端到端测试(两个引擎实例对跑完整同步流),全部铺进三平台 CI。平台集成是这个项目最大的风险面,那就用制度把它锁住,而不是靠下次记得。
顺带一提,重写还抓出了老 Node 版的一个 bug:--scan-interval 参数写进了一个从未被读取的字段。Rust 版修掉并加了回归测试——连前辈的 bug 都要兼容着修,也算是字节级互通的代价与乐趣。
零 GUI 框架:代价与甜头
两端 UI 都是"裸写":Windows 用 windows crate 直接贴 Win32,托盘 Shell_NotifyIconW、右键菜单 CreatePopupMenu、设置对话框是原生控件按需创建,无常驻窗口;macOS 用 objc2 直接贴 AppKit,define_class! 自定义菜单控制器,纯菜单栏应用不占 Dock。
代价是踩各种教科书级坑:AppKit 坐标系原点在左下角,按直觉排 y 坐标,控件整体倒序;无签名的 app 走不了 UNUserNotification,通知只能 osascript display notification 绕行;托盘图标引用的位图必须存活于图标整个生命周期,创建完就 DeleteObject,系统不保证拷贝——托盘直接变空白,这正是首版图标空白的原因。
甜头是意想不到的。比如托盘图标:五个状态(扫描/监听/已连接/暂停/停止)五种颜色,没有 .ico 资源文件,图标是纯代码画的——源码里就是几组 12x12 的 ASCII 字符画常量,# 是前景像素、. 是透明,套上圆角底色和 1px 描边,启动时现场生成 HICON。状态切换 = 换一组字符画重画,零渲染成本;想改图标,改字符串就行。
macOS 端对应地用 SF Symbol(模板图标自动适配深浅色),一行 NSImage::systemSymbolName 拿来就用。两端谁也没拖一个图标资源文件进仓库。
数字收尾
从 Initial commit 到发布 v0.3.0,前后约两天半,15 个提交,约 9500 行(含测试),连发三个版本。最终产物:
| 指标 | Windows | macOS (arm64) |
|---|---|---|
| 单文件体积 | 2.1MB | 1.7MB |
| 常驻私有内存 | ~1.8MB | — |
| 子进程 | 0(通知除外) | 0(通知除外) |
功能上,文字/图片/文件双向同步、剪贴板历史(重启保留)、收件箱按天清理、已知对端配对(strict 模式拒绝陌生设备)、开机自启、单实例保护,该有的都有了。
还欠的账:macOS 签名与公证(现在首次打开还得右键"打开"绕 Gatekeeper)、同屏只支持 1 对 1 连接、Linux 端还没有。这些是接下来的事——但那是下一篇博客的素材了。