Anki-Connect 故障排除指南

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

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

问题定位

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

核心原因

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

分层解决方案

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

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

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

✅ 验证：查看 Anki 日志

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

🔧 修复：重新安装插件

1. 从插件目录删除现有文件：rm -rf ~/.anki/addons21/anki-connect
2. 克隆仓库：git clone https://gitcode.com/gh_mirrors/an/anki-connect ~/.anki/addons21/anki-connect
3. 重启 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 服务未启动
• 端口被占用或防火墙拦截
• 配置文件中的端口设置错误

分层解决方案

🔍 诊断：检查服务状态

1. 确认 Anki 已启动且插件已启用
2. 检查端口占用：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 响应

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

1. 修改配置文件 ~/.anki/addons21/anki-connect/config.json 中的"port"字段
2. 添加防火墙例外：sudo ufw allow 8765/tcp
3. 重启 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"]
    }
  }
}

操作验证点：确认 modelName 和 fields 与 Anki 中的模型定义完全一致

✅ 验证：检查 Anki 模型配置

1. 打开 Anki → 工具 → 管理笔记类型
2. 选择对应模型，确认字段名称与 API 请求中的 fields 键名完全一致

🔧 修复：调整请求参数

1. 修正字段名称拼写错误
2. 添加必填字段内容
3. 确保 deckName 存在于 Anki 中

✅ 验证：确认卡片创建成功

1. 在 Anki 中切换到对应牌组
2. 搜索标签 tag:api-created 查找新创建的卡片

[!WARNING] 常见误区：使用中文标点符号作为字段名，导致匹配失败

[!TIP] 进阶技巧：先使用 "modelNames" API 获取所有模型名称，确保参数正确

预防措施

• 创建专用 API 测试牌组，避免影响正式卡片
• 实现请求参数验证机制，提前检测错误
• 定期导出模型结构文档，作为 API 开发参考

[批量操作超时]：如何优化大量卡片创建效率？

当一次性创建数百张卡片时，API 响应缓慢或返回超时错误。

问题定位

批量创建卡片时出现"504 Gateway Timeout"或响应时间超过30秒。

核心原因

• 单次请求包含过多卡片
• 卡片包含大型媒体文件
• Anki 数据库写入性能瓶颈

分层解决方案

🔍 诊断：分析请求规模 检查批量请求中的卡片数量，超过50张通常需要优化处理。

底层原理：Anki-Connect 处理每张卡片需进行数据库事务，大量并发操作会导致锁等待

✅ 验证：测试不同批次大小 尝试不同数量的批量请求（10/20/50张），记录响应时间临界点。

🔧 修复：实施分批处理

1. 将大批量拆分为20张/批的小请求
2. 每批之间添加1-2秒延迟
3. 实现请求重试机制处理临时失败

✅ 验证：监控系统资源 使用 top 命令观察 Anki 进程的 CPU 和内存占用，确保在安全范围内

[!WARNING] 常见误区：无限制提高并发请求数量，导致 Anki 进程崩溃

[!TIP] 进阶技巧：使用"createDeck" API 预先创建专用工作牌组，减少数据库锁竞争

预防措施

• 建立请求频率限制机制，避免突发流量
• 非高峰时段执行批量操作
• 定期清理测试卡片，保持数据库优化状态