一、最常见的 5 种同步失败
| 现象 | 常见原因 | 解决方向 |
|---|---|---|
| 一直转圈、超时 | 网络不通 / 服务器慢 / 防火墙拦截 | 检查网络与代理设置，切换网络重试 |
| 401 / 403 认证失败 | WebDAV 密码错误 / 应用密码未创建 | 重新生成坚果云等服务的专用应用密码 |
| SSL 证书错误 | 自建服务器证书不受信任 / 系统时间错误 | 更新证书或配置 Joplin 忽略证书校验 |
| 同步冲突提示 | 多设备离线编辑同一笔记后合并 | 定期同步，冲突笔记手动合并 |
| 目标已存在（revision） | 服务端与本地状态不一致 | 在同步设置中执行「重置同步状态」 |
Joplin 的同步基于增量协议，官方文档 同步说明 与 GitHub 仓库 里都有详细的故障排查章节。遇到问题先看官方文档，再结合本文按步骤定位。
二、WebDAV / 坚果云同步排查步骤
- 确认网络可达：在浏览器中访问你的 WebDAV 地址，确认能正常打开。
- 核对应用密码：坚果云等网盘需要「应用密码」而非登录密码，在「账户信息 → 安全选项」中创建（详见 新手入门教程）。
- 检查 URL 格式：WebDAV 地址应为完整路径（如
https://dav.jianguoyun.com/dav/joplin/），结尾建议保留斜杠。 - 重置同步状态：确认服务端备份完好后，在同步设置中点击「重置同步状态」，再重新同步。
三、坚果云免费版限流与账户临时限制（封禁）
坚果云免费版有每月上传/下载流量限制，Joplin 同步大量小文件时很容易触发限流，表现为 HTTP 403、同步反复失败，甚至账户被临时限制（俗称「封禁」）。遇到这种情况：先停止同步，登录坚果云网页版查看账户状态与流量用量；若确实触达免费额度，可等待次月重置、升级付费版，或改用其他 WebDAV 服务商、自托管 Joplin Server，从根源上避开限流。
四、端到端加密相关故障
启用端到端加密后，切换设备时需要输入主密码；忘记主密码只能通过助记词恢复。若提示「无法解密」，请确认主密码输入正确，或在另一台已登录设备上导出加密密钥。
五、同步冲突如何处理
当两台设备离线编辑同一篇笔记时，Joplin 会生成冲突副本（文件名带 conflict 标记）。打开冲突笔记对比两个版本，手动合并保留需要的部分，删除多余冲突副本即可。养成「切换设备前先同步」的习惯可大幅减少冲突。
六、常见问题
坚果云 WebDAV 提示 401 是什么原因？
通常是使用了坚果云登录密码而非应用密码。请到坚果云「账户信息 → 安全选项」创建「应用密码」，然后在 Joplin 中填入该应用密码。