类别一：镜像相关错误

1. Error response from daemon: pull access denied for <image-name>, repository does not exist or may require ‘docker login’

错误原因：

• 镜像名称拼写错误。
• 尝试拉取不存在的镜像。
• 尝试拉取私有仓库（如 Docker Hub 上的私人镜像、AWS ECR、Harbor 等）的镜像，但没有登录或没有权限。

解决办法：

• 检查镜像名：确认镜像名称拼写正确，特别是官方镜像通常没有前缀，如 nginx，而非 library/nginx。
• 检查镜像是否存在：去 Docker Hub (hub.docker.com) 或相应的镜像仓库网站搜索确认。
• 登录仓库：

  # 对于 Docker Hub
  docker login
  
  # 对于其他私有仓库，需要指定地址
  docker login myprivateregistry.com:5000
  

• 检查权限：确保你的账户有拉取该镜像的权限。

2. Error response from daemon: conflict: unable to delete <image-id> (cannot be forced) - image is being used by stopped container <container-id>

错误原因：

• 镜像被一个已停止的容器所占用，Docker 为了防止数据丢失，默认不允许删除正在被使用的镜像。

解决办法：

• 先删除占用镜像的容器：

  # 列出所有容器（包括已停止的）
  docker ps -a
  
  # 删除使用该镜像的容器
  docker rm <container-id>
  
  # 然后再删除镜像
  docker rmi <image-id>
  

• 强制删除（不推荐）：使用 -f 标志可以强制删除，但这可能导致“悬空”容器，不推荐。

  docker rmi -f <image-id>
  

3. no space left on device / Failed to export image: failed to create image: write /var/lib/docker/tmp/docker-export...: no space left on device

错误原因：

• Docker 宿主机磁盘空间不足，通常是 /var/lib/docker 目录满了。

解决办法：

• 清理 Docker 资源：

  # 删除所有已停止的容器、所有未被使用的网络、所有悬空镜像和构建缓存
  docker system prune -a
  
  # 也可以分别清理
  docker container prune    # 清理停止的容器
  docker image prune -a     # 清理无用的镜像
  docker volume prune       # 清理无用的数据卷
  

• 检查磁盘空间：使用 df -h 命令查看磁盘使用情况。
• 迁移 Docker 数据目录：如果 /var 分区太小，可以考虑将 Docker 的根目录迁移到更大的磁盘分区。

---

类别二：容器运行相关错误

4. docker: Error response from daemon: driver failed programming external connectivity on endpoint <container-name> (...-): Error starting userland proxy: listen tcp4 0.0.0.0:8080: bind: address already in use.

错误原因：

• 端口冲突。宿主机上已经有一个进程（可能是另一个 Docker 容器或其他应用）占用了你想要映射的端口（如 8080）。

解决办法：

• 更改宿主机端口：将 -p 8080:80 改为 -p 8081:80。
• 停止占用端口的进程：

  # 查找占用 8080 端口的进程
  sudo lsof -i :8080
  # 或者使用
  sudo netstat -tulpn | grep :8080
  
  # 根据 PID 杀死进程（如果确定可以停止）
  kill -9 <PID>
  

• 使用 --net=host（高级用法，不推荐用于常规部署）：这样容器会直接使用宿主机的网络命名空间，但会失去端口隔离。

5. standard_init_linux.go:228: exec user process caused: no such file or directory

错误原因：

• 最常见的原因是在 Windows 上创建了 Dockerfile，并将其复制到 Linux 系统的 Docker 中构建。Windows 的换行符（CRLF \r\n）和 Linux（LF \n）不同，导致 Shell 脚本无法正确识别。
• 也可能是 ENTRYPOINT 或 CMD 指定的可执行文件在镜像中确实不存在。

解决办法：

• 统一换行符：在 Git 中设置 core.autocrlf 为 false 或在文本编辑器（如 VSCode）中将文件换行符设置为 LF。
• 检查文件路径：确保 COPY 或 ADD 指令已将文件复制到镜像中，并且 ENTRYPOINT/CMD 的路径正确。
• 检查文件权限：确保可执行文件有执行权限（chmod +x）。

6. WARNING: IPv4 forwarding is disabled. Networking will not work.

错误原因：

• Linux 系统的 IP 转发功能被禁用，这会导致容器无法访问外部网络。

解决办法：

