解决Laravel Sail构建失败：WSL环境下的DNS配置指南-php教程-PHP中文网

解决Laravel Sail构建失败：WSL环境下的DNS配置指南

霞舞

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

原创

998人浏览过

解决Laravel Sail构建失败：WSL环境下的DNS配置指南

本文旨在解决laravel sail在wsl环境下构建容器时遇到的“tls handshake timeout”错误，该错误通常由dns配置问题引起。教程将详细指导用户如何通过修改wsl的wsl.conf和resolv.conf文件，将dns服务器设置为公共dns（如8.8.8.8），从而确保docker能够正常解析域名，成功构建laravel sail服务。

Laravel Sail构建失败：WSL环境下的DNS配置指南

Laravel Sail为PHP开发者提供了一个轻量级的Docker开发环境，极大地简化了本地开发环境的搭建。然而，在Windows Subsystem for Linux (WSL) 环境下使用Sail时，用户可能会遇到容器构建失败的问题，其中最常见的错误是failed to fetch oauth token: net/http: TLS handshake timeout，这通常指向网络或DNS解析故障。本教程将详细介绍如何诊断并解决此类问题。

诊断问题：确认Sail安装与网络连接

在深入解决DNS问题之前，首先需要确认Laravel Sail已正确安装。如果在运行./vendor/bin/sail up时遇到No such file or directory错误，请检查项目根目录下vendor/bin/sail文件是否存在。这通常意味着Sail未安装成功或Composer依赖未更新。

如果Sail文件存在，但构建过程出现以下错误信息：

ERROR [internal] load metadata for docker.io/library/ubuntu:21.04:
------
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.io拉取镜像。为了验证这一点，可以在WSL终端中尝试ping google.com。如果ping命令无法解析域名或无法获得响应，则可以确认是DNS配置不正确导致了问题。

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

解决此问题的核心在于手动配置WSL的DNS解析器，使其使用可靠的公共DNS服务器，例如Google的8.8.8.8。这需要修改WSL的两个关键配置文件：/etc/wsl.conf和/etc/resolv.conf。

步骤一：禁用自动生成resolv.conf

WSL默认会自动生成/etc/resolv.conf文件，这可能导致手动修改的DNS配置被覆盖。为了防止这种情况，我们需要禁用此自动生成功能。

打开WSL终端。
使用文本编辑器（如vim或nano）创建或编辑/etc/wsl.conf文件：
```
sudo vim /etc/wsl.conf
```
登录后复制
在文件中添加以下内容：
```
[network]
generateResolvConf=false
```
登录后复制
保存并退出文件（在vim中，输入:wq然后按回车）。

注意： 修改wsl.conf后，需要完全关闭并重新启动WSL实例才能使更改生效。可以通过在PowerShell中运行wsl --shutdown，然后重新打开WSL终端来完成。

琅琅配音

全能AI配音神器

208

查看详情

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

禁用自动生成后，现在可以手动修改/etc/resolv.conf文件，指定公共DNS服务器。

在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
```
登录后复制
请注意，nameserver后面的IP地址可能是由WSL或宿主机网络适配器自动分配的，这可能是导致解析失败的原因。
将nameserver行替换为公共DNS服务器地址，例如Google的8.8.8.8：
```
nameserver 8.8.8.8
```
登录后复制
保存并退出文件（在vim中，输入:wq然后按回车）。

步骤三：验证DNS配置并重新构建Sail

完成上述配置后，建议再次进行DNS验证：

在WSL终端中，尝试ping google.com。如果现在能够成功解析并接收到响应，则说明DNS配置已生效。

最后，回到Laravel项目目录，尝试重新构建并启动Sail服务：

./vendor/bin/sail up

登录后复制

此时，Sail应该能够正常从Docker Hub拉取镜像并构建服务，不再出现TLS handshake timeout错误。

总结

在WSL环境下使用Laravel Sail时，TLS handshake timeout错误通常是由于DNS解析问题导致的。通过禁用WSL自动生成resolv.conf并手动将其nameserver配置为可靠的公共DNS（如8.8.8.8），可以有效解决Docker构建过程中遇到的网络连接障碍。正确的DNS配置是确保开发环境稳定运行的关键一环。

以上就是解决Laravel Sail构建失败：WSL环境下的DNS配置指南的详细内容，更多请关注php中文网其它相关文章！