Laravel Sail通过Docker提供一致、隔离的开发环境，支持一键启动PHP、Nginx、MySQL、Redis等服务，相比MAMP/XAMPP具有环境一致性、服务易扩展、配置灵活等优势；使用./vendor/bin/sail up启动环境，通过sail artisan、sail composer执行命令，可轻松管理应用；常见问题如端口冲突可通过修改docker-compose.yml解决，日志查看和容器Shell访问便于故障排查。

Laravel Sail让本地Laravel开发环境的搭建变得异常轻松，它通过Docker容器提供了一套预配置的服务栈，涵盖了PHP、Web服务器（Nginx/Apache）、数据库（MySQL/PostgreSQL）、缓存（Redis）、邮件调试（Mailhog）等，开发者只需几个命令就能启动一个功能完备的开发环境，极大地简化了环境配置的复杂性。

解决方案

启动Laravel Sail开发环境，首先确保你的系统上已经安装了Docker Desktop（对于Windows和macOS用户）或Docker Engine（对于Linux用户）。这是Sail运行的基础。

如果你正在创建一个全新的Laravel项目，可以直接通过Composer或Laravel安装器来初始化一个带有Sail的项目：

# 使用Laravel安装器 laravel new my-project --sail  # 或者使用Composer composer create-project laravel/laravel my-project --prefer-dist --sail

这个命令不仅会创建一个新的Laravel项目，还会自动生成一个 docker-compose.yml 文件和相关的Sail配置。

如果你的Laravel项目已经存在，并且你希望为其添加Sail支持，可以这样做：

cd your-project-directory composer require laravel/sail --dev php artisan sail:install

php artisan sail:install 命令会提示你选择需要包含的服务，例如 MySQL、Redis、Mailhog 等。选择完成后，它会生成对应的 docker-compose.yml 文件。

项目初始化或Sail安装完成后，进入项目根目录：

cd my-project

然后，通过以下命令启动Sail环境：

./vendor/bin/sail up

或者，为了方便，你可以将 sail 命令添加到你的shell别名中，这样以后就可以直接使用 sail up 了：

alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'

当所有服务容器成功启动后，你就可以在浏览器中访问 http://localhost 来查看你的Laravel应用了。Sail默认会将应用的HTTP服务映射到本地的80端口。

Laravel Sail与传统本地开发环境（如MAMP/XAMPP）相比有何优势？

我个人在开发初期，也曾是MAMP/XAMPP的忠实用户，它们确实在一定程度上简化了PHP环境的搭建。但当我转向Laravel Sail后，我发现这简直是降维打击，体验上的提升是全方位的。

Sail最核心的优势在于其环境的一致性和隔离性。想想看，你和团队成员可能用着不同版本的操作系统，或者本地安装了各种奇奇怪怪的PHP扩展和数据库版本。MAMP/XAMPP往往意味着每个人本地环境都可能存在细微差异，这经常导致“在我机器上没问题啊”的尴尬局面。Sail则通过Docker确保了每个开发者都运行在几乎完全相同的、容器化的环境中，大大减少了这类问题的发生。每个项目都有自己独立的PHP版本、数据库实例和依赖，彼此互不干扰，完美解决了端口冲突和版本兼容性的噩梦。

其次是服务的可扩展性和管理。在MAMP/XAMPP中，要添加Redis、Mailhog或者换个数据库类型，往往需要手动安装、配置，过程繁琐且容易出错。Sail则不同，它通过简单的 docker-compose.yml 配置，就能轻松地添加、移除或升级各种服务。比如，想用PostgreSQL而不是MySQL？修改一行配置，sail up -d 重启一下就行，效率高得不是一点半点。这种灵活性和易用性，让开发者能更专注于代码本身，而不是环境配置。

最后，Sail还带来了更强的可移植性。一个新成员加入团队，或者你需要在另一台电脑上继续工作，只需要克隆项目代码，确保Docker运行，然后 sail up，一切就绪。这比手动配置整个开发环境要省心得多，也让团队协作变得更加顺畅。对我来说，Sail的出现，彻底改变了本地开发的体验，让它变得更加现代化和高效。

在使用Laravel Sail时，常见的配置调整和故障排除有哪些？

尽管Laravel Sail已经非常方便，但在实际使用中，我们偶尔还是会遇到一些需要调整或排查的问题。这很正常，毕竟没有哪个工具是百分百“傻瓜式”的。

常见的配置调整：

1. 修改默认端口： 如果你的本地80端口被其他应用占用（比如你可能同时运行着其他Web服务器），Sail启动时会报错。你可以编辑项目根目录下的 docker-compose.yml 文件，找到 laravel.test 服务下的 ports 部分，将其修改为其他未占用的端口，例如：

   

   即构数智人

   即构数智人是由即构科技推出的AI虚拟数字人视频创作平台，支持数字人形象定制、短视频创作、数字人直播等。

   41

   查看详情

   ports:     - '${app_PORT:-8080}:80' # 将80改为8080，这样就可以通过http://localhost:8080访问

   同时，你可能还需要在 .env 文件中设置 APP_PORT=8080。

2. 调整PHP版本： Sail默认会使用推荐的PHP版本。如果你的项目需要特定的PHP版本，可以在 docker-compose.yml 文件中修改 php 服务的 image 字段，例如：

   php:     image: 'laravelsail/php82-composer:latest' # 使用PHP 8.2

   记得 sail build –no-cache 然后 sail up -d 来重建并启动容器。

