第 10 章 · 常见问题与故障排查
适用版本：Joplin 3.x
本章汇总同步失败、忘记主密码、应用无法启动等常见问题与解决方案。
1. 同步失败
| 现象 | 解决方法 |
|---|---|
| 401 认证失败 | 改用应用专用密码（坚果云在「第三方应用管理」生成） |
| 超时 / 无法连接 | 更换网络重试，检查流量是否耗尽 |
| 频繁冲突 | 打开冲突副本手动合并，养成编辑完立即同步的习惯 |
如果上述方法仍未解决，可以到官方论坛搜索相同错误码的讨论帖，通常能找到对应的社区解决方案。
2. 忘记主密码
同步问题优先按「网络 → 配置 → 服务端状态 → 数据一致性」的顺序排查，多数问题在第二步即可解决。JEX 备份是唯一能完整保留笔记与附件的恢复手段，建议每次修改加密设置前后都导出一次。
启用 E2EE 后忘记主密码，云端数据无法解密。若其他设备还记得，优先从该设备导出 JEX 备份；若全部忘记，只能「重置加密」（清空云端加密数据，本地未加密笔记仍可访问），操作前务必备份本地数据。
3. 应用无法启动
- Windows：检查安全软件是否拦截 Joplin 主程序，可临时加入白名单。
- Linux：AppImage 需
chmod +x，依赖缺失时尝试官方安装脚本。 - macOS：首次打开需在「隐私与安全性」允许来自已识别的开发者。
如果应用反复崩溃，可以查看日志目录下的 log.txt 定位具体错误，再到官方论坛搜索解决方案。
4. 性能卡顿
高分辨率图片过多、单篇笔记过大、插件太多都会导致卡顿，建议清理插件、拆分巨型笔记；首次同步大量数据较慢属正常现象。性能优化还可以通过限制同步资源大小、定期清理已删除笔记的回收站来实现。
5. 图片与附件丢失
检查原网页是否有防盗链限制；查看数据目录 resources 文件夹是否完整，必要时从备份恢复；外部图片链接离线时无法显示。定期导出 JEX 备份是最稳妥的应对方式。关于附件丢失的更多排查方法，见官方文档 附件帮助 与 GitHub Issues。遇到难题可先看 同步排查 与 常见问答。
常见问题
为什么同步冲突会生成“conflict”笔记？
两台设备离线修改同一笔记时，Joplin 无法判断哪份更新，于是生成冲突副本保留双方修改，由你手动合并。
Joplin 会一直免费吗？
Joplin 是开源软件（AGPL-3.0），核心功能永久免费；官方 Joplin Cloud 是可选付费服务。
遇到问题先查看日志文件，日志中通常会记录具体的错误原因，有助于快速定位并解决。