07 · Troubleshooting
从症状回到底层边界
PATH、版本、编辑器、认证、冲突、校验和网络问题都应该产生可定位的失败。
安装与本地环境
| 症状 | 检查 | 处理 |
|---|---|---|
| 找不到 blog | npm prefix -g；where.exe blog / which blog | 补 PATH，或在当前 Node 环境重新 npm link |
| Node 版本不支持 | node --version | 切换 Node 20/22，再 npm install 与 npm link |
| 编辑器打不开 | blog doctor；检查 BLOG_EDITOR | 配置能等待关闭的命令，如 code --wait |
| YAML 无效 | blog post validate file --local | 按报错行修复缩进、引号或字段类型 |
HTTP 与状态语义
| 状态 | 含义 | 下一步 |
|---|---|---|
| 401 | 令牌无效且刷新失败 | 重新 blog login |
| 403 | 账号无该管理权限 | 确认账号角色，不要重复登录碰运气 |
| 409 | revision 冲突或状态前提不成立 | 重新 pull/show，合并或按状态机处理 |
| 422 | 字段、分类、标签或业务规则无效 | 修正文档并重新 validate |
| 网络错误 | DNS、TLS、代理或站点不可达 | blog doctor；在浏览器或 curl 验证同一基点 |
升级与卸载
git fetch --tags
git status
git pull --ff-only
npm install
npm run typecheck
npm test
npm run build
npm link先确认本地是否有改动，再只允许快进更新。依赖、构建产物与全局链接都需要和新源码同步。
npm unlink -g tyndall-blog-cli配置目录不会自动删除。先 blog logout，确认不再需要后再由用户自行处理 ~/.config/tyndall-mcp/。