1. SQLite 中文乱码到底乱在哪从 PRAGMA encoding 到连接层字符集SQLite 中文乱码是很多做本地数据存储、桌面工具、Android 内置库、AI 工具链缓存时都会撞上的问题。它的典型表现是用某个 GUI 工具建库、写入中文一切正常换到代码里SELECT出来就变成????、锟斤拷、测试这类东西或者反过来代码写进去的中文在工具里打开是乱码。核心检索词就三个SQLite、中文乱码、编码。搞懂这三者的关系你就能一次性定位而不是每次查询都手动new String(bytes, GBK)去补丁。先说结论SQLite 本身对文本的存储编码是有明确规定的。数据库文件有一个encoding属性取值只能是UTF-8、UTF-16le、UTF-16be三种默认是UTF-8。这个属性在数据库第一次写入数据时确定之后不能通过PRAGMA encoding修改——你执行PRAGMA encoding UTF-8如果库已经建好并且有数据它只会返回当前值不会真的改。很多人以为执行一句 PRAGMA 就能转码这是第一个大坑。那乱码从哪来来自「写入端」和「读取端」对字节序列的解释不一致。SQLite 存的是字节它自己按声明的 encoding 去解释。问题出在建库工具比如老版本的 SQLite Administrator在写中文时把 GBK 字节直接塞进了声明为 UTF-8 的库里。SQLite 不知道你塞的是 GBK它按 UTF-8 去解析于是存进去的就是「非法 UTF-8 字节序列」。读取端Android 的Cursor.getString、Python 的sqlite3、Node 的better-sqlite3拿到这些非法字节按 UTF-8 解码失败就出现替换字符或乱码。连接层字符集没对齐比如 JDBC 连接串没指定characterEncoding或者 Python 打开文件时用了系统默认编码Windows 上常是 GBK。我试过最典型的复现用 SQLite Administrator 建一个库插入「测试中文」然后用 Python 读import sqlite3 conn sqlite3.connect(legacy.db) cur conn.cursor() cur.execute(SELECT name FROM info WHERE id?, (8332,)) print(cur.fetchone()) # 输出可能是 (测试ä¸æ–‡,) 或直接抛 UnicodeDecodeError这时候你去查PRAGMA encoding;它告诉你UTF-8但数据其实是 GBK 字节。这就是「声明与内容不符」。Android 里那段new String(cursor.getBlob(2), GBK)之所以能救回来就是因为它绕过了getString的 UTF-8 解码直接拿原始字节按 GBK 重新解释。但这只是查询时补救写入、索引、排序、LIKE全都会出问题所以必须根治。根治有两条路一是把库真正转成 UTF-8推荐二是在连接层统一字符集并保证写入端正确。下面会分别给出可复制的 PRAGMA、连接参数以及通过 TaoToken 统一 API 通道调用 AI 工具时的编码校验动作。适合谁看做 Android 本地库、桌面 SQLite 工具、Python/Node 数据脚本以及用 AI 工具链读写 SQLite 缓存的开发者。2. 用 TaoToken 统一 Key/API 通道做编码校验的前置准备在讲具体修复之前先解决一个现实问题现在很多 AI 工具Cline、Claude Code、Codex 类 CLI、各种 MCP 客户端会读写本地 SQLite 做缓存、会话记录、向量索引。这些工具调用链里编码一旦在某一环被错误转换乱码就会顺着 API 请求传下去最后你看到的是模型返回一堆问号。所以除了修库本身还要保证「调用链的编码传递」是对的。TaoToken 在这里的角色是统一 Key 和 API 通道你用一个 Key、一个 Base URL就能让不同工具走同一条通道编码校验也只需要在一处做。前置准备分三步。第一步拿到统一 Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。这个 Key 就是后面所有工具共用的凭证。第二步确认 Base URL。API 通道统一用 https://taotoken.net/api 注意这个地址不带 UTM 参数直接写进配置即可。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。Claude Code 相关接入参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 。第三步明确编码校验点。AI 工具调用链里编码会经过本地 SQLite 读取 → 内存字符串 → JSON 序列化 → HTTP 请求体 → 服务端解析。任何一环用了错误编码中文就会坏。我们要做的是在「本地读取」和「JSON 序列化」两处做校验。TaoToken 通道本身按 UTF-8 处理请求体所以只要你的客户端发出的 JSON 是合法 UTF-8通道就能正确传递。这里给一个最小校验脚本用 Python 验证你的 Key 和通道是否正常同时验证中文编码import json import urllib.request API_KEY 你的_TaoToken_Key BASE_URL https://taotoken.net/api payload { model: claude-3-5-sonnet, messages: [ {role: user, content: 请原样返回这句话中文编码测试} ] } data json.dumps(payload, ensure_asciiFalse).encode(utf-8) req urllib.request.Request( f{BASE_URL}/v1/messages, datadata, headers{ Content-Type: application/json; charsetutf-8, x-api-key: API_KEY, anthropic-version: 2023-06-01, }, methodPOST, ) with urllib.request.urlopen(req) as resp: body resp.read().decode(utf-8) print(body)注意ensure_asciiFalse和.encode(utf-8)这两个是保证中文不被转义成\uXXXX再被错误解码的关键。如果返回里「中文编码测试」完整出现说明通道和编码都正常。这一步做完你就有了一条可信的编码基准线再去排查 SQLite 本地乱码就能区分是「库的问题」还是「调用链的问题」。3. 可复制的 PRAGMA 与连接参数配置把库真正转成 UTF-8这一节是核心操作。目标把声明与内容不符的库真正转成 UTF-8并给出各语言连接层的字符集参数。先给结论表再给可复制片段。场景关键配置说明新建库PRAGMA encoding UTF-8;必须在建表前执行且库为空已有 GBK 内容库导出重导PRAGMA 无法改已有库编码Pythonconn.text_factory str配合正确编码读取Node better-sqlite3默认 UTF-8写入前确保 Buffer 是 UTF-8JDBC?characterEncodingUTF-8连接串必须带Androidnew String(blob, UTF-8)避免 getString 误解码新建库时正确顺序是PRAGMA encoding UTF-8; CREATE TABLE info (id INTEGER PRIMARY KEY, name TEXT, memo TEXT); INSERT INTO info (id, name, memo) VALUES (8332, 测试中文, 备注内容);注意PRAGMA encoding必须在第一次写入之前执行。如果你先建了表再执行它不会生效。验证PRAGMA encoding; -- 应返回 UTF-8对于已经存了 GBK 字节的旧库正确做法是「读出原始字节 → 按 GBK 解码 → 按 UTF-8 写入新库」。给一个 Python 迁移脚本import sqlite3 src sqlite3.connect(legacy_gbk.db) src.text_factory bytes # 关键拿原始字节不让它自动解码 dst sqlite3.connect(fixed_utf8.db) dst.execute(PRAGMA encoding UTF-8;) dst.execute(CREATE TABLE info (id INTEGER PRIMARY KEY, name TEXT, memo TEXT)) for row in src.execute(SELECT id, name, memo FROM info): rid, name_b, memo_b row name name_b.decode(gbk, errorsreplace) if isinstance(name_b, bytes) else name_b memo memo_b.decode(gbk, errorsreplace) if isinstance(memo_b, bytes) else memo_b dst.execute(INSERT INTO info VALUES (?,?,?), (rid, name, memo)) dst.commit() print(迁移完成)text_factory bytes是精髓它让 sqlite3 不自动按 UTF-8 解码你拿到原始字节后自己按 GBK 解。迁移完再查新库中文就正常了。连接层参数方面JDBC 连接串要写成jdbc:sqlite:/path/to/fixed_utf8.db?characterEncodingUTF-8Node 用 better-sqlite3 时写入前确保字符串是 JS 原生字符串内部 UTF-16序列化时按 UTF-8const Database require(better-sqlite3); const db new Database(fixed_utf8.db); db.pragma(encoding UTF-8); const stmt db.prepare(INSERT INTO info (id, name, memo) VALUES (?,?,?)); stmt.run(8332, 测试中文, 备注内容); console.log(db.prepare(SELECT name FROM info WHERE id?).get(8332));Android 侧如果暂时不能迁移库至少统一用 UTF-8 读取别再混用 GBKCursor cursor db.rawQuery(SELECT name, memo FROM info WHERE id?, new String[]{8332}); if (cursor ! null cursor.moveToFirst()) { String name new String(cursor.getBlob(0), StandardCharsets.UTF_8); String memo new String(cursor.getBlob(1), StandardCharsets.UTF_8); cursor.close(); }如果你的 AI 工具链通过 TaoToken 通道读写 SQLite 缓存建议在工具配置里显式声明编码。以 Cline 类工具的 MCP 配置为例三件套要写全{ mcpServers: { sqlite-helper: { command: python, args: [sqlite_mcp.py], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: 你的_TaoToken_Key, TAOTOKEN_MODEL: claude-3-5-sonnet, PYTHONIOENCODING: utf-8 } } } }PYTHONIOENCODINGutf-8是很多人忽略的Windows 上 Python 子进程默认用 GBK 输出MCP 通信时中文就会坏。加上这一行编码传递就稳了。Base URL、Key、Model ID 三件套齐全工具才能正确走 TaoToken 通道。4. 验证请求与成功结果从乱码到正常中文的完整对照配置改完必须验证否则你不知道是修好了还是碰巧。这一节给一套可复现的验证流程包含乱码复现、修复、结果对照。先复现乱码。用旧库执行import sqlite3 conn sqlite3.connect(legacy_gbk.db) print(conn.execute(PRAGMA encoding;).fetchone()) print(conn.execute(SELECT name FROM info WHERE id8332).fetchone())典型输出(UTF-8,) (测试ä¸æ–‡,)PRAGMA说是 UTF-8但内容是乱码这就是声明与内容不符的铁证。修复后查新库import sqlite3 conn sqlite3.connect(fixed_utf8.db) print(conn.execute(PRAGMA encoding;).fetchone()) print(conn.execute(SELECT name, memo FROM info WHERE id8332).fetchone())期望输出(UTF-8,) (测试中文, 备注内容)中文完整、无替换字符说明库层面修好了。接着验证调用链。用第 2 节的脚本把从 SQLite 读出的中文拼进请求走 TaoToken 通道import json, sqlite3, urllib.request conn sqlite3.connect(fixed_utf8.db) name, memo conn.execute(SELECT name, memo FROM info WHERE id8332).fetchone() payload { model: claude-3-5-sonnet, messages: [{role: user, content: f请确认这两个词是否正常{name} / {memo}}] } data json.dumps(payload, ensure_asciiFalse).encode(utf-8) req urllib.request.Request( https://taotoken.net/api/v1/messages, datadata, headers{ Content-Type: application/json; charsetutf-8, x-api-key: 你的_TaoToken_Key, anthropic-version: 2023-06-01, }, methodPOST, ) with urllib.request.urlopen(req) as resp: print(resp.read().decode(utf-8))成功结果里模型会原样引用「测试中文 / 备注内容」没有问号、没有\u乱码。这一步同时验证了 SQLite 读取、JSON 序列化、HTTP 传输、TaoToken 通道解析四个环节的编码一致性。再补一个边界验证写入含 emoji 和生僻字的内容确认 UTF-8 四字节字符也没问题。conn.execute(INSERT INTO info VALUES (?,?,?), (9001, 测试, 野家)) conn.commit() print(conn.execute(SELECT name, memo FROM info WHERE id9001).fetchone())期望输出(测试, 野家)。如果这里坏了说明你的连接层还在用非 UTF-8 编码回去检查text_factory和连接串。验证通过后建议把校验脚本固化成 CI 或启动自检每次工具链启动时跑一遍避免某次环境变更又把编码搞坏。对于长期跑 Agent、需要频繁读写 SQLite 缓存的场景可以考虑用 Coding Plan 统一管理调用额度减少多 Key 切换带来的配置漂移。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth编码问题往往和调用错误混在一起报错信息会误导你。这一节对照真实报错逐个拆。401 Unauthorized。走 TaoToken 通道时出现 401先查 Key 是否正确、是否带了x-api-key或Authorization头。注意编码不会直接导致 401但如果你把 Key 存在 SQLite 里、读取时编码坏了Key 字符串就会变成乱码服务端自然拒绝。排查顺序先PRAGMA encoding确认库正常再打印 Key 的前后各 4 位确认没被污染。local proxy failed。这个报错通常出现在工具配置了本地代理但代理没起来或者 Base URL 写错。检查你的配置里 Base URL 是不是https://taotoken.net/api不要多写/v1或少写/api。同时确认没有残留的本地代理环境变量如HTTP_PROXY指向一个不存在的端口。编码层面如果配置文件本身是 GBK 保存的读出来的 URL 可能带乱码用 UTF-8 重新保存配置文件。reading choices 相关报错。这类报错多出现在 OpenAI 兼容格式的响应解析里工具期望choices[0].message.content但服务端返回了别的结构。如果你用的是 Anthropic 格式/v1/messages响应是content数组不是choices。检查你的工具用的是哪种协议Base URL 和端点要匹配。编码坏掉时JSON 解析会先失败报错可能伪装成「reading choices」实际是响应体不是合法 UTF-8 JSON。用resp.read().decode(utf-8)先看原始内容。OAuth 相关报错。Claude Code 类工具可能走 OAuth 流程如果配置里混用了 OAuth 和 API Key会冲突。走 TaoToken 通道时统一用 API Key不要同时开 OAuth。检查~/.claude/settings.json或对应配置文件确保认证方式唯一。如果之前登录过 OAuth清掉旧凭证再配 Key。再补几个 SQLite 专属的坑PRAGMA encoding返回UTF-8但数据乱码说明写入端塞了非 UTF-8 字节必须迁移不能靠 PRAGMA 改。LIKE %中文%查不到编码不一致导致索引和比较失效迁移后重建索引。AndroidgetString抛异常改用getBlob 显式 UTF-8 解码。Windows 命令行sqlite3.exe显示乱码是终端代码页问题执行chcp 65001切到 UTF-8不代表库坏了。排查时记住一个原则先确认字节再确认解释。用hex()看原始字节SELECT hex(name) FROM info WHERE id8332;「测试中文」的正确 UTF-8 字节是E6B58BE8AF95E4B8AD E69687。如果你看到的是B2E2CAD4开头那就是 GBK 字节库需要迁移。这个方法能一锤定音不用猜。6. 把编码校验固化进你的 AI 工具链修好一个库只是开始真正省事的是把编码校验变成流程的一部分。我的做法是所有涉及 SQLite 的项目建库脚本第一行永远是PRAGMA encoding UTF-8;所有连接层显式声明 UTF-8所有跨进程通信MCP、子进程、HTTP都设PYTHONIOENCODINGutf-8或等价配置。这样新库不会再出问题旧库用第 3 节的迁移脚本批量处理。对于走 TaoToken 通道的 AI 工具建议把第 2 节的校验脚本做成启动自检每次工具链启动跑一次确认 Key、Base URL、Model ID 三件套和中文编码都正常。模型对话入口可以用来快速验证通道接入文档里有各语言的完整示例Coding Plan 适合需要长期跑 Agent、频繁读写本地缓存的场景。把这些动作固化下来中文乱码就从「每次都要救火」变成「一次配置长期稳定」。