• 编辑 /etc/sysctl.conf 文件：

  sudo vi /etc/sysctl.conf
  

• 添加或修改以下行：

  net.ipv4.ip_forward=1
  

• 重新加载配置：

  sudo sysctl -p
  

---

类别三：权限相关错误

7. Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

错误原因：

• 当前用户没有加入 docker 用户组，因此无权访问 Docker 守护进程的 Unix Socket。

解决办法：

• 将当前用户加入 docker 组：

  sudo usermod -aG docker $USER
  

• 重新登录：退出当前终端并重新登录，或者执行 newgrp docker，使组权限生效。
• 注意：在生产环境中，授予用户 Docker 权限等同于授予其 root 权限，需谨慎操作。

8. Permission denied 当挂载宿主机目录到容器内时

错误原因：

• 容器内的进程（通常以 root 或其他非 root 用户运行）没有权限访问宿主机上挂载的目录。

解决办法：

• 放宽宿主机目录权限（简单但不安全）：

  chmod 777 /host/path
  

• 使用更安全的权限：将目录的所有者改为容器内进程使用的 UID（通常是 root，即 0）。

  sudo chown 1000:1000 /host/path # 假设容器内用户 UID 是 1000
  

• 在 docker run 中使用 -u 参数：指定容器运行时使用的 UID，使其与宿主机目录的 UID 匹配。

  docker run -u $(id -u):$(id -g) -v /host/path:/container/path ...
  

---

类别四：网络相关错误

9. docker: Error response from daemon: user specified IP address is supported only when connecting to networks with user configured subnets.

错误原因：

• 在 docker run 时使用 --ip 参数为容器指定了静态 IP，但所连接的网络（通常是默认的 bridge 网络）不支持自定义子网和静态 IP。

解决办法：

• 创建自定义网络：自定义网络支持静态 IP 分配。

  # 创建自定义网络并指定子网
  docker network create --subnet=172.20.0.0/16 mynet
  
  # 运行容器并连接到自定义网络，同时指定 IP
  docker run --network=mynet --ip=172.20.0.10 ...
  

10. 容器无法连接到外部网络（如互联网）或其他容器

错误原因：

• Docker 守护进程的 DNS 配置问题。
• 防火墙（iptables, firewalld）规则阻止了连接。

解决办法：

• 配置 Docker DNS：编辑 Docker 守护进程配置文件 /etc/docker/daemon.json（如果不存在则创建）：

  {
    "dns": ["8.8.8.8", "114.114.114.114"]
  }
  

• 重启 Docker 服务：

  sudo systemctl restart docker
  

• 检查防火墙：如果使用 firewalld，可以尝试暂时关闭它以确认问题：

  sudo systemctl stop firewalld
  # 如果问题解决，需要为 Docker 服务添加规则，而不是直接关闭防火墙
  sudo firewall-cmd --permanent --add-masquerade
  sudo firewall-cmd --permanent --add-port=2376/tcp # 或其他所需端口
  sudo firewall-cmd --reload
  

---

类别五：Dockerfile 构建错误

11. Step 5/10 : COPY ./app /app COPY failed: stat /var/lib/docker/tmp/docker-builder.../app: no such file or directory

错误原因：

• COPY 或 ADD 指令引用的源文件在构建上下文中不存在。
• 注意：Docker 构建时只能访问构建上下文（通常是 docker build 命令最后一个点 . 指定的目录）内的文件。

解决办法：

• 确保文件存在于构建上下文中。
• 检查 .dockerignore 文件，看是否排除了该文件。
• 确认 docker build 命令的路径是否正确。

12. The command ‘/bin/sh -c <command>‘ returned a non-zero code: 1

错误原因：

• 这是一个通用错误，表示 Dockerfile 中某一条 RUN 指令执行失败（返回了非 0 的退出码）。
• 具体原因需要看它上面的输出，可能是包安装失败、命令不存在、脚本错误等。

解决办法：

• 仔细阅读错误输出：错误信息通常会明确指出失败原因，如 apt-get update 网络问题、pip install 包找不到等。
• 分步调试：可以尝试在出错的 RUN 指令前加上 RUN ls -l 等命令来检查当前目录状态。
• 交互式调试：如果可能，先构建一个出错的中间镜像，然后运行一个交互式容器进去手动执行命令调试：

  docker run -it <failed-image-id> /bin/bash