Obsidian 故障排查

国内 Windows 环境下 Obsidian 打不开/卡在"加载仓库中"的完整排查流程。

环境

• Obsidian 安装：D:\sofeware\obsidian\Obsidian.exe
• 配置目录：%APPDATA%\obsidian\（C:\Users\<用户>\AppData\Roaming\obsidian\）
• Vault 列表：%APPDATA%\obsidian\obsidian.json
• Vault 级配置：<vault路径>\.obsidian\

诊断流程（按概率从高到低）

一、core-plugins.json 损坏

症状：卡"加载仓库中"，进度条不动或极慢。

根因：<vault>\.obsidian\core-plugins.json 为 0 字节空文件，Obsidian 解析时卡住。

诊断：

# 检查文件大小
ls -la "D:\Hermes\.obsidian\core-plugins.json"
cat "D:\Hermes\.obsidian\core-plugins.json"
# 空文件或0字节 = 损坏

修复：从正常 vault 复制一份（697 字节左右的标准配置）：

cp "D:\Hermes\knowledge-base\.obsidian\core-plugins.json" "D:\Hermes\hermes-agent\.obsidian\core-plugins.json"

标准内容见 references/core-plugins-template.json。

二、自动更新下载卡死

症状：日志反复出现 Downloading update from https://github.com/...，国内网络下载 GitHub Release 极慢，拖死启动。

诊断：检查更新缓存

ls "C:\Users\<用户>\AppData\Local\obsidian\pending-update" 2>/dev/null
ls "C:\Users\<用户>\AppData\Local\Obsidian\pending-update" 2>/dev/null

修复：

import json
# 1. 禁用自动更新
path = 'C:/Users/28672/AppData/Roaming/obsidian/obsidian.json'
with open(path) as f:
    data = json.load(f)
# 在 vaults 同级添加或修改 config
data['config'] = data.get('config', {})
data['config']['autoUpdates'] = False
with open(path, 'w') as f:
    json.dump(data, f, indent=2)

# 2. 清更新缓存
rm -rf "C:\Users\<用户>\AppData\Local\obsidian\pending-update"
rm -rf "C:\Users\<用户>\AppData\Local\Obsidian\pending-update"

三、Vault 文件过多导致索引卡死

症状：vault 下 2000+ 文件时，Obsidian 启动索引扫描所有文件直到超时/内存耗尽。

根因：Obsidian 默认索引 vault 内所有文件，包括 .git、.venv、node_modules、二进制等不应索引的内容。

修复：在 <vault>\.obsidian\app.json 配置排除规则：

{
  "userIgnoreFilters": [
    ".git/",
    ".venv/",
    "node_modules/",
    "__pycache__/",
    "*.pyc",
    "*.exe",
    "*.dll",
    "*.so",
    "*.bin",
    "*.pak",
    "*.asar",
    "scripts/",
    "plugins/",
    "logs/",
    "temp/",
    "audio_cache/"
  ]
}

注意：userIgnoreFilters 中目录不加尾部斜杠（如 companion_bot_v3 而非 companion_bot_v3/）。排除规则在索引后才生效，但能防止后续的重索引风暴。

四、嵌套 Vault 冲突

症状：两个 vault 是父子目录关系（如 D:\Hermes 和 D:\Hermes\hermes-agent），同时注册在 obsidian.json 中，导致索引冲突。

修复：只保留父目录或子目录其中之一作为活跃 vault。如果两个都要用，确保每次只打开一个。

五、缓存损坏

症状：以上修复后仍异常。

修复：清 Obsidian 全部缓存后重启

rm -rf "C:\Users\<用户>\AppData\Roaming\obsidian\Cache"
rm -rf "C:\Users\<用户>\AppData\Roaming\obsidian\Code Cache"
rm -rf "C:\Users\<用户>\AppData\Roaming\obsidian\GPUCache"

关键文件位置速查

本次修复实例（2026-08-05）

三个 vault 同时出问题：

1. knowledge-base → 正常（唯一能打开的）
2. hermes-agent → core-plugins.json 0字节 → 从 knowledge-base 复制修复 + 禁用 autoUpdates
3. Hermes（D:\Hermes）→ 2000+文件索引卡死 → 添加 userIgnoreFilters 排除大目录

结果：knowledge-base 正常启动，Hermes/hermes-agent 需排除规则后重开。