Laravel Sail 服务构建失败：Docker 环境排查与修复指南-php教程-PHP中文网

Laravel Sail 服务构建失败：Docker 环境排查与修复指南

心靈之曲

发布： 2025-11-09 13:19:27

原创

125人浏览过

Laravel Sail 服务构建失败：Docker 环境排查与修复指南

本文旨在解决laravel sail项目中常见的“service 'laravel.test' failed to build”错误。该问题通常表现为docker容器在构建过程中无法解析网络地址或安装依赖包，其根本原因往往是宿主机docker环境过时或配置不当，特别是在操作系统升级后。本教程将详细指导如何通过彻底重装docker来修复此问题，确保laravel sail能够顺利构建并运行开发环境。

在使用Laravel Sail构建开发环境时，开发者可能会遇到“ERROR: Service 'laravel.test' failed to build”的错误。此错误通常伴随着Docker构建日志中出现网络连接失败的提示，例如“Temporary failure resolving 'archive.ubuntu.com'”或“W: Some index files failed to download”，进而导致后续的软件包安装（如gnupg、curl等）失败，并显示“E: Package '...' has no installation candidate”或“E: Unable to locate package ...”。这些现象明确指出，Docker容器在尝试构建其镜像时，无法正常访问外部网络资源。

错误现象分析

当执行./vendor/bin/sail up命令时，如果Docker环境存在问题，构建过程会在laravel.test服务处中断。详细的错误日志会显示在执行apt-get update命令时，由于DNS解析失败或网络不通，导致无法从Ubuntu官方仓库下载软件包索引。这进而使得容器无法安装后续步骤所需的各种依赖，最终导致构建失败并返回非零退出码。

尽管表面上看是容器内部的网络连接问题，但其深层原因往往在于宿主机上的Docker守护进程本身存在缺陷，尤其是当Docker版本过旧或其仓库配置在操作系统升级（例如从Ubuntu 16.04升级到20.04）过程中被禁用或损坏时。在这种情况下，升级Docker是解决问题的关键。

解决方案：彻底重装Docker

为了解决因Docker环境问题导致的Laravel Sail构建失败，最有效的方法是彻底移除旧版Docker并重新安装最新稳定版。以下是详细的步骤：

1. 移除旧版Docker及其相关组件

首先，需要确保系统上所有旧的Docker安装都被完全清除。执行以下命令：

sudo apt-get remove docker docker-engine docker.io containerd runc

登录后复制

此命令会卸载Docker的核心组件。如果系统上没有安装这些包，命令会提示未找到，这属于正常情况。

2. 更新APT包索引并安装必要的依赖

为了让APT能够通过HTTPS使用仓库，需要安装一些必要的软件包。

sudo apt update
sudo apt install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

登录后复制

ca-certificates: 允许基于SSL/TLS的应用程序检查证书。
curl: 用于下载文件，包括Docker的GPG密钥。
gnupg: 用于验证下载的软件包的签名。
lsb-release: 提供Linux标准库（LSB）信息，如发行版名称。

3. 添加Docker官方GPG密钥

Docker使用GPG密钥来验证软件包的真实性。需要下载并添加Docker的官方GPG密钥到系统。

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

登录后复制

此命令从Docker官网下载GPG密钥，并将其存储在/usr/share/keyrings/docker-archive-keyring.gpg路径下。

4. 配置Docker稳定版仓库

将Docker的稳定版仓库添加到APT源列表中。这确保APT会从官方渠道获取Docker软件包。

绘蛙AI修图

绘蛙平台AI修图工具，支持手脚修复、商品重绘、AI扩图、AI换色

129

查看详情

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

登录后复制

$(dpkg --print-architecture): 自动检测系统架构。
signed-by=/usr/share/keyrings/docker-archive-keyring.gpg: 指定用于验证软件包的GPG密钥。
$(lsb_release -cs): 获取当前Ubuntu发行版的代号（例如focal对应Ubuntu 20.04）。

5. 安装新版Docker

现在，可以更新APT包索引并安装Docker Engine、CLI和Containerd。

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

登录后复制

这会安装最新稳定版的Docker。

6. 验证安装并重启服务

安装完成后，可以通过运行一个简单的Docker命令来验证安装是否成功：

sudo docker run hello-world

登录后复制

如果看到“Hello from Docker!”的消息，则表明Docker已成功安装并运行。

由于Docker服务可能在安装过程中自动启动，但为了确保所有更改生效，建议手动重启Docker服务：

sudo systemctl restart docker

登录后复制

如果之前未进行Docker的“Post-installation steps”（例如将当前用户添加到docker组以便无需sudo即可运行Docker命令），建议现在进行配置：

sudo usermod -aG docker $USER
newgrp docker # 或注销并重新登录

登录后复制

完成上述步骤后，返回到Laravel项目目录，再次尝试启动Sail：

./vendor/bin/sail up

登录后复制

此时，laravel.test服务应该能够顺利构建并启动。

注意事项

网络环境：在执行上述步骤时，请确保宿主机具有稳定的互联网连接，以便下载Docker及其依赖。
操作系统版本：本教程基于Ubuntu系统，对于其他Linux发行版，Docker的安装步骤可能会有所不同，请参考Docker官方文档。
持续更新：建议定期更新Docker以获取最新的功能和安全修复。

总结

Laravel Sail的“Service 'laravel.test' failed to build”错误，特别是当其伴随容器内部网络连接失败的日志时，往往指向宿主机Docker环境的问题。通过彻底移除旧版Docker并按照官方推荐步骤重新安装最新稳定版，可以有效解决因Docker版本过旧或配置不当导致的构建失败。一个健康且配置正确的Docker环境是确保Laravel Sail顺畅运行的关键。

以上就是Laravel Sail 服务构建失败：Docker 环境排查与修复指南的详细内容，更多请关注php中文网其它相关文章！