Laravel Sail 容器构建失败问题排查与解决-php教程-PHP中文网

Laravel Sail 容器构建失败问题排查与解决

心靈之曲

发布： 2025-10-21 11:36:51

原创

486人浏览过

laravel sail 容器构建失败问题排查与解决

本文旨在帮助开发者解决在使用 Laravel Sail 构建容器时遇到的 "No such file or directory" 和 "TLS handshake timeout" 等错误。通过检查 Sail 安装、配置 DNS 解析，提供详细的步骤和示例，确保 Laravel Sail 环境顺利运行。

在使用 Laravel Sail 进行 Laravel 项目容器化部署时，可能会遇到各种问题导致容器构建失败。其中，常见的错误包括 "No such file or directory" 和 "TLS handshake timeout"。这通常与 Sail 未正确安装或 DNS 配置有关。本文将详细介绍如何排查这些问题，并提供相应的解决方案。

确认 Laravel Sail 已正确安装

首先，需要确认 Laravel Sail 是否已成功安装，以及相关文件是否存在。

检查 Sail 文件是否存在： 确认 vendor/bin/sail 文件是否存在。如果该文件不存在，说明 Sail 可能未正确安装。
重新安装 Sail： 如果 vendor/bin/sail 文件不存在，请执行以下命令重新安装 Sail：
```
composer require laravel/sail --dev
php artisan sail:install
```
登录后复制
安装过程中，php artisan sail:install 命令会提示选择 Docker 镜像，根据项目需求选择即可。

解决 DNS 解析问题

如果确认 Sail 已正确安装，但仍然遇到问题，很可能是 DNS 解析配置不正确导致的。尤其是在 WSL (Windows Subsystem for Linux) 环境下，DNS 配置可能会出现问题，导致无法访问 Docker 镜像仓库。

问题表现：

No such file or directory (如果 Sail 命令无法找到)
TLS handshake timeout (无法从 Docker 镜像仓库拉取镜像)

解决方案：

以下步骤演示如何在 WSL 环境下配置 DNS 解析：

配置 wsl.conf 文件： 创建或编辑 /etc/wsl.conf 文件：
```
sudo vim /etc/wsl.conf
```
登录后复制
在文件中添加以下内容：
```
[network]
generateResolvConf=false
```
登录后复制
保存并退出编辑器。

AI建筑知识问答
用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情
修改 resolv.conf 文件： 编辑 /etc/resolv.conf 文件：
```
sudo vim /etc/resolv.conf
```
登录后复制
找到 nameserver 行，通常会显示 WSL 自动生成的 DNS 服务器地址，例如：
```
nameserver 172.28.32.1
```
登录后复制
将其替换为公共 DNS 服务器地址，例如 Google 的 DNS 服务器：
```
nameserver 8.8.8.8
```
登录后复制
保存并退出编辑器。
重启 WSL： 关闭所有 WSL 终端，然后在 PowerShell 中执行以下命令重启 WSL：
```
wsl --shutdown
```
登录后复制
测试 DNS 解析： 重新打开 WSL 终端，执行以下命令测试 DNS 解析是否正常：
```
ping google.com
```
登录后复制
如果能够成功 ping 通 google.com，说明 DNS 解析已配置正确。
重新构建 Sail 容器： 进入 Laravel 项目目录，执行以下命令重新构建 Sail 容器：
```
./vendor/bin/sail up
```
登录后复制

注意事项

在修改 resolv.conf 文件后，如果 WSL 自动重新生成该文件，导致配置失效，可以考虑将 resolv.conf 文件设置为只读：
```
sudo chattr +i /etc/resolv.conf
```
登录后复制
但请注意，设置为只读后，系统将无法自动更新 DNS 配置。如果需要更新 DNS 配置，需要先移除只读属性：
```
sudo chattr -i /etc/resolv.conf
```
登录后复制
如果仍然遇到问题，可以尝试更新 Docker 到最新版本。