Anki-Connect 故障诊断与解决方案手册

⚠️ 插件部署异常

现象特征

Anki启动后插件未激活或提示加载失败

技术原理简析

Anki插件系统通过扫描addons21目录加载扩展，Python依赖缺失或文件权限问题会导致加载失败

技术背景

Anki插件采用Python开发，需符合特定目录结构，核心逻辑通过__init__.py暴露给主程序。插件加载失败通常与环境依赖或文件完整性相关。

分级解决方案

基础方案

🔍 检查Anki版本兼容性（需2.1.50+版本） 🔧 执行标准安装流程：

1. 打开Anki → 工具 → 插件 → 获取插件
2. 输入插件代码1788670778
3. 重启Anki验证插件列表状态 ✅ 确认插件管理器中"Anki-Connect"显示为启用状态

进阶方案

🔍 检查插件目录完整性 🔧 手动部署流程：

1. 终端执行：git clone https://gitcode.com/gh_mirrors/an/anki-connect ~/.anki/addons21/anki-connect
2. 验证目录结构：~/.anki/addons21/anki-connect/plugin/下需包含__init__.py等核心文件
3. 重启Anki并查看日志（帮助 → 查看日志） ✅ 日志中应出现"Anki-Connect server started"字样

专家方案

🔍 分析Python环境依赖 🔧 环境修复步骤：

1. 检查Python版本（需3.8+）：python --version
2. 安装缺失依赖：cd ~/.anki/addons21/anki-connect && pip install -r requirements.txt
3. 验证端口可用性：netstat -tuln | grep 8765 ✅ 使用tox命令运行测试套件验证环境完整性

💡 避坑指南：Windows用户需注意路径中反斜杠转义问题，建议使用WSL或Git Bash执行命令行操作

🔌 接口通信故障

现象特征

API请求无响应或返回4xx/5xx错误代码

技术原理简析

API调用就像餐厅点餐，URL是地址（localhost:8765），参数是菜单，服务器未响应通常是通信链路中断

技术背景

Anki-Connect采用HTTP服务器模式，默认监听本地8765端口，支持JSON-RPC 2.0协议，跨域请求需特殊配置。

分级解决方案

基础方案

🔍 检查服务状态 🔧 基础排查流程：

1. 确认Anki已启动且插件已加载
2. 验证默认端口[8765-8775]可用性：访问http://localhost:8765
3. 若提示端口占用→修改config.json中的"port"值，否则直接下一步
4. 关闭防火墙或添加端口例外规则 ✅ 使用curl测试基础连接：curl http://localhost:8765 -X POST -d '{"action":"version","version":6}'

进阶方案

🔍 分析请求参数与格式 🔧 请求调试步骤：

1. 启用详细日志：修改config.json中"log"为true
2. 使用Postman构造标准请求：

   {
     "action": "createDeck",
     "version": 6,
     "params": {"deck": "测试牌组"}
   }
   

3. 检查请求头设置：Content-Type必须为application/json ✅ 查看~/.anki/addons21/anki-connect/plugin/logs目录下的请求记录

专家方案

🔍 网络环境深度诊断 🔧 高级排查：

1. 使用wireshark捕获本地8765端口流量
2. 检查config.json中"webCorsOriginList"配置，添加客户端域名
3. 测试替代通信方式：启用WebSocket支持（需修改web.py） ✅ 通过telnet手动建立连接：telnet localhost 8765

💡 避坑指南：API版本号必须与文档匹配，v6是当前稳定版，使用v1会导致大部分功能不可用

📝 卡片操作异常

现象特征

API返回成功但卡片未实际创建或内容异常

技术原理简析

卡片创建需通过Anki内部数据接口，涉及牌组、模板、字段多层验证，任一环节失败都会导致静默错误

技术背景

Anki使用SQLite数据库存储卡片数据，卡片创建需经过模板渲染、字段验证、数据库事务等多个步骤，任何验证失败都会回滚整个操作。

分级解决方案

基础方案

🔍 验证卡片数据格式 🔧 数据检查流程：

1. 确认必填字段完整性：模型ID、牌组名称、字段内容
2. 使用基础创建接口测试：

   {
     "action": "addNote",
     "version": 6,
     "params": {
       "note": {
         "deckName": "默认",
         "modelName": "基础",
         "fields": {"正面": "测试问题", "背面": "测试答案"},
         "tags": ["test"]
       }
     }
   }
   

3. 若返回成功但无卡片→检查目标牌组是否存在，否则检查字段名称是否匹配模型 ✅ 在Anki界面手动搜索"test"标签验证结果

进阶方案

🔍 模型与字段映射检查 🔧 模型调试步骤：

1. 获取模型详情：调用"modelNames"和"modelFieldNames"接口
2. 验证字段名称拼写和大小写（区分大小写）
3. 检查卡片模板是否包含所有字段引用
4. 尝试使用已知有效模型：{"modelName": "Basic"} ✅ 通过"findNotes"接口搜索创建记录：{"query": "tag:test"}

专家方案

🔍 数据库与事务诊断 🔧 深度排查：

1. 启用Anki调试模式：按住Shift启动Anki
2. 检查数据库完整性：sqlite3 ~/.local/share/Anki2/User\ 1/collection.anki2 "PRAGMA integrity_check"
3. 分析插件源码：查看plugin/edit.py中的addNote实现
4. 使用事务日志：修改web.py添加详细事务日志 ✅ 直接操作数据库验证插入语句

💡 避坑指南：中文牌组名称需使用UTF-8编码，API调用时无需转义，但需确保客户端编码正确