个人项目[ez-app]：拾光工具集，让 Android 和 macOS 的剪切板同步起来

🚀 ez-app - 拾光工具集，跨设备剪切板同步

这是一个憋了很久终于整理出来的项目。起因是两个日常痛点：一是我日常是 Android 手机 + Mac 双持，经常在手机上复制个验证码、链接或者一段文字，想粘贴到电脑上，来回折腾微信文件传输助手实在烦不胜烦；二是 Android 手机上竟然没有原生的"扫一扫"，临时扫个码还得打开微信——有时候就是不想用微信的扫码。于是自己动手写了一套——这就是 ez-app，一个面向 Android 与 macOS 的轻量工具集合。

它不是一个单一应用，而是一个 monorepo，里面住了三个能用的东西：Android 工具箱、Android 输入法、macOS 菜单栏应用，三端围绕两个核心能力——剪切板同步和扫码。

🧩 项目组成

应用	平台	主要能力
拾光工具箱	Android	扫码、网络诊断、剪切板同步、快捷设置入口
拾光输入法	Android	基于 fcitx5-android 改造，输入的同时监听并同步剪切板
拾光菜单栏应用	macOS	剪切板监听、同步状态、历史与收藏

三个应用共享同一套剪切板同步协议，名字都带"拾光"，算是凑成了一套"拾光三件套"。

其中扫码值得单独说一句：Android 没有系统级的"扫一扫"，工具箱里内置的扫码器就是为了解决"临时扫个码还得开微信"这个别扭——打开即扫，扫完即走。

✨ 核心特性：剪切板怎么同步

这是整个项目的灵魂，设计上主要考虑了三点：

1. 局域网优先，MQTT 兜底

• 同一局域网内，三端自动发现并直连同步，延迟低、不经过服务器；
• 局域网不可用（比如手机切了流量）时，自动回退到 MQTT over TLS 中转；
• 局域网恢复后自动停掉 MQTT 通道切回直连。整个过程无感，不用手动切换。

2. 端到端加密

三端使用同一个 MQTT 用户名作为频道标识，剪切板内容在发送前用 AES-GCM 加密，服务器只负责转发，看不到明文。MQTT 默认服务器是阿里云的 emqxsl 实例，三端都可以在设置里改成自己的。

3. 历史与收藏

• 同步策略采用"时间较新的内容优先"；
• macOS 端有历史面板，收藏项置顶且不占用普通历史 100 条的上限；
• 对我来说最实用的场景就是：手机复制 → Mac 菜单栏点开历史 → 粘贴，验证码、链接秒到。

🛠️ 技术栈

• macOS 菜单栏应用：Swift，轻量无依赖
• Android 工具箱：Kotlin
• 输入法：基于 fcitx5-android 源码改造（上游许可证保留）
• 构建/发布：GitHub Actions 自动打包，推 v* 标签自动生成 Release

📝 下载与使用

最简单的方式：直接去 GitHub Releases 下载对应平台的安装包——Android APK 已签名，macOS 应用也在 Release 中提供，下载即用，不需要自己编译。

三端各自的"远程同步设置"里配置相同的 MQTT 地址、端口、用户名和密码即可互通。macOS 端配置保存在 ~/.ez-clipboard/config.json。

⚠️ Android 10+ 的剪切板限制

这里要坦诚说明一个平台限制：Android 10 起，系统不允许后台应用读取剪切板。所以：

• 不装输入法的话，工具箱只能手动触发同步；
• 启用拾光输入法后，可以在输入法进程存活且系统允许时自动监听剪切板。

这也是为什么我要把输入法拉进来——它是 Android 上少数能在前台合法读剪切板的入口，等于给同步能力找了个"常驻载体"。

🔗 项目地址

GitHub: https://github.com/erguotou520/ez-app

安全设计（密钥管理、签名证书处理等）在仓库 README 里有详细说明：仓库只保存构建逻辑和公钥信息，keystore 与密码全部走 Actions Secrets。

🌟 结语

这个项目目前主要服务于我自己和"受同样折腾"的双持用户，功能不算花哨，但剪切板同步这件事，解决的是每天都要遇到几十次的高频痛点。后续 file-provider 那块还会继续迭代，如果你也在 Android + macOS 之间来回倒腾内容，欢迎试用反馈。