1. 从一次 scan 遍历翻车说起cursor 为什么成了乱码Java 里用 Jedis 做 Redis 的 scan 遍历本来是想替代 keys 命令避免在大 key 量下把单线程的 Redis 卡住。结果第一轮 scan 正常返回第二轮直接把scanResult.getStringCursor()拿到的字符串塞回jedis.scan(cursor, params)客户端立刻抛出JedisDataException: ERR invalid cursor打印出来的 cursor 是类似㠵㔰这种看不懂的字符。这个现象的核心不是 Redis 服务端坏了而是 Java 客户端在字节与字符串之间做了一次有损转换。scan 命令的游标在 Redis 协议里本质是一个二进制安全的字节序列服务端只保证它是「上一轮遍历结束的位置」并不承诺它是人类可读的十进制数字。Jedis 的ScanResult内部用byte[] cursor保存原始游标getStringCursor()则通过SafeEncoder.encode(cursor)把它按Protocol.CHARSET默认 UTF-8解码成 String。如果项目源码文件本身是 UTF-16 之类的编码编译和运行链路里对字节的解读就会错位于是你看到的 cursor 就成了乱码再传回去自然被 Redis 判定为非法游标。这篇内容面向正在用 Java Jedis 做 scan 遍历、并且遇到 cursor 乱码或ERR invalid cursor的开发者。我会把排查路径拆成可复制的步骤先确认编码边界再给出统一的 Key/API 通道配置骨架最后用一段最小验证代码确认游标能稳定回传。整个过程围绕 TaoToken 的统一 Key 通道来组织方便你在多环境、多客户端之间保持一致。2. TaoToken 前置统一 Key 通道与配置骨架在动手改代码之前先把「连哪个 Redis、用哪套凭据」这件事固定下来。很多 cursor 乱码的排查会被环境差异干扰本地连的是 A 实例测试环境连的是 B 实例凭据和编码配置各不相同最后定位到的根因其实是配置漂移。TaoToken 的统一 Key 通道可以把模型调用、编码辅助、接口调试收敛到同一套入口减少这种漂移。你需要先拿到一个可用的 API Key入口在控制台的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 之后接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想先验证模型侧的行为可以直接用模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期做编码和 Agent 任务的话Coding Plan 更适合https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI 基址统一用https://taotoken.net/api下面给出一份config.toml骨架把通道地址、Key 占位和超时参数集中管理。注意 Key 不要写死在源码里用环境变量注入# config.toml [channel] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_ms 15000 retry 2 [redis] host 127.0.0.1 port 6379 db 0 # 关键显式声明客户端字符集避免依赖平台默认值 charset UTF-8 scan_count 200对应的settings.json骨架用于 IDE 或构建工具侧统一源码编码防止 UTF-16 混入{ channel: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY }, editor: { filesEncoding: UTF-8, filesAutoGuessEncoding: false }, java: { compilerEncoding: UTF-8, runtimeEncoding: UTF-8 } }注意filesAutoGuessEncoding设为 false 是刻意的。自动猜测编码在混合编码项目里经常猜错反而让 cursor 乱码更难复现。3. 可复制配置把编码边界钉死在 UTF-8cursor 乱码的根因在字节到字符串的解码环节所以配置的重点是「全链路 UTF-8」。下面按 JVM、构建工具、Jedis 客户端三层给出可复制的配置。3.1 JVM 与构建工具编码Maven 的pom.xml里显式声明源码编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /propertiesGradle 则在build.gradle里加tasks.withType(JavaCompile) { options.encoding UTF-8 }启动 JVM 时再补一刀确保运行时默认字符集不漂移java -Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8 -jar your-app.jar3.2 Jedis 连接与 scan 参数Jedis 侧的关键是不要依赖getStringCursor()的隐式解码而是直接操作字节游标。下面这段代码把 scan 遍历写成可复用的方法import redis.clients.jedis.Jedis; import redis.clients.jedis.ScanParams; import redis.clients.jedis.ScanResult; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; public class ScanSafeDemo { public static ListString scanKeys(Jedis jedis, String pattern) { ListString keys new ArrayList(); ScanParams params new ScanParams(); params.match(pattern); params.count(200); // 用 byte[] 游标绕开 String 解码 byte[] cursor ScanParams.SCAN_POINTER_START_BINARY; while (true) { ScanResultbyte[] result jedis.scan(cursor, params); Listbyte[] batch result.getResult(); if (batch ! null) { for (byte[] raw : batch) { keys.add(new String(raw, StandardCharsets.UTF_8)); } } cursor result.getCursorAsBytes(); if (cursor.length 1 cursor[0] 0) { break; } } return keys; } }这里有两个要点。第一ScanParams.SCAN_POINTER_START_BINARY是字节形式的起始游标0避免字符串转换。第二result.getCursorAsBytes()直接拿原始字节下一轮再传回去中间不经过任何字符集解码乱码自然无从产生。如果你必须用getStringCursor()那就确保Protocol.CHARSET与源码编码一致。可以在初始化时打印确认System.out.println(Protocol.CHARSET redis.clients.jedis.Protocol.CHARSET); System.out.println(file.encoding System.getProperty(file.encoding));两者都应该是UTF-8。只要有一个是UTF-16或平台默认值cursor 就有概率变成乱码。3.3 参数对照表配置项推荐值作用project.build.sourceEncodingUTF-8编译期源码编码-Dfile.encodingUTF-8运行时默认字符集Protocol.CHARSETUTF-8Jedis 解码游标所用字符集scan 游标类型byte[]避免字符串解码损耗scan_count200 左右单次遍历槽位数量非返回条数注意COUNT 200不是「返回 200 个 key」而是限定服务端单次遍历的字典槽位数量实际返回条数可能远小于 200。这一点在排查「为什么扫不全」时经常被误解。4. 验证请求确认游标能稳定回传配置改完用一段最小验证代码确认游标在第二轮、第三轮都能正确回传。先往 Redis 里塞一批测试 keyredis-cli -h 127.0.0.1 -p 6379 SET test1111:a 1 SET test1111:b 2 SET test1111:c 3 SET test2222:d 4然后跑下面的验证类import redis.clients.jedis.Jedis; import redis.clients.jedis.ScanParams; import redis.clients.jedis.ScanResult; import java.nio.charset.StandardCharsets; public class ScanVerify { public static void main(String[] args) { try (Jedis jedis new Jedis(127.0.0.1, 6379)) { ScanParams params new ScanParams(); params.match(test1111*); params.count(10); byte[] cursor ScanParams.SCAN_POINTER_START_BINARY; int round 0; while (true) { round; ScanResultbyte[] result jedis.scan(cursor, params); System.out.println(round round , cursorBytes new String(result.getCursorAsBytes(), StandardCharsets.UTF_8) , keys result.getResult().size()); cursor result.getCursorAsBytes(); if (cursor.length 1 cursor[0] 0) { System.out.println(scan finished, total rounds round); break; } } } } }预期输出类似round1, cursorBytes49152, keys3 round2, cursorBytes0, keys0 scan finished, total rounds2如果cursorBytes打印出来是㠵㔰这类乱码说明字节到字符串的解码仍然错位回到第 3 节检查file.encoding和Protocol.CHARSET。如果第二轮直接抛ERR invalid cursor说明传回去的游标字节已经被破坏重点检查是否在中间做了new String(cursor)再getBytes()的往返转换。验证通过后再跑一次删除逻辑确认遍历到的 key 能被正确清理for (String key : scanKeys(jedis, test1111*)) { jedis.del(key); }5. 本篇常见错排查5.1ERR invalid cursor反复出现最常见的原因是游标在字符串和字节之间往返转换。比如先getStringCursor()拿到 String再cursor.getBytes()传回去中间如果字符集不一致字节序列就变了。解决方式是全程用byte[]游标或者确保Protocol.CHARSET、file.encoding、源码编码三者一致。5.2 源码文件是 UTF-16 导致乱码有些 IDE 默认把新建文件存成 UTF-16编译后字符串常量在运行时的字节表现就和 UTF-8 不一致。检查方式是在文件头看 BOM或者用file -i YourClass.java查看编码。统一改成 UTF-8 后重新编译。5.3 scan 扫不全 keyscan 是增量遍历遍历期间如果有 key 被增删结果不保证完整。另外COUNT只是槽位提示不是返回条数。要扫全必须循环到游标为0不能只扫一轮就停。5.4 多实例环境下 cursor 串了如果本地和测试环境连的是不同 Redis 实例游标只在同一个实例内有意义。把游标从 A 实例拿到 B 实例用必然报ERR invalid cursor。用 TaoToken 统一 Key 通道固定实例地址能减少这类串环境问题。5.5 用getResult()正常但getStringCursor()乱码这正好说明问题出在 cursor 的解码路径上。getResult()返回的是ListString内部对每个元素单独解码而 cursor 是单个字节序列解码时机和字符集设置不同。两者表现不一致恰恰是编码边界问题的典型信号。6. 把通道和编码一起固定下来排查到这一步你会发现 cursor 乱码从来不是 Redis 单方面的问题而是 Java 客户端在字节与字符串边界上的处理问题。把file.encoding、Protocol.CHARSET、源码编码统一成 UTF-8并且 scan 游标全程用byte[]这类报错基本不会再出现。如果你还在多环境之间来回切换建议把 Key 和通道地址也一起收敛。API Keys 页面用来管理凭据https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档里有各语言客户端的配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite需要快速验证模型行为时用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite长期做编码和 Agent 任务就上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后留一个实用习惯每次新建 Java 项目先在pom.xml或build.gradle里把编码钉死再写第一行业务代码。cursor 乱码这种问题防比查省事得多。