故障排查
连不上、同步不生效、后台被系统限制等常见问题的排查。
这一页按「症状 → 排查」组织。移动 App 是纯局域网 / 自建服务器的同步客户端， 它连接的是一台运行 UniClipboard 桌面端并开启了「手机同步」 的电脑；两台 手机之间不互相同步，都各自跟桌面通信。排查时先记住这个结构：多数问题要么出在 这台电脑、要么出在 手机与电脑之间的网络、要么出在 系统权限。
连不上服务器
「测试连接」失败、卡在「正在连接」、或历史一直拉不下来，通常是下面三类之一。
| 症状 | 原因 | 怎么办 |
|---|---|---|
| 地址不可达 / 连接超时 | 桌面没开监听、手机和电脑不在同一 Wi-Fi、或地址端口填错 | 确认电脑上 UniClipboard 桌面端已开启手机同步；确认手机与电脑连的是同一个 Wi-Fi；核对服务器地址和端口 |
| 鉴权失败 / 提示未授权 | 用户名或密码错 | 核对凭据；密码只在桌面添加设备时显示一次，忘了就在桌面轮换密码后重新填 |
| 提示证书错误 | 桌面走的是自签名 HTTPS | 在该服务器的「允许不安全证书」开关打开；纯 HTTP 不需要开这个 |
排查要点：
- 如果你在连接表单里填了多条地址（局域网 / Tailscale / 公网），App 会按 当前网络自动择优，界面会标注「将使用」哪条地址。连不上时先看它选中的是不是 你以为的那条。
- 拿到凭据、开启桌面手机同步的完整步骤在桌面侧文档： 移动端同步 和 配对与同步。
- 想跨网络（4G/5G 或在外面）访问，需要自建可公网访问的 server 节点，见 自建无头 server 节点。
下行不写入：远端内容没进系统剪贴板
桌面复制了东西，手机历史里也看到了，但粘贴时粘不出来、系统剪贴板还是旧内容。
- iOS 上「自动写入本机剪贴板」是一个独立开关（设置 → 同步）。关掉它之后， 远端内容只会在主页高亮显示，不会覆盖系统剪贴板。想让它自动进剪贴板， 把这个开关打开。
- 实时推送（SSE）需要桌面服务端支持。服务端不支持时，App 不会自动回退到 轮询，下行会明显变慢或不实时。可以手动下拉刷新，或在主界面用「立即同步」。
- Android 后台自动写入依赖后台读取方式已就绪（定时轮询 / ADB 事件 / Shizuku 任选其一），详见 Android 后台访问。
- 实时推送（SSE）需要桌面服务端支持；不支持时不会自动回退轮询，可调大 / 调小 轮询间隔或手动「立即同步」。
上行不生效：本机内容推不上去
在手机上复制或上传了内容，但桌面收不到，卡片右下角的时钟图标（待上传 / 待同步）一直不消失。
iOS 读系统剪贴板需要一次性授权。到 设置 → 扩展与权限 → 剪贴板访问， 触发一次「从其他 App 粘贴」授权。没授权时 App 读不到系统剪贴板，自然也推不上去。
如果你用的是分享或键盘扩展推内容，确认扩展本身已配置好，见 iOS 扩展。
后台上传要求后台读取方式已就绪：定时轮询和 ADB 事件都需要悬浮窗权限，ADB 事件还要 READ_LOGS， 或改用 Shizuku 方式。只要方式没配好，App 不在前台时就推不上去。完整配置见 Android 后台访问。
前台时可以直接用右下「添加」里的「上传剪贴板」或「立即同步」手动推一次， 先确认是不是纯后台问题。
时钟图标只表示「还没推成功」——内容已经安全落在本地历史里，后台上传管理器会按 退避策略重试。连上桌面后通常会自动补推。
后台被系统杀
App 切到后台一段时间后就不再同步、常驻通知消失、或再打开时像被冷启动。这是系统 的电池 / 后台限制，不是同步本身坏了。
- 到 设置 → 后台运行，打开总开关「后台自动同步」，它会依次引导你忽略电池 优化、开通知权限、开悬浮窗权限。
- 打开常驻通知（后台运行高级项），让系统更不容易回收 App。
- MIUI / 澎湃等厂商系统有额外的后台限制。用 Shizuku 方式还能关掉 MIUI 的 「智能剪贴板」限制，见 Android 后台访问。
- 电池优化的授权弹窗通常每次安装只弹一次。错过了就手动去系统设置里把 UniClipboard 加进不受电池优化限制的名单。
iOS 在锁屏 / 切后台后同样会限制剪贴板读写，这是系统行为。需要稳定后台同步时， 把 App 留在前台，或用键盘 / 分享扩展在需要时主动触发。
iOS 扩展读到空配置
键盘或分享扩展提示「尚未配置服务器」，但主 App 里明明连着桌面。
- 键盘扩展必须开**「允许完全访问」**：系统设置 → 通用 → 键盘 → 键盘 → UniClip Keyboard → 允许完全访问。没开完全访问，键盘读不到剪贴板、也连不上服务器。
- App 内 设置 → 键盘 的状态（未添加 / 已添加 / 就绪）靠打开一次键盘上报 心跳来刷新。刚添加完先切到任意输入框把键盘调出来用一次，状态才会更新。
- 完整的扩展启用步骤见 iOS 扩展。
Android 权限
Android 侧多数「功能不生效」最后都落在某个没给的权限上。
| 权限 | 用途 | 怎么给 |
|---|---|---|
| READ_LOGS | 「复制即自动同步」的事件监听（ADB 事件方式） | 应用内无法申请，只能用电脑执行 adb 命令授予；App 会把命令复制到剪贴板方便你粘贴，授予后需重启 App |
| 悬浮窗（SYSTEM_ALERT_WINDOW） | 后台读 / 写剪贴板 | 手动在系统设置里开启；设置 → 后台运行的引导会带你去 |
| 短信权限 | 短信验证码自动转发 | 在设置 → 短信转发里按引导授予 |
| 相机权限 | 扫码连接 | 首次扫码时授予；被永久拒绝后去系统设置开启，或改用「手动填写」连接 |
READ_LOGS 的 adb 命令形如：
adb shell pm grant <应用包名> android.permission.READ_LOGSREAD_LOGS 只有「ADB 事件」方式才需要。如果你不想碰电脑，直接用默认的「定时轮询」 即可——它靠定时轮询感知复制，无需 READ_LOGS，只是实时性和省电略逊。三种后台读取方式 （定时轮询 / ADB 事件 / Shizuku）的取舍见 Android 后台访问。
想自己写第三方客户端，或需要排查协议层（HTTP 请求 / 响应、鉴权、字段格式）的 问题，去看 移动端 LAN API。本手册只覆盖 App 里 看得到、点得到的东西，不涉及协议内幕。