Docker 构建时出现 "docker-credential-desktop.exe" 找不到错误

问题描述

在使用 docker build 命令时，用户可能会遇到以下错误：

=> ERROR [internal] load metadata for docker.io/library/ubuntu:18.04
------
> [internal] load metadata for docker.io/library/ubuntu:18.04:
------
failed to solve with frontend dockerfile.v0: failed to create LLB definition: rpc error: code = Unknown desc = error getting credentials - err: exec: "docker-credential-desktop.exe": executable file not found in $PATH, out: ``

这个错误表明 Docker 尝试调用 docker-credential-desktop.exe 凭证管理器来处理认证，但无法在系统路径中找到该可执行文件。

根本原因

Docker 使用配置文件 ~/.docker/config.json 中的 credsStore 设置来决定如何存储和检索容器注册表的凭据。当该属性设置为 desktop 或 desktop.exe 时，Docker 会尝试查找并执行 docker-credential-desktop（或 .exe）程序。

此问题通常出现在以下情况：

• 从 Docker Desktop 切换到其他 Docker 运行时（如 Colima、Rancher Desktop）
• Docker Desktop 未正确安装或配置
• WSL（Windows Subsystem for Linux）环境中的路径配置问题

解决方案

方法一：修改 Docker 配置文件（推荐）

最常见的解决方案是编辑 Docker 的配置文件：

1. 打开终端，编辑配置文件：

   # 使用你喜欢的编辑器，如 nano、vim 或 code
   nano ~/.docker/config.json

2. 将 credsStore 改为 credStore，或者直接删除该行：

   修改前：

   {
     "credsStore": "desktop"
   }

   修改后（选项1）：

   {
     "credStore": "desktop"
   }

   修改后（选项2 - 完全删除）：

   {
   }

3. 保存文件并重新尝试 Docker 构建操作。

TIP

实际上，只需确保配置文件中没有名为 credsStore 的属性即可。即使将其改为其他名称（如 credxxxxxxStore）也能解决问题。

方法二：完全重置 Docker 配置

如果没有任何重要的 Docker 配置需要保留，可以完全删除配置目录：

rm -rf ~/.docker

这将删除所有 Docker 配置，包括认证信息，因此下次需要重新登录 Docker 仓库。

方法三：Windows/WSL 特定配置

对于 Windows 用户和 WSL 环境：

1. 检查 Windows 主机上的配置：

   • 同时检查 C:\Users\<用户名>\.docker\config.json 文件
   • 确保 WSL 已正确启动（特别是使用 VS Code Dev Containers 时）

2. 使用 PowerShell：

   • 尝试使用 PowerShell 终端而不是 CMD，有时可以解决路径问题

3. 更新 Docker Desktop：

   • 检查并安装 Docker Desktop 的最新更新

方法四：macOS 特定解决方案

对于 macOS 用户：

1. 安装凭证助手：

   brew install docker-credential-helper

2. 确保 Docker 在 PATH 中：

   # 对于 zsh 用户
   echo 'export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   
   # 对于 bash 用户
   echo 'export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"' >> ~/.bash_profile
   source ~/.bash_profile

3. 验证 Docker 路径：

   which docker
   # 应该输出：/Applications/Docker.app/Contents/Resources/bin/docker

方法五：Linux 权限问题

如果遇到权限问题，确保用户已加入 docker 组：

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 注销后重新登录使更改生效

配置示例

以下是一些有效的 config.json 配置示例：

示例1：完全移除凭据存储

{
  "auths": {},
  "currentContext": "default"
}

示例2：使用正确拼写

{
  "auths": {},
  "credStore": "desktop",
  "currentContext": "default"
}

示例3：Windows/WSL 配置

{
  "credStore": "wincred"
}

原理解释

Docker 使用 credsStore 属性指定外部二进制文件作为默认凭据存储。当设置此属性时，docker login 会尝试将凭据存储在由 docker-credential-<value> 指定的二进制文件中，该文件需要在 $PATH 中可见。如果未设置此属性，凭据将存储在配置的 auths 属性中。

WARNING

从 Docker Desktop 切换到其他 Docker 运行时（如 Colima 或 Rancher Desktop）时，通常需要修改或删除 credsStore 设置，因为这些环境可能不包含 Docker Desktop 的特定凭证助手。

总结

"docker-credential-desktop.exe not found" 错误通常是由于 Docker 配置文件中的 credsStore 设置与当前环境不匹配导致的。通过修改或删除 ~/.docker/config.json 文件中的相关设置，大多数情况下可以迅速解决此问题。

根据你的环境和需求，选择最适合的解决方案：

• 对于大多数用户，方法一（修改配置文件）是最简单有效的解决方案
• 如果需要彻底清理，可以考虑方法二
• 平台特定的问题可以参考方法三和方法四

保持 Docker 安装更新并确保路径配置正确，可以预防此类问题的发生。