Windows Docker 下 Laravel 访问极慢的排查与迁移 WSL2 方案

参考链接

0. 豆包
1. CSDN - WSL2 相关配置
2. 腾讯云开发者社区 - Docker 与 WSL2
3. 知乎 - WSL2 使用实践
4. 简书 - WSL2 开发环境搭建
5. CSDN - Docker 在 WSL2 中的性能优化
6. CSDN - Windows Docker 性能问题排查

环境

软件/系统	版本	说明
Windows 10 专业版	10.0.19045	开发主机
Docker Engine	29.5.3
WSL2	2.7.10.0
Ubuntu	Ubuntu 22.04 LTS
VS Code	1.128.1
Remote Development	0.26.0	VS Code 插件

问题

在 Windows + Docker 下搭建 LNMP 环境，运行一个几乎没有任何数据的 Laravel 空项目。
预期空项目应当快速响应，实际每次页面访问耗时 2~4 秒。

原因分析

核心原因：Windows 与 Docker 容器之间的文件挂载与转换涉及多个步骤，导致 I/O 性能极差。

具体链路如下：

1. Docker Desktop 使用 Hyper-V 或 WSL2 后端，但项目文件位于 Windows 的 NTFS 磁盘上。
2. 容器（Linux）访问这些文件时，需经过文件系统翻译层（如 9p/drvfs），将 Windows 路径映射为 Linux 路径。
3. Laravel 启动时需加载大量小文件（vendor 依赖、自动加载、config、bootstrap 等），每次文件读写都要经过翻译层。
4. 文件数量与翻译开销叠加，最终形成 2~4 秒的访问延迟。

解决思路：将项目文件放到 Linux 原生文件系统（WSL2 的 Ubuntu 内），使容器直接读写 Linux 文件，消除中间翻译层，从而恢复 I/O 性能。

---

迁移步骤

1. 安装 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install

该命令会自动启用所需组件、下载 Linux 内核并安装 Ubuntu。

wsl --set-default-version 2

2. 安装 Ubuntu 发行版

在 Microsoft Store 搜索并安装 Ubuntu（建议 LTS 版本，如 Ubuntu 22.04）。首次启动需设置用户名与密码。

若步骤 1 已使用 wsl --install，Ubuntu 通常已一并安装，可跳过本步。

3. 为 Docker 启用 WSL2 集成

部分时候 wsl 的 ubuntu 是 wsl1 版本，通过下面的命令进行切换，docker 就可以正常支持了。

wsl --set-version ubuntu 2

进入 Settings → Resources → WSL Integration，勾选：

• Enable integration with my default WSL distro
• 已安装的 Ubuntu 发行版

点击 Apply & Restart，Docker 将在 WSL2 的 Ubuntu 中运行并共享其文件系统。

4. 将项目放入 WSL2 目录

关键点：不要将项目放在 C:\Users\... 等 Windows 路径下。

打开 Ubuntu 终端（或在文件管理器地址栏输入 \\wsl$\Ubuntu），将项目与 docker-compose.yml 放到 Ubuntu 家目录：

mkdir -p ~/projects/my-laravel
cd ~/projects/my-laravel
git clone <你的项目地址> .

原则：所有涉及容器挂载的目录，均应位于 WSL2 的 Linux 文件系统内（/home/xxx/...），避免跨系统挂载。

5. 启动项目

在 WSL2 终端进入项目目录，使用 Docker Compose 启动：

cd ~/projects/my-laravel
docker compose up -d

此时容器访问的是 Linux 原生文件，I/O 性能显著提升，页面访问耗时降至数百毫秒。

6. 安装远程插件

在 VS Code 扩展商店搜索并安装 Remote - WSL（或 Remote Development 扩展包）。

安装后 VS Code 会自动检测已安装的 WSL2 发行版。点击左下角绿色图标 ><，选择 New Window using WSL，即可在 Ubuntu 环境中打开项目。

7. 通过 VS Code 远程连接开发

VS Code 会自动检测 WSL 远程，邮件连接即可

8. 在 WSL2 中通过 VS Code 开发

在 Ubuntu 中执行 Code . 会自动安装相关依赖，并在编辑器中打开对应目录

五、常见问题

问题 1：访问出现权限不足（Permission denied）

文件从 Windows 拷贝或经 git 拉取到 WSL2 后，所有者与权限可能不正确，Laravel 的 storage、bootstrap/cache 等目录需可写。

解决方案：为项目目录授权。

cd ~/projects/my-laravel
sudo chown -R $USER:$USER .
chmod -R 755 storage bootstrap/cache
# 视情况给写权限
chmod -R 777 storage bootstrap/cache

问题 2：无需手动配置 WSL2 的 hosts

WSL2 会自动引入 Windows 的 hosts 配置。

在 Windows 的 C:\Windows\System32\drivers\etc\hosts 中配置的域名映射（如 127.0.0.1 local.docker.xxx.com），在 WSL2 中同样生效，无需重复配置。

问题 3：WSL2 内无需安装项目运行环境

迁移后无需在 Ubuntu 中另装 PHP、Composer、MySQL 等。

项目运行环境（PHP、Nginx、MySQL、Redis 等）均已在 Docker 容器内，WSL2 仅负责存放文件与运行 Docker。

若项目需执行环境相关命令（如 composer install、php artisan migrate），进入对应容器执行：

docker compose exec php bash
# 容器内部
composer install
php artisan migrate

此方式可保证命令运行环境与容器环境一致，避免环境差异导致的问题。