# 首次使用排障

本页用于排查首次使用时最常见的失败：**看不到同步内容**、**只能单向同步**、**历史里有记录但粘贴失败**。按下面顺序检查，减少重复试错。

若你**只在一台设备**上验证剪贴历史、尚未做跨端，优先走 [复制与粘贴](/getting-started/first-steps)；本页默认你已在做**两台设备之间**的同步或粘贴验证。

跨端「看不到对方剪贴」时，先在**来源设备**看剪贴历史里有没有这次复制：**没有则多半是「没记下来」**，不要先当成「同步坏了」再改同步方式。手机端常受前后台与系统规则限制；桌面也可对照下面「各端」Tab。想先看短说明可读 [剪贴记录预期](/getting-started/clipboard-record-expectations)；**已经出问题请从本页下文开始排查**。

## 适合谁看

- 已按入门做过跨端或同步测试，但结果不符合预期的用户
- 不确定该先查「网络 / 同步方式」还是「单端权限 / 后台」的用户

## 先判断你的现象

| 现象 | 优先检查 |
|---|---|
| 设备互相看不到新剪贴 | 同步方式是否一致、设备在线状态、网络拦截；**Android/iOS** 对照下一节对应 Tab 是否「未写进历史」；**桌面端**一般先查网络、应用是否被挂起，macOS 再查 [权限](/advanced/macos/permissions) |
| 只有一个方向失败 | 失败方向来源设备的权限与后台状态 |
| 历史中有记录但粘贴失败 | 目标应用粘贴限制、系统粘贴权限 |
| 同步延迟明显 | 网络质量、系统后台限制、是否在省电模式 |

> [!WARNING] 不要混用同步路径
> 一端附近同步、另一端云同步时，常表现为「完全看不到」或极不稳定。请先统一方式，再跑下方「按顺序检查」。

## 各端：后台监听与「像同步坏了」

跨端看不到新剪贴时，先确认**来源端有没有把这次复制写进剪贴历史**。若历史里根本没有，另一端同步也「等不到」——不一定是同步方式选错。下面按平台拆开看（和 [剪贴板后台监听](/features/source/background-monitoring/) 专题一致，用 Tab 方便你只读常用端）。

:::tabs
:::tab{label="桌面（Windows / macOS）"}

剪贴板后台相关能力在**正常安装与运行**下通常默认可用，首次排障里**较少**出现「必须打开应用主界面才把复制写进历史」这类问题。若来源端是桌面却仍像「没同步」，多数仍应先按上文顺序查同步方式、网络与在线状态。

**macOS** 若涉及自动粘贴、输入监控或隐私弹窗，再对照 [macOS 权限说明](/advanced/macos/permissions) 与 [跨平台差异](/advanced/platform-differences)。需要对照机制时读 [剪贴板后台监听](/features/source/background-monitoring/)。

:::
:::tab{label="Android"}

**没有**可用的剪贴板后台监听（未开启、未走通，或未配合通知、电池优化等系统策略）时，新复制内容往往只能依赖**先打开应用**再复制，才会稳定写入历史，同步也才会跟上——容易误判成「同步坏了」，其实是本端还没记进历史。

机制与选项见 [剪贴板后台监听](/features/source/background-monitoring/)；需要动开关时见 [快速开启指南](/features/source/background-monitoring/quick-start)。想先看短说明可读 [剪贴记录预期](/getting-started/clipboard-record-expectations)。

:::
:::tab{label="iOS"}

系统**完全不支持**与桌面 / Android 相同的**持续后台剪贴板监听**。替代方式是：用**快捷指令**或**系统分享**把剪贴**手动**交给本应用，常常**无需**先打开应用主界面即可完成这一轮录入（分享扩展等系统界面仍可能出现，以实际交互为准）。回到应用内操作仍是通用路径之一。

详见 [剪贴板后台监听](/features/source/background-monitoring/)、[iOS 平台说明](/advanced/ios/) 与 [跨平台差异](/advanced/platform-differences)。

:::
:::

## 按顺序检查

:::steps
:::step{title="确认两台设备都在运行"}

