解决Laravel Sail构建失败：深入解析WSL DNS配置与网络问题-php教程-PHP中文网

解决Laravel Sail构建失败：深入解析WSL DNS配置与网络问题

聖光之護

发布： 2025-10-21 10:11:15

原创

543人浏览过

解决Laravel Sail构建失败：深入解析WSL DNS配置与网络问题

本文深入探讨laravel sail在wsl环境下构建容器时常见的网络和dns相关问题，特别是`tls handshake timeout`错误。教程将指导用户通过修改wsl的`wsl.conf`和`resolv.conf`文件，手动配置dns服务器为公共dns（如8.8.8.8），从而解决容器构建失败的问题，确保laravel开发环境的顺利搭建。

Laravel Sail为PHP开发者提供了一个轻量级的Docker开发环境，极大地简化了Laravel项目的环境搭建流程。然而，在Windows Subsystem for Linux (WSL) 环境下使用Sail时，用户可能会遇到容器构建失败的问题，其中最常见的是与网络或DNS解析相关的错误，例如TLS handshake timeout或failed to fetch oauth token。本教程将详细解析这些问题，并提供一套行之有效的解决方案。

诊断Sail构建失败的常见原因

当执行./vendor/bin/sail up命令时，如果遇到No such file or directory错误，首先应确认Laravel Sail是否已正确安装。这通常意味着vendor/bin/sail文件不存在。请确保已运行composer require laravel/sail --dev和php artisan sail:install命令，并且Composer依赖已正确安装。

如果Sail文件存在，但构建过程仍然失败并显示类似以下错误信息：

failed to solve with frontend dockerfile.v0: failed to create LLB definition: failed to authorize: rpc error: code = Unknown desc = failed to fetch oauth token: Get "https://auth.docker.io/token?scope=repository%3Alibrary%2Fubuntu%3Apull&service=registry.docker.io": net/http: TLS handshake timeout
ERROR: Service 'laravel.test' failed to build : Build failed

登录后复制

这明确指示了网络连接或DNS解析问题。Docker在构建过程中需要从Docker Hub拉取基础镜像（例如ubuntu:21.04），而TLS handshake timeout和failed to fetch oauth token错误表明WSL环境无法正确解析或连接到Docker Hub的认证或镜像服务。

为了进一步诊断，您可以在WSL终端中尝试执行ping google.com。如果该命令无法成功解析域名并获得响应，那么可以确认DNS配置是问题的根源。

解决方案：配置WSL的DNS服务器

WSL默认会自动生成/etc/resolv.conf文件，并使用宿主Windows系统的DNS设置。有时，这些自动生成的DNS服务器在WSL环境中可能无法正常工作，导致容器构建时出现网络问题。解决此问题的核心是禁用WSL的自动DNS生成，并手动配置一个可靠的公共DNS服务器。

步骤一：禁用WSL的自动DNS生成

首先，我们需要告诉WSL不要自动覆盖/etc/resolv.conf文件。

打开WSL终端。
使用文本编辑器（如vim或nano）创建或编辑/etc/wsl.conf文件：
```
sudo vim /etc/wsl.conf
```
登录后复制
在文件中添加以下内容：
```
[network]
generateResolvConf=false
```
登录后复制
这行配置将阻止WSL在启动时自动生成或修改/etc/resolv.conf文件。

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

22

查看详情
保存并退出文件（在vim中是:wq）。

步骤二：手动配置DNS服务器

接下来，我们将手动编辑/etc/resolv.conf文件，将其指向一个可靠的公共DNS服务器，例如Google的8.8.8.8。

继续在WSL终端中，编辑/etc/resolv.conf文件：
```
sudo vim /etc/resolv.conf
```
登录后复制
您可能会看到类似以下内容：
```
# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
# [network]
# generateResolvConf = false
nameserver 172.28.32.1
```
登录后复制
请注意，文件顶部可能仍有注释，但由于我们在wsl.conf中设置了generateResolvConf=false，这些注释将不再影响文件的自动生成。
将nameserver行替换为nameserver 8.8.8.8（或其他您信任的公共DNS，如Cloudflare的1.1.1.1）：
```
nameserver 8.8.8.8
```
登录后复制
保存并退出文件。

步骤三：重启WSL和Docker Desktop

为了使wsl.conf的更改生效，您需要完全关闭并重启WSL实例。

在Windows的PowerShell或命令提示符中，运行以下命令关闭所有WSL实例：
```
wsl --shutdown
```
登录后复制
等待几秒钟，然后重新启动您的WSL终端。
同时，建议重启Docker Desktop应用程序，以确保Docker环境也刷新了网络配置。

步骤四：重新尝试构建Sail容器

完成上述步骤后，导航到您的Laravel项目目录，并再次尝试启动Sail容器：

./vendor/bin/sail up

登录后复制

此时，Sail应该能够成功解析域名并从Docker Hub拉取所需的镜像，从而顺利完成容器的构建和启动。

注意事项与总结

网络连通性检查： 在进行上述配置之前，请确保您的宿主Windows系统本身具有正常的互联网连接。如果Windows都无法上网，那么WSL和Docker自然也无法访问外部网络。
其他DNS服务器： 除了8.8.8.8，您还可以尝试使用其他公共DNS服务器，例如Cloudflare的1.1.1.1，或您本地ISP提供的稳定DNS。
Docker登录： 尽管错误信息中提到了failed to authorize，但通常情况下，这并非直接的Docker登录凭据问题，而是底层网络无法到达认证服务器所致。解决DNS问题后，通常无需手动执行docker login。
WSL版本： 确保您的WSL是最新版本，可以通过wsl --update命令进行更新，这有助于解决一些潜在的兼容性问题。

通过上述步骤，您应该能够成功解决Laravel Sail在WSL环境中因DNS配置不当导致的容器构建失败问题，从而顺利搭建您的Laravel开发环境。正确的网络配置是Docker环境稳定运行的基础，尤其是在WSL这种虚拟化环境中。

以上就是解决Laravel Sail构建失败：深入解析WSL DNS配置与网络问题的详细内容，更多请关注php中文网其它相关文章！