故障排查
本页聚合使用 Backlog.md 时的常见故障，每节按「症状 → 原因 → 处置」组织。各功能页的详细说明仍归原页，这里只做排错索引与处置建议。
Web 端口被占用
症状：启动 backlog browser 时端口不可用，或访问的地址打不开。
原因：默认端口 6420 已被其他进程占用。
处置：
- 默认
autoPort: true，端口占用时服务器会自动扫描后续可用端口并在终端打印真实地址（如http://localhost:6421），照抄控制台输出即可，不算故障。 - 若关了
autoPort，占用会直接报EADDRINUSE——用backlog browser --port 8080显式指定端口。 - 自动扫描只接受用户端口范围（1024–65535）内的端口，拒绝操作系统临时分配的随机高位端口。
图谱一直 building / 锁冲突
症状：图谱页面长时间显示加载中，/api/graph 一直返回 building；或启动时报锁冲突。
原因：图谱槽位的锁同一时刻只允许一个进程持有。持有方进程已退出时锁会自动回收，不会卡 building；卡 building 通常是持有方进程仍活着（例如另一个浏览器会话或残留的 backlog browser 进程）。
处置：
- 持有方进程已退出时无需操作，锁自动回收、自动重建。
- 持有方仍存活时，交互终端会询问是否接管锁——确认前请先确实旧进程已不再需要图谱。
- 两个浏览器会话各持有独立数据库（按项目路径哈希分槽），互不争抢；排查时确认是否为同一项目起了多个服务进程。
- 可用环境变量
BACKLOG_GRAPH_CACHE_DIR覆盖缓存目录；BACKLOG_GRAPH_BACKEND=kuzu已不再是合法取值（原生依赖已移除），能覆盖的只有memory。 - Cypher 检索不可用（图谱页搜不到内容、
backlog graph query报错）时先看终端有没有[graph] RyuGraph (WASM) backend init failed for <path>, falling back to memory告警：有则后端已降级到内存（无 Cypher），按告警末尾的原因区分「路径对 WASM 不可见」（v1.53.9 已修复）与「引擎故障」（需上报）。
watch / 文件变更不刷新
症状：TUI 看板、Web 界面或 task list --json --watch 没有反映刚做的修改。
原因与处置：
- TUI 看板：底层用
Bun.watch监听任务目录。它对原子写入具有弹性（等待文件稳定后再刷新），但确认你修改的是当前项目的backlog/目录——用--cwd/BACKLOG_CWD启动的实例只看各自解析到的项目。 --json --watch：通知是提示性的，1 秒的 reconcile tick 会用文件 stat 签名兜底修复漏掉的事件；签名不变就不重复输出。确认监听进程的上游程序还活着（启动方退出即停）。- Web 界面：通过 WebSocket 广播刷新。整页不刷新时先确认浏览器控制台 WebSocket 连接正常；CLI / TUI / MCP 的写入都会触发通知。
macOS 报 illegal hardware instruction / 架构不匹配
症状（M 系列 Mac）：运行 backlog 报 illegal hardware instruction 或 Binary package not installed for darwin-...。
原因：Node、Bun 或 Homebrew 以 Rosetta（x64 模拟）方式运行，却安装了与原生 CPU 架构不匹配的 Intel 版二进制。
处置：先检查各工具报告的架构：
uname -m # arm64 = Apple Silicon 硬件；x86_64 = Intel 或 Rosetta shell
node -p process.arch # Node/Bun 运行时架构
sysctl -in sysctl.proc_translated # 1 = 当前 shell 运行于 Rosetta 之下
which brew # /opt/homebrew = arm64 brew，/usr/local = Intel brew
架构不一致时用原生架构重装：
brew reinstall backlog-md # 上游 formula；先确认 which brew 输出 /opt/homebrew
arch -arm64 npm i -g @kuwork/backlog.md
arch -arm64 bun add -g @kuwork/backlog.md
刻意在 Rosetta 下运行 x64 Node 也可以：启动器会回退到实际已安装的任一 backlog.md-darwin-* 包。详见安装与初始化。
watch 进程空转 CPU 高（旧版本）
症状：backlog task list --json --watch 在无事发生时仍持续占用高 CPU（大仓库实测约 35–42%）。
原因：旧版本的 1 秒 reconcile tick 无条件重复完整任务列表读取；成本随仓库规模增长。
处置：升级到最新版本——空转时每秒只做一次廉价的 stat 签名比较，CPU 降到 1% 以下，输出与延迟不变。浏览器与 TUI 的 watcher 无此轮询，不受影响。
MCP 连接问题
症状：AI 客户端报告 MCP 服务器启动失败、超时，或任务写入到了错误项目。
处置：详见 MCP 工作流的「常见问题」：
- 启动失败/超时：多为本地
backlog命令解析到陈旧二进制——重新构建、用codex mcp add backlog -- backlog mcp start格式注册，并单独测试backlog mcp start。 - 写入错误项目：升级到最新版本（服务器跟随客户端 workspace roots），或
backlog mcp start --cwd <path>固定目录。
按 E 打开编辑器无响应
症状：TUI / Web 中按 E 打开编辑器后界面挂起或编辑器不启动。
原因与处置：多见于默认编辑器 code --wait 会挂住无人值守的代理进程，或编辑器路径含参数解析失败。
- 清除默认编辑器：
backlog config set defaultEditor "" - 或用
EDITOR环境变量按次覆盖：EDITOR=nvim backlog board - 编辑器路径含参数时请写完整可执行路径或用包装脚本；颜色异常时设
TERM=xterm-256color
详见配置管理的「编辑器解析优先级」一节。