使用 docker pull 拉取插件时出现 "Encountered remote 'application/vnd.docker.plugin.v1+json'(plugin)" 错误

本文适用于：

• Docker 20+ / 24+
• 尝试使用 docker pull 拉取插件
• 遇到 application/vnd.docker.plugin.v1+json 错误
• 需要了解插件与镜像的区别

⚠️ 重要提示

这不是镜像拉取错误，而是您尝试用 docker pull 拉取插件，应该使用 docker plugin install。

✅ 推荐做法

插件必须使用 docker plugin install 命令，不能用 docker pull。安装后使用 docker plugin enable 启用插件。

当您尝试使用 docker pull 命令拉取某个镜像时，如果遇到如下错误，说明您尝试拉取的不是普通镜像，而是 Docker 插件。

错误示例

docker pull xxx.xuanyuan.run/grafana/loki-docker-driver:3.6.2-amd64 Error response from daemon: Encountered remote "application/vnd.docker.plugin.v1+json"(plugin) when fetching

这个错误表明 Docker 检测到您尝试拉取的是插件（plugin），而不是普通的镜像（image）。

错误原因分析

核心原因：Docker 插件和普通镜像的安装方式完全不同

普通镜像使用 docker pull 命令拉取
Docker 插件需要使用专门的 docker plugin install 命令安装
错误信息中的 "application/vnd.docker.plugin.v1+json" 是 Docker 插件的媒体类型标识，表示这是一个插件资源

解决方案

方法 1：使用插件安装命令（基础用法）

将 docker pull 替换为 docker plugin install：

docker plugin install xxx.xuanyuan.run/grafana/loki-docker-driver:3.6.2-amd64

执行此命令后，Docker 会自动下载并安装插件到本地。

方法 2：使用插件安装命令（带配置参数）

如果需要为插件设置别名或授予权限，可以在命令中添加参数：

docker plugin install xxx.xuanyuan.run/grafana/loki-docker-driver:3.6.2-amd64 --alias loki --grant-all-permissions

参数说明：

--alias loki：为插件设置一个简短的别名，方便后续使用
--grant-all-permissions：授予插件所有必要的权限，某些插件需要特定权限才能正常工作

Docker 插件与普通镜像的区别

特性	普通镜像（Image）	Docker 插件（Plugin）
安装命令	`docker pull`	`docker plugin install`
用途	运行容器应用	扩展 Docker 功能（如日志驱动、存储驱动等）
使用方式	`docker run` 启动容器	在配置文件中启用（如 `daemon.json`）
查看已安装项	`docker images`	`docker plugin ls`

插件安装后的操作

安装成功后，您可以使用以下命令管理插件：

查看已安装的插件：

docker plugin ls

启用插件：

docker plugin enable <插件名或ID>

禁用插件：

docker plugin disable <插件名或ID>

卸载插件：

docker plugin rm <插件名或ID>

（注意：卸载前需要先禁用插件）

常见插件示例

一些常见的 Docker 插件包括：

日志驱动插件：如 Loki Docker Driver，用于将容器日志发送到 Loki
网络插件：如 Weave、Calico 等网络解决方案
存储插件：如各种云存储驱动
卷插件：如 NetApp、GlusterFS 等存储系统

如果您的需求是使用 Loki 日志驱动，安装插件后还需要在 Docker 的配置文件中配置日志驱动。具体配置方法请参考插件提供商的文档。

💡 总结：

✅ 遇到 "application/vnd.docker.plugin.v1+json" 错误时，说明您尝试拉取的是 Docker 插件而非普通镜像
✅ 使用 docker plugin install 替代 docker pull 来安装插件
✅ 可以添加 --alias 和 --grant-all-permissions 参数进行配置
✅ 安装后使用 docker plugin ls 查看已安装的插件
✅ 更多插件管理命令请参考 Docker 官方文档：Docker 插件安装文档

你可能还会遇到：

本文由「xuanyuan.cloud」维护
专注国内 Docker / 镜像 / Registry 网络问题
内容基于真实用户环境与实测