runqueryonbackgroundthread close cursor! 报错排查：Cursor 泄漏定位与 TaoToken 配置骨架-平芜编程栈

1. 先搞清楚 runqueryonbackgroundthread close cursor! 到底在报什么

runqueryonbackgroundthread close cursor!这个报错，通常出现在你用了CursorAdapter（尤其是SimpleCursorAdapter或自定义CursorAdapter）配合LoaderManager、startManagingCursor或手动在后台线程跑查询的场景里。它的字面意思是：系统在后台线程执行runQueryOnBackgroundThread时，发现你传入的 Cursor 已经被关闭了，于是抛出IllegalStateException或直接打印close cursor!的警告日志。

很多同学第一次遇到它，是在“杀死进程、清除缓存”之后重新打开 App，列表页直接闪退或者白屏。原因并不神秘：Cursor 的生命周期和 Activity/Fragment 的生命周期没有对齐。后台线程还在跑查询，主线程已经把 Cursor 关掉了；或者 Adapter 换了新 Cursor，旧 Cursor 没被正确释放，系统在后台线程复用时踩到了已关闭的对象。

这个报错适合谁看？适合所有还在用CursorAdapter做列表、又不想把整个数据层重写成 Room + Flow 的 Android 开发者。你不需要推翻现有架构，只要把 Cursor 的“谁创建、谁持有、谁关闭”这三件事理清楚，再配一套统一的 Key/API 通道做联调验证，就能一次性消除它。下面我会先给可复制的 Cursor 关闭检查清单，再给 Logcat 过滤命令，最后给 TaoToken 在settings.json里的配置骨架和验证动作。

2. TaoToken 前置：统一 Key/API 通道，让联调不再靠猜

排查 Cursor 泄漏时，最怕的是“改完不知道有没有生效”。如果你同时还在调模型接口、跑 Agent 或做代码补全，建议先把 API 通道统一到 TaoToken，这样日志、Key、Base URL 都是一套，验证动作可复用。

TaoToken 是一个统一的大模型 API 通道，官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （这个不加 UTM）。它解决的是“多个模型、多个 Key、多个 Base URL 来回切”的问题：你只需要在控制台生成一个 Key，然后在settings.json或环境变量里指向同一个 API 地址，就能在模型对话、Coding Plan、Agent 之间复用。

对本次排查来说，TaoToken 的作用是：当你用 Logcat 确认 Cursor 已经不再泄漏后，可以用同一个 Key 去请求模型对话接口，确认“通道连通”，避免把“网络问题”误判成“Cursor 问题”。控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你长期做编码和 Agent，可以看 Coding Plan： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

注意：TaoToken 是 API 通道，不是编辑器替代品，也不做任何灰色中转。你仍然在 Android Studio 里写代码，只是把模型请求指向统一入口。

3. 可复制配置：Cursor 关闭检查清单 + settings.json 骨架

3.1 Cursor 关闭检查清单（逐条对照）

先给结论：runqueryonbackgroundthread close cursor!的根因，90% 是下面五条里至少一条没做到。

第一，changeCursor里必须关闭旧 Cursor。很多人只调super.changeCursor(newCursor)，忘了旧的那个。正确写法是先取旧 Cursor，再判断是否同一个对象，不同才关。

@Override public void changeCursor(Cursor newCursor) { Cursor oldCursor = getCursor(); super.changeCursor(newCursor); if (oldCursor != null && oldCursor != newCursor) { oldCursor.close(); } }

第二，如果你还在用activity.startManagingCursor(cursor)，要确认 Activity 销毁时它会被自动关闭。但startManagingCursor已废弃，推荐改用LoaderManager或CursorLoader，让 Loader 自己管生命周期。

第三，后台线程查询结束后，Cursor 的持有者必须是 Adapter 或 Loader，不能是局部变量。局部变量出了作用域没人关，后台线程再访问就是已关闭状态。

第四，onDestroy或onDestroyView里要显式adapter.changeCursor(null)，把 Adapter 持有的 Cursor 释放掉，再让 Loader 去关。

第五，swapCursor和changeCursor不要混用。swapCursor返回旧 Cursor 但不关闭，需要你自己关；changeCursor会帮你关。混用就会出现“以为关了其实没关”或“关了两次”。

3.2 Logcat 过滤命令

排查阶段，先把日志过滤出来，别被其他噪音淹没。在终端里执行：

adb logcat -c adb logcat | grep -iE "runqueryonbackgroundthread|close cursor|CursorWindow|StaleDataException"

如果你想按进程过滤，先拿 PID：

adb shell pidof com.example.yourapp adb logcat --pid=$(adb shell pidof com.example.yourapp) | grep -iE "cursor|runquery"

Windows 下把grep换成findstr /i。实测下来，close cursor!往往和CursorWindow的分配日志挨在一起，看到CursorWindow: Window is full就要警惕泄漏。

