WebDAV Sync（坚果云 / 通用 WebDAV）

⚠️ 自用插件 · AI 生成 · 不保证更新 个人使用为主，代码由 AI 在人工指导下完成，按现状提供，不承诺维护与修 bug。

一个给 Obsidian 用的双向同步插件，主打国内可用：

• 坚果云：官方 WebDAV，免费账户即可用（有频率/数量限制，见下）
• 同样兼容 Alist / 群晖 / Nextcloud / 自建 WebDAV
• 桌面端 + 移动端同一套代码：网络请求走 Obsidian 官方 requestUrl（绕过 CORS，移动端原生可用），不依赖 Node
• 中英双语界面（自动跟随 Obsidian，可手动切换）

不选阿里云盘/百度网盘：它们没有稳定的官方开放 API，第三方接口随时可能失效且违反服务条款。

当前版本：0.1.3

---

一、坚果云配置（5 分钟）

1. 注册/登录 坚果云
2. 右上角头像 → 账户信息 → 安全选项 → 第三方应用管理 → 添加应用密码
3. 名称随便填（如 obsidian），生成一串应用密码，复制它
4. 打开 Obsidian → 设置 → 第三方插件 → WebDAV Sync：

设置项	填什么
服务器地址	https://dav.jianguoyun.com/dav/（默认已填；只填 dav.jianguoyun.com 也会自动补全）
账号	你的坚果云登录邮箱
应用密码	上一步生成的那串（不是登录密码）
云端目录	如 ObsidianSync（不存在会自动创建）
自动同步间隔	建议 10 分钟以上；0 = 只手动

5. 点 测试 → 提示"连接成功"即可（失败时下方会显示每一步的 URL 和状态码，直接看是哪一步坏了）
6. 命令面板执行 「立即双向同步」，或等自动同步

两台设备（电脑 + 平板）都装这个插件、填同一套配置，就能互相同步。

---

二、同步规则（务必先看懂）

• 状态表判变化（0.1.1 起）：每次同步后记录"本地 mtime / 云端 mtime"作为基线；下次只有真的变了的那一侧才会传输。这样即使两台设备时钟不一致，也不会反复重传同一文件。
• 较新者胜：首次遇到某文件（还没有基线）时，按修改时间判断，3 秒容差。
• 只在一侧存在的文件：会被复制到另一侧（新增文件双向流动）。
• 删除不传播：刻意的保守设计——某端删了文件，不会把另一端也删掉。要删除请两端手动删，或先关掉自动同步再操作。
• 不合并冲突：两端同时改同一文件时，按修改时间较新者覆盖。重要笔记请在同步前确认另一端没有未保存的改动。
• 默认不同步 .obsidian：插件设置、外观、快捷键不会互相同步。想让两端配置一致时可打开「同步隐藏目录」——但这会把插件配置（含 API Key）一起传到云端，不建议长期开启。
• 忽略规则：每行一条，支持路径前缀、包含匹配和 *.mp4 这类后缀匹配；默认忽略 .obsidian、.trash。
• 内容哈希去重：mtime 变了但文件内容没变（编辑器碰过文件、复制粘贴同名同内容）不会上传。

---

三、常见问题（HTTP 状态码对照）

现象	最可能的原因	怎么办
HTTP 404	① 地址不是 WebDAV 端点（漏了 /dav/，或用了 www.jianguoyun.com）；② 云端目录不存在（旧版本会误报，0.1.1 已修）	服务器地址填 https://dav.jianguoyun.com/dav/；点「测试」看它打印的实际 URL
HTTP 401	用了登录密码，或邮箱填错	必须用应用密码；邮箱是登录邮箱
HTTP 403	免费版频率超限（每 30 分钟 600 次），或该路径无写权限	把同步间隔调到 10 分钟以上，减少同步文件数
HTTP 501	服务器不认 PROPFIND，通常说明地址填错	核对地址
同步一半中断，提示 750 条	坚果云单次目录列表上限 750 条	把笔记拆到多个子目录，或关闭自动同步改用手动
卡住/长时间无响应	旧版本在子目录列表上有死循环（0.1.1 已修）	升级到 0.1.1

插件设置里「实际请求地址」会显示它真正使用的 URL；「最近一次连接测试」会逐条列出请求 URL 与状态码，排查时先看这两处。

---

四、省流量（免费版每月只有 1GB 上传 / 3GB 下载）

坚果云免费版每月上传 1GB、下载 3GB，用尽后直接无法同步（详见官方说明）。本插件为此做了四层保护：

