常见问题

云盘授权失败

请检查是否开启了网络代理。或者打开终端，参考 #查看开发者工具错误日志。

新设备未同步文件 & 云盘上没有仓库文件夹

请验证仓库名称是否有效。关于百度网盘文件名符号限制的详情，请参考此链接。

部分文件同步失败

检查文件路径是否包含 Emoji —— Emoji 被视为无效字符。
在自动模式下，由于网络波动可能会导致同步失败。系统将在下一个同步周期自动重试。
尝试切换到受限模式进行手动同步。如果手动同步仍然失败，请在 Github 或 Gitee 上提交 Issue，或在社区群中讨论。

如何收集调试日志用于报修

在 设置 → 维护与调试 → Debug 文件日志 中开启日志记录，复现问题后点击 导出报告，粘贴到 GitHub Bug Report 中提交。

自我诊断指南

同步体验取决于外部因素，包括：

网络稳定性（影响同步稳定性）。
网络带宽（影响同步速度）。
网络拓扑（影响点对点连接能力）。
云盘账户等级（影响下载速度）。

Sync Vault 用户可以根据需要自行诊断同步问题。

graph LR
Q2(同步速度慢)
Q1(文件同步错误)
A1(运行同步速度测试并选择最佳云盘)
A2(获取诊断概览 - 检查错误)
A3(查看最新同步报告 - 获取详细错误信息)
Q1-->A2 & A3
Q2-->A1

获取诊断概览

转到 仓库信息 设置标签页，点击 “Diagnose” (诊断) 按钮，查看诊断信息，包括以下部分：

系统信息：显示 Obsidian 版本、Sync Vault 版本和当前系统类型。

{
    "platform": "macOS",
    "obsidianVersion": "Obsidian Repository - Obsidian v1.9.12",
    "pluginVersion": "2.1.0"
}

仓库信息：文件总数和仓库对应的云端路径。

{
    "name": "Obsidian Repository",
    "path": "/apps/obsidian/Obsidian Repository",
    "totalFiles": 513,
    "configPath": "/apps/obsidian/Obsidian Repository"
}

当前配置：插件相关设置。

{
     "ignorePattern": "^(New Folder).*$",
     "fileSizeLimit": 100,
     "encryptMode": false,
     "syncThemes": true,
     "syncPlugins": true,
     "showHidden": true
}

同步状态：包括当前同步模式、云盘和授权码过期时间。

{
     "mode": "restricted",
     "isLiveMode": true,
     "cloudDisk": "baidu",
     "tokenValid": true,
     "tokenExpiry": "2026/8/1 11:40:15",
     "lastSyncTime": null
}

同步统计：记录上次同步时间、总同步尝试次数和最近错误。

{
     "lastSyncTime": null,
     "totalSyncTimes": 0,
     "recentErrors": [],
     "totalFilesProcessed": 0
}

最近错误
```
{
     "recentErrors": []
}
```

查看最新同步报告

在云盘同步期间，用户可以访问最新同步的详细记录。具体操作请参考查看同步报告。

测试同步速度

转到 高级功能 > 调试。
找到 “Cloud Drive Performance” (云盘性能) 部分，点击右侧的 “Perf” 按钮。将弹出以下界面：
400
点击相应云盘的测试按钮以测试其速度。下图显示了 非云盘会员在商场公共 WiFi 下的速度体验：
400

Download Speed (下载速度)：当前环境下的文件下载速度。
Upload Speed (上传速度)：当前环境下的文件上传速度。
Latency (延迟)：云盘 API 的访问延迟，大致相当于一次同步所需的最小延迟。

关于每个云盘的详细同步性能分析，请点击这里。

查看开发者工具错误日志

打开 Obsidian 开发者工具 (DevTools) 以检查错误：

macOS: 按 cmd+option+i
Windows: 按 ctrl+shift+I

Debug 文件日志系统

内置的诊断工具，将运行日志持久化写入本地文件，用于排查问题。

开启方式

设置 → 维护与调试 → Debug 文件日志 — 打开开关。

文件结构

.sync-vault-debug/
├── debug-2026-07-15.log           # 当日完整日志
└── session-20260715T132100.log    # 每次同步的操作记录

Debug Header（日志顶部）

每条日志文件头部包含：系统信息、仓库信息、同步配置、网络状态、插件 State 健康度。

导出报告

在设置页点击 导出报告 生成压缩包，直接粘贴到 GitHub Issue 中。

隐私说明

日志仅存储在本地，已加入同步忽略列表，不会上传到云端。

报修流程

开启日志
复现问题
导出报告
在 GitHub 创建 Bug Report
粘贴报告并提交