3.3 TaoToken settings.json 配置骨架

下面这份骨架可以直接复制到你的settings.json（比如 Claude Code 或兼容工具的配置目录）。把YOUR_TAOTOKEN_KEY换成你在 API Keys 页面生成的 Key。

{ "api": { "base_url": "https://taotoken.net/api", "api_key": "YOUR_TAOTOKEN_KEY", "timeout_ms": 60000, "max_retries": 2 }, "models": { "default": "claude-sonnet-4-20250514", "fallback": "gpt-4o-mini" }, "logging": { "level": "info", "log_requests": true } }

如果你用的是环境变量方式，等价写法是：

export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="YOUR_TAOTOKEN_KEY"

提示：base_url只写https://taotoken.net/api，不要在后面拼/v1或/chat/completions，具体路径由客户端按模型协议补全。写错路径会返回 404，容易被误判成 Key 失效。

4. 验证请求与成功结果：确认 Cursor 不再泄漏、通道连通

4.1 验证 Cursor 是否还会泄漏

改完changeCursor后，按这个流程走一遍：打开列表页 → 快速旋转屏幕三次 → 按 Home 键再回来 → 进入详情页再返回 → 反复五次。然后看 Logcat：

adb logcat -d | grep -iE "close cursor|runqueryonbackgroundthread" | wc -l

如果输出是0，说明这一轮没有触发。再配合adb shell dumpsys meminfo com.example.yourapp | grep -i cursor看 Cursor 数量是否稳定。稳定不增长，基本可以确认泄漏点已堵住。

4.2 验证 TaoToken 通道连通

用curl发一个最小请求，确认 Key 和 Base URL 都对：

curl -s -X POST "https://taotoken.net/api/v1/messages" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_TAOTOKEN_KEY" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'

成功时你会看到类似{"id":"msg_...","content":[{"type":"text","text":"pong"}]}的返回。如果返回 401，检查 Key 是否复制完整；返回 404，检查base_url是否多写了路径；返回超时，检查timeout_ms是否太短。

你也可以直接在模型对话页面做一次可视化验证： https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。输入一句话，能正常返回就说明通道没问题。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各协议的路径说明。

5. 本篇常见错排查：close cursor! 反复出现的六个坑

第一个坑：在changeCursor里调了oldCursor.close()，但oldCursor == newCursor时也关了。这会把正在用的 Cursor 关掉，后台线程立刻报close cursor!。所以判断条件必须是oldCursor != newCursor。

第二个坑：CursorLoader的onLoadFinished里调adapter.changeCursor(cursor)，但onLoaderReset里忘了调adapter.changeCursor(null)。Loader 重置时旧 Cursor 会被框架关闭，Adapter 还拿着引用，后台线程一访问就炸。

第三个坑：在子线程里手动cursor.close()，主线程的 Adapter 还在用。Cursor 不是线程安全的，关闭动作必须和持有者在同一生命周期里。

第四个坑：swapCursor返回的旧 Cursor 没关。swapCursor的语义是“换但不关”，返回值就是旧 Cursor，你必须自己close()。

第五个坑：startManagingCursor和手动close()同时用，导致双重关闭。已废弃的startManagingCursor会在 Activity 销毁时自动关，你再手动关一次就冲突。

第六个坑：把close cursor!当成网络错误去查 TaoToken 配置。这个报错和 API 通道无关，先看 Cursor 生命周期，再看通道。如果你确认 Cursor 已经干净，但请求还是失败，再去 API Keys 页面核对 Key： https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

注意：不要为了“快速消除报错”而把close()全部注释掉。那样只是把异常藏起来，CursorWindow 会持续增长，最终 OOM。

6. 下一步：把 Cursor 检查清单固化，通道统一到 TaoToken

把第 3.1 节的五条检查清单贴到你的代码 Review 模板里，每次改 Adapter 都过一遍。Logcat 过滤命令存成 shell 脚本，排查时直接跑。TaoToken 的settings.json骨架放在项目根目录的tools/下，团队共用一份，Key 走环境变量注入，不要提交到 Git。

如果你还在做长期编码和 Agent 任务，建议把通道切到 Coding Plan： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它和本次的 Cursor 排查不冲突，只是让你在验证“通道连通”时少配几套 Key。Claude Code 相关接入说明在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，需要的话按文档把base_url指到https://taotoken.net/api即可。

最后留一个我踩过的坑：close cursor!有时候不是你的代码直接引起的，而是某个第三方库在ContentProvider里返回了已关闭的 Cursor。遇到这种情况，先用adb shell dumpsys activity providers看哪个 Provider 被调用，再顺着调用栈找。把 Cursor 的创建和关闭都收拢到 Loader 或 Adapter 一处，问题就不会再反复。