故障排查

Vault 没同步

Git / iCloud / Dropbox 每种同步路径的排查、修复与冲突处理。

症状

A 机器上改了笔记，B 机器上看不到；或者反过来 — B 上看到的是几小时前的版本；或者两台机器都看得到，但内容打架了（出现 note (conflict-2026-06-07).md 之类的"打架文件"）。

Kition 本身是本地优先的 — 它把笔记当成普通 Markdown 文件，同步不是 Kition 做的，而是底层的 Git / iCloud / Dropbox 在做。所以排查思路是：先确认 Kition 写盘了，再确认同步工具搬运了，最后确认对端拉回来了。

通用第一步：确认 Kition 已写盘

Kition 默认每输入 800ms 自动保存一次，但如果系统电池低 / 磁盘满 / 文件被外部锁住，写盘会失败。

# In your vault root, see the most recently changed files
ls -lt | head -20

# Confirm the file size > 0 and mtime is in the last minute
stat "Daily/2026-06-07.md"

# macOS: see if anything is holding the file open
lsof | grep "2026-06-07.md"

Git 同步排查

Git 同步是最透明也最可控的方式 — 一切走 git status 就知道当前状态。

git status — 看本地有没有 staged / unstaged 改动
git pull --rebase — 拉远端，把本地放在远端之上
git log --oneline -10 — 看最近 10 条提交，确认对端的提交是不是真的有
冲突文件用编辑器手工解决，删掉 <<<<<<< 标记后 git add + git commit
Settings → Sync → 看自动 push 间隔是不是太大（默认 5 分钟）

iCloud / Dropbox 同步排查

这俩本质都是文件系统层的后台服务 — Kition 写了一个 .md，iCloudDrive / Dropbox 守护进程把它推上云。任何同步异常都在守护进程的状态里。

看 Finder 里文件名旁边的小图标：云 + 箭头 = 上传中，绿圈 = 已同步，红叹号 = 失败
系统托盘 / 菜单栏点 iCloud / Dropbox 图标，看"最近活动"列表里有没有报错
云端控制台（iCloud.com、dropbox.com）搜你的 vault 路径，确认远端真的拿到了
冲突文件命名约定：filename (conflict-...).md、filename (Bob’s MacBook).md — 这是同步工具改的，不是 Kition
不要让两个云盘客户端挂在同一个目录 — 它们会互相覆盖

冲突文件怎么处理

当你看到 Note (conflict-2026-06-07-093012).md 这类文件，不要直接删 — 它是同步工具救下的另一份版本。正确流程：

把原文件 Note.md 在 Kition 里打开
把 conflict 文件用普通文本编辑器打开（或 Kition 新窗口）
逐段对比，把对的内容合到 Note.md
存盘，再把 conflict 文件删掉
强烈建议先 cp Note*.md /tmp/ 做个备份

应急方案

如果你急需在 B 机器上看 A 机器的最新内容、而正常同步还没到位：把 Vault 整个目录用 rsync / scp / U 盘搬过去一次，覆盖 B 机器的旧 vault。Kition 下次启动会自动重建索引（5-30 秒）。

什么时候该提 bug

Kition 写盘成功但同步工具没看见文件（mtime 没刷新）
索引重建后双链反链全断
.kitable 文件在两台机器上 mtime 一致但行数 / 校验码不同（数据分叉）

← 返回帮助中心更多故障排查 →