3. 自定义数据库凭证： 默认情况下，Sail的MySQL服务会在 .env 文件中设置 DB_HOST=mysql，DB_DATABASE=laravel，DB_USERNAME=sail，DB_PASSWORD=password。这些都是可以根据你的需求修改的。重要的是，DB_HOST 应该始终指向 docker-compose.yml 中定义的数据库服务名称（例如 mysql 或 pgsql），而不是 localhost。

4. 添加或移除服务： docker-compose.yml 是Sail的核心。如果你需要添加MongoDB、MeiliSearch等服务，或者移除不需要的服务，直接编辑这个文件即可。每个服务都有其独立的配置块，通常只需要复制粘贴并稍作修改。

常见的故障排除：

1. 容器启动失败（端口冲突）：这是最常见的问题。如果 sail up 报错提示端口已被占用，那很可能是你的本地机器上其他程序（如Apache、Nginx、Skype等）正在使用80、443或MySQL的3306端口。解决办法是修改Sail的端口（如上面所述），或者关闭占用端口的程序。netstat -ano (Windows) 或 lsof -i :<port> (Linux/macOS) 可以帮助你查找占用端口的进程。

2. sail up 后应用无法访问或显示错误：

   • Docker Desktop是否运行？ 确保Docker应用在后台正常运行。
   • 容器是否真的启动成功？ 使用 docker ps 命令检查所有Sail相关的容器是否都在 Up 状态。
   • 查看容器日志： 如果某个容器（特别是 laravel.test 或 php 服务）启动失败，使用 sail logs <service_name>（例如 sail logs laravel.test 或 sail logs php）可以查看详细的错误信息，这通常能帮你定位问题。
   • 文件权限问题： 在Linux或WSL环境下，有时 storage 和 bootstrap/cache 目录的权限会不正确，导致应用无法写入文件。可以尝试运行 sail artisan storage:link 或手动设置权限：sudo chmod -R 777 storage bootstrap/cache。
   • .env 文件未配置或配置错误： 确保 .env 文件存在且数据库等配置正确。

3. composer install 或 npm install 失败： 有时容器内的网络连接可能不稳定，或者镜像源速度慢。可以尝试更换Composer或NPM的镜像源，或者清理Docker缓存并重试：sail down –rmi all -v (这会删除所有容器、网络和卷，慎用，但通常能解决顽固问题)，然后 sail up。

遇到问题时，我通常会先检查日志，这就像是医生诊断病症的“望闻问切”。大部分Sail的问题，通过查看容器日志、检查 docker-compose.yml 和 .env 文件，以及确认Docker Desktop的运行状态，都能找到解决思路。

如何在Laravel Sail环境中执行Artisan命令和Composer操作？

在Laravel Sail环境中，执行Artisan命令和Composer操作的方式非常直观，它通过 sail 脚本提供了一个统一的接口，让你感觉就像在本地直接运行这些命令一样，但实际上它们是在Docker容器内部执行的。这避免了本地PHP版本、依赖等可能带来的冲突。

执行Artisan命令： 所有你需要通过 php artisan 运行的命令，都可以直接通过 sail artisan 来调用。例如：

• 运行数据库迁移：

  sail artisan migrate
• 创建控制器：

  sail artisan make:controller UserController
• 生成Seeder：

  sail artisan make:seeder UserSeeder
• 清除缓存：

  sail artisan cache:clear

这样做的优势在于，sail artisan 会确保这些命令是在Sail的PHP服务容器中执行的，它会使用容器内安装的PHP版本和所有项目依赖，避免了本地PHP环境可能带来的不匹配问题。

执行Composer操作： 同样地，所有Composer相关的命令，都可以通过 sail composer 来执行。

• 安装项目依赖：

  sail composer install
• 更新项目依赖：

  sail composer update
• 安装新的Composer包：

  sail composer require spatie/laravel-permission

这确保了Composer在容器内的PHP环境中运行，使用了容器内预装的Composer版本和正确的PHP配置。

执行NPM/Yarn（前端资产）： 如果你在Laravel项目中处理前端资产，比如使用Vue或React，你也会用到NPM或Yarn。Sail也为这些提供了便捷的接口：

• 安装前端依赖：

  sail npm install # 或者 sail yarn install
• 编译前端资产：

  sail npm run dev # 或者 sail yarn dev

获取容器Shell： 有时候，你可能需要更深入地进入某个容器内部进行调试，或者执行一些 sail 脚本没有直接封装的命令。你可以使用 sail bash 命令来获取PHP服务容器的Shell：

sail bash

进入容器后，你就可以像在普通Linux环境中一样，执行各种命令，比如 ls、cat、php -v 等。完成操作后，输入 exit 即可退出容器Shell。

对我而言，sail 脚本的这种封装设计极大地提升了开发效率。我不再需要手动 docker exec 进入容器，然后运行命令，这在以前是常态。现在，所有与项目相关的命令行操作都通过一个统一的 sail 前缀来完成，这让工作流变得更加流畅和一致。

以上就是Laravel Sail如何启动开发环境_基于Docker的本地开发环境的详细内容，更多请关注mysql php linux vue react word laravel redis 前端 bootstrap go php laravel bash composer mysql nginx bootstrap npm yarn 封装 接口 栈 windows docker macos redis mongodb postgresql 数据库 apache http linux