Laravel Sail 开发环境部署一把过（疑难杂症篇）

(Updated: )
Laravel
, ,

故障排查概览

本文汇总了在 Windows （WSL2） + Docker 环境下运行 Laravel Sail 时可能遇到的高频问题。我们将从网络、资源、权限与性能四个维度进行分析与解决。

1. 网络连接问题

由于 Docker 镜像拉取及 Composer 依赖安装均需访问境外服务器，网络连接稳定性是环境部署的首要前提。

典型症状：

  • curl 安装脚本连接超时 （Connection refused）。
  • Docker 镜像拉取速度极慢或卡顿。
  • Composer 依赖安装失败。

解决方案：
建议在宿主机配置能够处理 TUN 流量的代理工具（如 v2rayN 开启 TUN 模式）。

  • 原理：TUN 模式在网络层接管所有流量，能够自动代理 WSL2 及 Docker 容器发出的请求，无需单独配置复杂的 HTTP_PROXY 环境变量或 Docker 镜像源。

2. 端口冲突

Docker 容器尝试绑定的宿主机端口已被占用。

典型症状：
sail up 启动失败，报错：

Error response from daemon: Ports are not available: listen tcp 0.0.0.0:80: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

根本原因：
Sail 默认绑定端口：

  • APP_PORT: 80 （常被 IIS, Apache, 或其他 Web 服务占用）
  • MySQL: 3306 （常被本地 MySQL 服务占用）

解决方案：
修改项目根目录 .env 文件，重映射 Docker 端口：

1
2
3
APP_PORT=8000
FORWARD_DB_PORT=33060
FORWARD_REDIS_PORT=63790

重启服务生效：sail up -d。

3. I/O 性能严重下降

典型症状：
页面加载延迟极高（>2s），文件读写缓慢。

根本原因：
跨文件系统访问。若项目代码存放于 Windows 文件系统（如 /mnt/c/Users/...），WSL2 需通过 9P 协议进行跨系统文件读写，性能损耗巨大。

最佳实践：
务必将项目代码存储于 WSL2 原生文件系统中（如 ~/code 或 /var/www）。

  • 错误路径：/mnt/c/Users/code/project
  • 正确路径：/home/code/project

4. 文件权限问题

典型症状：
应用日志无法写入，或缓存文件生成失败。

根本原因：
如果在 WSL2 中使用 root 用户（或者通过 sudo）执行了生成文件的命令，会导致文件所有者变为 root，而 Sail 容器内的 sail 用户（UID 1000）无权写入。

解决方案：

  1. 修复权限：使用 Sail 提供的辅助命令重置项目目录权限：
    1
    sail root-shell chown -R sail:sail .
  2. 预防措施：始终通过 sail 别名执行命令（如 sail npm install），避免直接使用 sudo。

5. 外部数据库连接

若需使用宿主机的 GUI 工具（如 Navicat, TablePlus）连接容器数据库：

  • Host: localhost （Docker Desktop 会自动将端口转发至宿主机）
  • Port: 3306 （或 .env 中定义的 FORWARD_DB_PORT）
  • User: sail
  • Password: password （或 .env 中定义的 DB_PASSWORD）

6. 磁盘空间回收

Docker Desktop 在 Windows 上使用 ext4.vhdx 虚拟磁盘文件存储数据。该文件具有“动态增长，但不自动缩容”的特性，长期使用可能导致占用大量磁盘空间。

解决方案：Purge Data

若需释放空间，可使用 Docker Desktop 自带的清理功能（注意：此操作将即时删除所有容器、镜像及数据卷）：

  1. 打开 Docker Desktop -> Troubleshoot （左下角启停按钮跟前的三个点的列表中）。
  2. 选择 Clean / Purge data。
  3. 勾选 Disk image 并点击 Delete。

重建环境：
清理完成后，只需在 WSL2 项目目录中执行两步即可完全恢复环境：

当然，若此过程进展不顺利，您大可放心删除 docker desktop，重新安装即可。

1
2
3
4
5
# 1. 重新拉取镜像并启动
sail up -d

# 2. 重建数据库结构
sail artisan migrate:fresh --seed

这也体现了 Infrastructure as Code 的优势：开发环境是可被快速销毁并重建的。

结语

至此，《Laravel Sail 开发环境部署一把过》 系列的技术内容告一段落。
通过标准化、容器化的开发环境，我们消除了环境差异带来的不确定性。希望本系列能协助 Windows 开发者构建高效、稳定的 Laravel 工作流。