确保两端都能打开应用，并可进入剪贴历史页面。

:::
:::step{title="确认两端使用同一种同步方式"}

两端都使用附近同步，或两端都使用云同步。不要一端附近同步、一端云同步。

:::
:::step{title="做一次最小文本测试"}

在设备 A 复制：

```text title="最小测试文本" noLineNumbers
octoclip-troubleshooting-001
```

然后在设备 B 打开历史列表查找该文本。

:::
:::step{title="排除网络与系统拦截"}

临时关闭 VPN/代理后复测；检查系统是否对应用施加后台限制或省电限制。

:::
:::step{title="做反向测试"}

在设备 B 复制新文本，再到设备 A 查找，确认是单向问题还是双向问题。
:::
:::

## 常见修复动作

若上面步骤已定位大致方向，可展开下面对应项，按条做**补充动作**（与上文顺序检查配合，不替代上文）。

:::accordion{multiple}
:::item{label="设备看不到新剪贴"}
- 统一两端同步方式并重试。  
- 确认两端网络可用且应用未被系统挂起。  
- 先用纯文本测试，再测试复杂内容。  
- **Windows / macOS**：少见「未开后台监听」导致不写历史；可查应用是否退出、防火墙或 **macOS** [权限](/advanced/macos/permissions)。  
- **Android**：若后台监听未开或未生效，先**打开应用**再复制复测，或按 [快速开启指南](/features/source/background-monitoring/quick-start) 配置后再测。  
- **iOS**：尝试用**系统分享**或**快捷指令**把剪贴交给应用；参见 [iOS 平台说明](/advanced/ios/)。

:::
:::item{label="只有一个方向失败"}
- 重点检查失败方向来源设备的权限和后台状态。  
- 重新打开来源端应用后再次复制测试文本。  
- 若仍失败，重启来源端设备后复测。

:::
:::item{label="历史有内容但无法粘贴"}
- 更换一个普通文本输入框测试。  
- 检查系统是否拦截粘贴行为。  
- 重新复制同一文本后立即粘贴，排除过期状态影响。
:::
:::

## 修复后如何验证

- 在设备 A 复制 `octoclip-troubleshooting-001`。
- 在设备 B 历史中看到该文本。
- 在设备 B 成功粘贴出相同文本。
- 反向测试也能成功（设备 B -> 设备 A）。

## 下一步

:::cards{cols=2}
:::card{title="复制与粘贴" icon="lucide.play" href="/getting-started/first-steps"}
怀疑单端未写入历史时，回到本机最短验证。

:::
:::card{title="跨设备复制" icon="lucide.copy" href="/getting-started/first-cross-device-paste"}
回到首次跨端任务页，按最短路径重做端到端验证。

:::
:::card{title="剪贴板后台监听（平台专题）" icon="lucide.monitor-cog" href="/features/source/background-monitoring/"}
理解「不打开 App 就不记剪贴」与后台限制，减少误判为同步坏了。

:::
:::card{title="同步方式概览" icon="lucide.git-compare" href="/features/sync-overview"}
仍不稳定时，对照场景确认是否选对了同步方式。

:::
:::card{title="常见问题" icon="lucide.circle-help" href="/getting-started/faq"}
快捷键、资源占用等日常问答。
:::
:::

## 仍未解决

请反馈以下信息：

- 两台设备平台与系统版本
- 应用版本
- 使用的同步方式（附近同步 / 云同步）
- 网络环境（同一 Wi-Fi / 不同网络 / VPN / 代理 / 防火墙 / 公司网络）
- 失败方向（A -> B / B -> A / 双向）
- 内容类型（纯文字 / 图片 / 链接 / 文件等）
- 若涉及 **Windows / macOS**：应用是否常驻运行、是否有防火墙/安全软件拦截；**macOS** 是否已对照 [权限说明](/advanced/macos/permissions)
- 若涉及 **Android**：是否已配置剪贴板后台监听、是否试过「先打开 App 再复制」
- 若涉及 **iOS**：是否用过分享 / 快捷指令等替代路径
- 复现步骤（最短路径）
- 预期结果与实际结果