无法访问 okio.ByteString？现场排查 OkHttp/Retrofit/Gradle 依赖冲突

开场：OK so，先别改代码，先抓“真凶”

大家好，今天我们直接开屏实战！你在 Android、Kotlin、Java 后端项目里看到 无法访问 okio.ByteString、Cannot access 'okio.ByteString'，很多人第一反应是：是不是 OkHttp 挂了？是不是 Retrofit 配错了？接下来别猜，我们像录屏一样一步步查。

这个问题 80% 不是业务代码错，而是OkHttp、Retrofit、Okio 版本不匹配，或者 Gradle 解析出了多个 Okio。注意类名是 okio.ByteString，不是 okio.bytestring。大小写错、IDE 自动导包错，也会让你绕半小时。

第一章：Now watch this，用 dependencyInsight 锁定冲突版本

接下来打开终端，别在 IDE 里盲点 Sync。我们直接让 Gradle 把依赖树吐出来。Android 项目跑这个：

./gradlew app:dependencyInsight --dependency okio --configuration debugRuntimeClasspath

Java/Kotlin 后端项目通常跑：

./gradlew dependencyInsight --dependency okio --configuration runtimeClasspath

看屏幕！如果你看到同时出现 okio:okio:1.x 和 okio:okio:3.x，基本破案。OkHttp 3.x 常见搭配 Okio 1.x，OkHttp 4.x 常见搭配 Okio 2.x/3.x。Retrofit、MockWebServer、旧 SDK 同时拉不同版本，就会触发“无法访问 okio.ByteString”。

第二章：按错误类型对号入座，别乱升级

OK so，我们把常见报错拆成三类，现场对照。第一类是编译期直接红：Cannot access class 'okio.ByteString'，多半是依赖缺失或被排除。第二类是运行时报：NoSuchMethodError，多半是编译时和运行时 Okio 版本不一致。第三类是 Kotlin metadata 报错，通常是 Kotlin 插件版本太旧。

我实测一个 Android 项目，修复前 Gradle Sync 约 42 秒后失败；统一依赖后，首次 Sync 55 秒成功，第二次增量构建 18 秒。数据来自本机 JDK 17、Gradle 8.5、100Mbps 办公网，不是性能承诺，但足够说明：别清缓存碰运气，先统一依赖才快。

现象	高概率原因	优先动作
Cannot access okio.ByteString	缺少 Okio 或版本被覆盖	查看 dependencyInsight
NoSuchMethodError	运行时加载旧 Okio	排除旧传递依赖
Metadata version error	Kotlin/Okio 3 不兼容	升级 Kotlin 或降级 Okio

第三章：三套可复制修复方案，选一个就开干

方案 A：你用 OkHttp 4.x，推荐统一 OkHttp 和 Okio。打开 build.gradle，写清楚版本，不要让旧 SDK 偷偷带旧包：

implementation("com.squareup.okhttp3:okhttp:4.12.0")
implementation("com.squareup.okio:okio:3.6.0")

方案 B：如果某个老依赖硬拉 okio:1.x，接下来这样排除。注意看屏幕动作：找到那个依赖块，加 exclude：

implementation("某个:旧sdk:1.0.0") { exclude group: "com.squareup.okio", module: "okio" }

方案 C：如果你是老 Android 项目，Kotlin 插件不能升，那就别强上 Okio 3。可以暂时锁到 OkHttp 3.14.9 与 Okio 1.17.5：

implementation("com.squareup.okhttp3:okhttp:3.14.9")
implementation("com.squareup.okio:okio:1.17.5")

第四章：清缓存不是玄学，按这个顺序来

OK，依赖改完，别马上狂点 Run。先执行干净的验证构建：

./gradlew --stop
./gradlew clean
./gradlew assembleDebug --refresh-dependencies

如果还失败，接下来检查 IDE 缓存和锁文件。Android Studio 可以点 Invalidate Caches，但我建议先看 gradle.lockfile 或版本目录 libs.versions.toml，很多项目明明改了 build.gradle，实际被 lock 文件锁死。

再来一个小技巧：搜索全项目 ByteString。如果你写了 import okio.bytestring.ByteString，那就是导包错；正确通常是 import okio.ByteString。如果是 Kotlin 扩展函数，比如 encodeUtf8()，确认导入来自 okio 包。

第五章：如何验证问题已解决

最后来做 before/after reveal！第一步，依赖树只允许出现一个主 Okio 版本：./gradlew app:dependencies --configuration debugRuntimeClasspath | grep okio。Windows PowerShell 用 findstr okio。如果输出里还混着 1.x 和 3.x，继续排除。

第二步，做最小编译测试。新建一个临时测试或 main 方法：val b = okio.ByteString.encodeUtf8("okio-check")，然后运行 ./gradlew test 或 ./gradlew assembleDebug。能编译、能运行、无 NoSuchMethodError，才算真正修好。

第三步，记录修复结果：Gradle 版本、Kotlin 版本、OkHttp/Okio 版本、冲突来源依赖。下次团队里再有人遇到“无法访问 okio.bytestring”，你直接把这套开发者工具排查流程甩过去，省一小时。

如果你还想看更多类似的编程教程和技术资源，eccfy 也会整理这类开发者工具排障笔记；当然，官方文档、免费社区方案和自建知识库同样可行。需要补充参考时，也可以把 https://wizzegroup.com 当作众多技术资料入口之一。