Anki-Connect 故障排除指南

2026-04-12 09:38:59作者：范靓好Udolf

[插件加载失败]：如何恢复 Anki-Connect 功能？

当 Anki 启动后插件列表中找不到 Anki-Connect，或提示"加载失败"时，可按以下步骤诊断解决：

问题定位

Anki 启动时未加载插件，通常表现为插件管理器中显示"已禁用"状态或完全缺失。

核心原因

插件文件损坏或权限不足
Anki 版本与插件不兼容
配置文件格式错误

分层解决方案

🔍 诊断：检查插件目录结构

~/.anki/addons21/anki-connect/
├── __init__.py
├── config.json
└── web.py

操作验证点：确认以上核心文件存在且大小正常（非0字节）

✅ 验证：查看 Anki 日志

打开 Anki → 帮助 → 显示调试信息
搜索"anki-connect"关键词，查找加载错误信息

🔧 修复：重新安装插件

从插件目录删除现有文件：rm -rf ~/.anki/addons21/anki-connect
克隆仓库：git clone https://gitcode.com/gh_mirrors/an/anki-connect ~/.anki/addons21/anki-connect
重启 Anki 并在插件管理器中启用

✅ 验证：确认插件已加载在 Anki 主界面 → 工具 → 插件，确认 Anki-Connect 显示"已启用"状态

[!WARNING] 常见误区：直接覆盖安装可能保留损坏的配置文件，建议先完全删除旧版本

[!TIP] 进阶技巧：使用 anki --debug 命令启动可获取更详细的插件加载日志

预防措施

定期备份 ~/.anki/addons21/anki-connect/config.json
升级 Anki 前先检查插件兼容性公告
启用 Anki 的自动更新功能：工具 → 首选项 → 自动更新

[API无响应]：如何恢复 localhost:8765 连接？

当调用 API 接口时出现"连接拒绝"或超时错误，无法与 Anki-Connect 建立通信。

问题定位

使用 curl http://localhost:8765 测试时返回"Connection refused"或长时间无响应。

核心原因

Anki-Connect 服务未启动
端口被占用或防火墙拦截
配置文件中的端口设置错误

分层解决方案

🔍 诊断：检查服务状态

确认 Anki 已启动且插件已启用
检查端口占用：lsof -i :8765 或 netstat -tulpn | grep 8765

底层原理：Anki-Connect 使用 HTTP 服务器监听本地端口，默认8765，通过 JSON-RPC 2.0 协议通信

✅ 验证：测试基础连接

# 健康检查请求
curl -X POST http://localhost:8765 -d '{"action": "version", "version": 6}'

操作验证点：应返回包含版本号的 JSON 响应

🔧 修复：配置端口与防火墙

修改配置文件 ~/.anki/addons21/anki-connect/config.json 中的"port"字段
添加防火墙例外：sudo ufw allow 8765/tcp
重启 Anki 使配置生效

✅ 验证：重新测试 API 连接使用上述 curl 命令确认返回正常响应

[!WARNING] 常见误区：修改端口后未重启 Anki，导致配置未生效

[!TIP] 进阶技巧：使用 nc -zv localhost 8765 快速测试端口连通性

预防措施

将常用 API 请求保存为 shell 脚本便于快速测试
使用端口扫描工具定期检查服务可用性
在配置文件中设置非默认端口时记录到备忘录

[卡片创建失败]：如何确保 API 提交的卡片正确入库？

通过 API 创建卡片后，Anki 收藏夹中未显示新卡片，或提示"模板错误"。

问题定位

API 调用返回成功状态，但实际未创建卡片，或卡片内容显示异常。

核心原因

卡片数据结构不符合模板要求
字段名称与模型定义不匹配
媒体文件引用路径错误

分层解决方案

🔍 诊断：检查 API 请求参数

{
  "action": "addNote",
  "version": 6,
  "params": {
    "note": {
      "deckName": "默认",
      "modelName": "基础",
      "fields": {
        "正面": "问题内容",
        "背面": "答案内容"
      },
      "tags": ["api-created"]
    }
  }
}