机制	说明	默认值
单文件上限	超过该大小的文件本次跳过并提示。一个视频/压缩包就能吃掉整月配额	20 MB（可改，0 = 不限制）
月上传上限	达到上限前主动停手，避免账号被锁；下月自动恢复	1024 MB
月下载上限	同上	3072 MB
内容哈希去重	只有内容真的变了才上传；仅 mtime 变化不产生流量	始终启用
流量看板	设置页显示本周期区间（起止日）、已用 / 上限 / 百分比，可手动重置	—
计费周期起始日	坚果云按注册日清零，不是自然月。填你的重置日（1–28），看板与上限判断都按「本月起始日 → 下月起始日前一天」算	1（自然月）
流量校准	插件只能看到自己的 WebDAV 传输；把坚果云网页端（账户信息 → 流量使用情况）的数字填进来点「校准」，用真实值覆盖本地估算，之后继续累加	建议每月校准一次
阈值告警	用掉 70%、90% 各提醒一次（只提醒一次，不刷屏），提示里带上本周期区间	内置

统计口径：只统计本插件走 WebDAV 的实际传输字节，其它设备、网页端上传下载都不在其中，所以数字偏小是正常的——用「校准」把差额补上即可。校准后若又出现新的阈值跨越，仍会照常告警。

其他省流量的习惯：别用 WebDAV 同步视频/大附件；.obsidian 默认不同步（工作区文件每次开关都会变，很费流量）；把笔记拆到多个子目录可避免触发单目录 750 条上限。

五、已知限制

• 坚果云免费版：每 30 分钟 600 次请求（付费 1500）；单次目录列表最多 750 项；单文件上传上限 500MB
• 没有实时同步（不是文件系统监听，靠定时器）
• 没有端到端加密（数据在坚果云服务器上是明文可读的，敏感笔记请勿使用）
• 首次同步大量文件会较慢，且占流量
• 冲突只按时间判断，不合并内容
• 删除不传播（见上）

---

六、安装

1. 下载 webdav-sync-cn 文件夹（或 zip 解压），确保含 manifest.json、main.js、styles.css
2. 放入 <你的库>/.obsidian/plugins/webdav-sync-cn/
3. Obsidian → 第三方插件 → 启用 WebDAV Sync (Jianguoyun / generic)
4. 安卓 11+ 若文件管理器进不去 Android/data，请把库放在共享存储（如 Documents/）或用 adb push

七、平台支持

平台	状态
Windows / macOS / Linux	✅ 预期可用（requestUrl + 纯 JS）
Android	✅ 已在 Android 14 / Obsidian 1.9 真机上加载并配置
iOS / iPadOS	⚠️ 预期可用，未验证

---

八、变更记录

0.1.3

• 计费周期起始日：新增「每月几号清零」（1–28，超出自动收到 28），统计区间、看板、上限判断全部按账号真实的清零日走，不再假设自然月
• 流量校准：新增「校准流量」——填入坚果云网页端显示的已用上传/下载（MB），用真实值覆盖本地估算，并在本周期内继续累加；页面显示上次校准时间
• 看板升级：显示本周期区间 起 → 止，文案从「本月」改为「本周期」
• 校准会把告警水位同步到当前百分比，避免校准完立刻重复弹窗

0.1.2

• 流量控制：单文件上限（默认 20MB）、月上传/下载上限、达到上限前主动停止
• 流量看板：设置页显示本月上传/下载用量与百分比，可一键重置
• 流量告警：跨过 70% / 90% 各提醒一次（不重复刷屏）；同步摘要里直接显示本次上传/下载了多少 MB
• 内容哈希去重：mtime 变了但内容没变时不上传（省上传流量）
• 修正「仅上传 / 仅下载」为方向过滤（不再全量重传）

0.1.1

• 修复 HTTP 404：目录 URL 现在保留结尾斜杠；「测试连接」改为先认证根目录、再建/查云端目录（不再对不存在的目录直接 PROPFIND）
• 修复 MKCOL 路径重复：云端目录名曾被拼接两次（/dav/ObsidianSync/ObsidianSync/），导致同步直接失败
• 修复子目录列表死循环：PROPFIND 返回的自身条目被当成子目录再次递归，旧版会在有子目录时卡死
• 新增状态表：按基线 mtime 判断变化，时钟不一致不再反复重传（省坚果云请求额度）
• 地址自动归一化：缺 https://、缺 /dav/、www. 域名都会自动纠正
• 「仅上传 / 仅下载」改为方向过滤：只限制传输方向，不再每次都全量拉取/推送（旧行为会白白消耗请求额度）
• 错误信息可读化：401/403/404/501 各自给出对应原因与处理办法；设置页显示实际请求地址与逐步骤测试结果
• 目录创建去重（一次同步内只 MKCOL 一次）；单目录 750 条上限检测；请求数超 500 时提示

0.1.0

• 首个版本：双向同步、仅上传/仅下载、自动同步、忽略规则、中英双语

---

MIT License · 作者 pi3141592653589793