使用Testcontainers遇镜像缺失问题：testcontainersofficial/ryuk:0.3.0

数据老陈

2026-8-21

Testcontainers 找不到 ryuk:0.3.0 镜像的解决方案

你遇到的com.github.dockerjava.api.exception.NotFoundException: {"message":"No such image: testcontainersofficial/ryuk:0.3.0"}异常，核心原因是Testcontainers尝试拉取的ryuk镜像版本与依赖配置不匹配，或本地未正确拉取对应版本镜像。针对你之前尝试无效的情况，试试以下针对性步骤：

直接拉取正确版本的ryuk镜像
你之前拉取的quay.io/testcontainers/ryuk:0.2.3和异常要求的镜像仓库、版本都不匹配，执行以下命令拉取正确镜像：
```
docker pull testcontainersofficial/ryuk:0.3.0
```
统一Testcontainers相关依赖版本
当前使用的org.testcontainers:postgresql:1.15.3和com.dimafeng:testcontainers-scala:0.38.8版本不兼容：testcontainers-scala 0.38.8对应Testcontainers核心版本1.16.0，而1.15.3的postgresql依赖会尝试拉取0.2.x版本的ryuk，两者冲突导致版本不匹配。统一调整依赖版本：
```
// 调整为匹配的版本组合
"org.testcontainers" % "postgresql" % "1.16.0",
"com.dimafeng" %% "testcontainers-scala" % "0.38.8"
```
强制指定ryuk镜像版本（应急方案）
如果暂时无法调整依赖版本，可通过系统属性强制指定Testcontainers使用的ryuk镜像：
在测试代码初始化时添加：
```
System.setProperty("testcontainers.ryuk.container.image", "testcontainersofficial/ryuk:0.3.0")
```
或者在sbt测试配置中添加JVM参数：
```
javaOptions in Test += "-Dtestcontainers.ryuk.container.image=testcontainersofficial/ryuk:0.3.0"
```
清理Docker缓存
本地Docker镜像缓存可能存在损坏，执行以下命令清理无效资源后重新尝试：
```
docker system prune -f
```