本文深入探讨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文件。
- 保存并退出文件（在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这种虚拟化环境中。
