Laravel 风帆

Introduction

Laravel 风帆 是一个轻量级的命令行界面，用于与 Laravel 的默认 Docker 开发环境进行交互。 Sail 为使用 PHP、MySQL 和 Redis 构建 Laravel 应用程序提供了一个很好的起点，而无需先前的 Docker 经验。

从本质上讲，Sail 是docker-compose.yml 文件和sail 存储在项目根目录中的脚本。这sail 脚本为 CLI 提供了方便的方法来与由定义的 Docker 容器进行交互docker-compose.yml 文件。

Laravel Sail 支持 macOS、Linux 和 Windows（通过WSL2).

安装与设置

Laravel Sail 会自动安装所有新的 Laravel 应用程序，因此您可以立即开始使用它。要了解如何创建新的 Laravel 应用程序，请参阅 Laravel 的安装文档 为您的操作系统。在安装过程中，您将被要求选择您的应用程序将与哪些 Sail 支持的服务进行交互。

将 Sail 安装到现有应用程序中

如果您有兴趣将 Sail 与现有的 Laravel 应用程序一起使用，您可以简单地使用 Composer 包管理器安装 Sail。当然，这些步骤假设您现有的本地开发环境允许您安装 Composer 依赖项：

composer require laravel/sail --dev

安装 Sail 后，您可以运行sail:install 工匠命令。此命令将发布 Sail 的docker-compose.yml 文件到应用程序的根目录：

php artisan sail:install

最后，您可以启动 Sail。要继续学习如何使用 Sail，请继续阅读本文档的其余部分：

./vendor/bin/sail up

添加附加服务

如果您想为现有的 Sail 安装添加额外的服务，您可以运行sail:add 工匠命令：

php artisan sail:add

使用开发容器

如果你想在一个Devcontainer, 你可以提供--devcontainer 的选项sail:install 命令。这--devcontainer 选项将指示sail:install 发布默认值的命令.devcontainer/devcontainer.json 文件到应用程序的根目录：

php artisan sail:install --devcontainer

配置 Shell 别名

默认情况下，Sail 命令是使用vendor/bin/sail 所有新的 Laravel 应用程序都包含的脚本：

./vendor/bin/sail up

但是，而不是重复输入vendor/bin/sail 要执行 Sail 命令，您可能希望配置一个 shell 别名，使您可以更轻松地执行 Sail 的命令：

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

为了确保它始终可用，您可以将其添加到您的主目录中的 shell 配置文件中，例如~/.zshrc 或者~/.bashrc，然后重新启动 shell。

配置 shell 别名后，您只需键入即可执行 Sail 命令sail.本文档的其余示例将假定您已配置此别名：

sail up

启动和停止航行

Laravel 帆的docker-compose.yml 文件定义了多种 Docker 容器，它们协同工作以帮助您构建 Laravel 应用程序。这些容器中的每一个都是services 你的配置docker-compose.yml 文件。这laravel.test 容器是将为您的应用程序提供服务的主要应用程序容器。

在启动 Sail 之前，您应该确保没有其他 Web 服务器或数据库正在您的本地计算机上运行。启动应用程序中定义的所有 Docker 容器docker-compose.yml 文件，你应该执行up命令：

sail up

要在后台启动所有 Docker 容器，您可以在“分离”模式下启动 Sail：

sail up -d

启动应用程序的容器后，您可以在 Web 浏览器中访问该项目：http://localhost.

要停止所有容器，您只需按 Control + C 即可停止容器的执行。或者，如果容器在后台运行，您可以使用stop 命令：

sail stop

执行命令

使用 Laravel Sail 时，您的应用程序在 Docker 容器中执行，并与本地计算机隔离。但是，Sail 提供了一种方便的方法来对您的应用程序运行各种命令，例如任意 PHP 命令、Artisan 命令、Composer 命令和 Node / NPM 命令。

在阅读 Laravel 文档时，您会经常看到对 Composer、Artisan 和 Node / NPM 命令的引用，而没有引用 Sail。 这些示例假定这些工具安装在您的本地计算机上。如果您在本地 Laravel 开发环境中使用 Sail，则应该使用 Sail 执行这些命令：

# Running Artisan commands locally...
php artisan queue:work

# Running Artisan commands within Laravel Sail...
sail artisan queue:work

执行 PHP 命令

PHP 命令可以使用php 命令。当然，这些命令将使用为您的应用程序配置的 PHP 版本执行。要了解有关 Laravel Sail 可用的 PHP 版本的更多信息，请参阅PHP版本文档:

sail php --version

sail php script.php

执行作曲家命令

Composer命令可以使用composer 命令。 Laravel Sail 的应用程序容器包括一个 Composer 2.x 安装：

sail composer require laravel/sanctum

为现有应用程序安装 Composer 依赖项

如果您正在与团队一起开发应用程序，您可能不是最初创建 Laravel 应用程序的人。因此，在您将应用程序的存储库克隆到本地计算机后，不会安装应用程序的任何 Composer 依赖项，包括 Sail。

您可以通过导航到应用程序的目录并执行以下命令来安装应用程序的依赖项。此命令使用包含 PHP 和 Composer 的小型 Docker 容器来安装应用程序的依赖项：

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php82-composer:latest \
    composer install --ignore-platform-reqs

当使用laravelsail/phpXX-composer 图像，您应该使用您计划用于您的应用程序的相同版本的 PHP（74,80,81， 或者82).

执行工匠命令

Laravel Artisan 命令可以使用artisan 命令：

sail artisan queue:work

执行节点/NPM 命令

节点命令可以使用node 命令，而 NPM 命令可以使用npm 命令：

sail node --version

sail npm run dev

如果你愿意，你可以使用 Yarn 而不是 NPM：

sail yarn

与数据库交互

MySQL

您可能已经注意到，您的应用程序的docker-compose.yml 文件包含 MySQL 容器的条目。这个容器使用码头工人卷 这样存储在数据库中的数据即使在停止和重新启动容器时也能保留。

另外，MySQL容器第一次启动时，会为你创建两个数据库。第一个数据库使用您的值命名DB_DATABASE 环境变量，用于您的本地开发。第二个是名为的专用测试数据库testing 并将确保您的测试不会干扰您的开发数据。

启动容器后，您可以通过设置您的应用程序连接到 MySQL 实例DB_HOST 应用程序中的环境变量.env 归档到mysql.

要从本地计算机连接到应用程序的 MySQL 数据库，您可以使用图形数据库管理应用程序，例如TablePlus.默认情况下，可以访问 MySQL 数据库localhost 端口 3306 和访问凭据对应于您的值DB_USERNAME 和DB_PASSWORD 环境变量。或者，您可以连接为root 用户，这也利用了你的价值DB_PASSWORD 环境变量作为其密码。

Redis

你的应用程序docker-compose.yml 文件还包含一个条目Redis 容器。这个容器使用码头工人卷 这样即使在停止和重新启动容器时，存储在 Redis 数据中的数据也会保留。启动容器后，您可以通过设置您的应用程序连接到 Redis 实例REDIS_HOST应用程序中的环境变量.env 归档到redis.

要从本地计算机连接到应用程序的 Redis 数据库，您可以使用图形数据库管理应用程序，例如TablePlus.默认情况下，可以访问 Redis 数据库localhost 端口 6379。

MeiliSearch

如果您选择安装MeiliSearch 安装 Sail 时的服务，您的应用程序的docker-compose.yml 文件将包含这个强大的搜索引擎的条目compatible 和Laravel 侦察兵.启动容器后，您可以通过设置您的应用程序连接到 Meil​​iSearch 实例MEILISEARCH_HOST 环境变量到http://meilisearch:7700.

从您的本地计算机，您可以访问 Meil​​iSearch 的基于 Web 的管理面板，方法是导航到http://localhost:7700 在您的网络浏览器中。

档案储存

如果您计划在其生产环境中运行您的应用程序时使用 Amazon S3 来存储文件，您可能希望安装MinIO 安装 Sail 时的服务。 MinIO 提供了一个 S3 兼容的 API，你可以使用它来使用 Laravel 的本地开发s3 文件存储驱动程序，而无需在生产 S3 环境中创建“测试”存储桶。如果您在安装 Sail 时选择安装 MinIO，则 MinIO 配置部分将添加到您的应用程序的docker-compose.yml 文件。

默认情况下，您的应用程序的filesystems 配置文件已包含磁盘配置s3 磁盘。除了使用此磁盘与 Amazon S3 交互外，您还可以使用它与任何 S3 兼容的文件存储服务（例如 MinIO）进行交互，只需修改控制其配置的关联环境变量即可。例如，当使用 MinIO 时，你的文件系统环境变量配置应该定义如下：

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

为了让 Laravel 的 Flysystem 集成在使用 MinIO 时生成正确的 URL，你应该定义AWS_URL 环境变量，使其与应用程序的本地 URL 匹配，并在 URL 路径中包含存储桶名称：

AWS_URL=http://localhost:9000/local

您可以通过 MinIO 控制台创建存储桶，该控制台位于http://localhost:8900. MinIO 控制台的默认用户名是sail 而默认密码是password.

Warning
通过生成临时存储 URLtemporaryUrl 使用 MinIO 时不支持方法。

运行测试

Laravel 开箱即用地提供了惊人的测试支持，您可以使用 Sail 的test 运行应用程序的命令功能和单元测试. PHPUnit 接受的任何 CLI 选项也可以传递给test 命令：

sail test

sail test --group orders

风帆test 命令相当于运行test 工匠命令：

sail artisan test

默认情况下，Sail 会创建一个专门的testing 数据库，以便您的测试不会干扰数据库的当前状态。在默认的 Laravel 安装中，Sail 也会配置你的phpunit.xml 执行测试时使用此数据库的文件：

<env name="DB_DATABASE" value="testing"/>

Laravel 黄昏

Laravel 黄昏 提供了一个富有表现力、易于使用的浏览器自动化和测试 API。感谢 Sail，您无需在本地计算机上安装 Selenium 或其他工具就可以运行这些测试。首先，取消注释应用程序中的 Selenium 服务docker-compose.yml 文件：

selenium:
    image: 'selenium/standalone-chrome'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

接下来，确保laravel.test 应用程序中的服务docker-compose.yml 文件有一个depends_on 进入selenium:

depends_on:
    - mysql
    - redis
    - selenium

最后，您可以通过启动 Sail 并运行dusk 命令：

sail dusk

苹果硅上的硒

如果您的本地机器包含 Apple Silicon 芯片，您的selenium 服务必须使用seleniarm/standalone-chromium 图像：

selenium:
    image: 'seleniarm/standalone-chromium'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

预览电子邮件

Laravel Sail 的默认docker-compose.yml 文件包含一个服务条目Mailpit. Mailpit 在本地开发期间拦截您的应用程序发送的电子邮件，并提供方便的 Web 界面，以便您可以在浏览器中预览您的电子邮件。使用 Sail 时，Mailpit 的默认主机是mailpit 并可通过端口 1025 访问：

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

当 Sail 运行时，您可以访问 Mailpit Web 界面：http://localhost:8025

容器 CLI

有时您可能希望在应用程序的容器内启动 Bash 会话。您可以使用shell 命令连接到应用程序的容器，允许您检查其文件和已安装的服务以及在容器内执行任意 shell 命令：

sail shell

sail root-shell

开始新的Laravel 修补匠 会话，你可以执行tinker 命令：

sail tinker

PHP 版本

Sail 目前支持通过 PHP 8.2、8.1、PHP 8.0 或 PHP 7.4 为您的应用程序提供服务。 Sail 使用的默认 PHP 版本目前是 PHP 8.2。要更改用于为您的应用程序提供服务的 PHP 版本，您应该更新build 的定义laravel.test 应用程序中的容器docker-compose.yml 文件：

# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2

# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1

# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

# PHP 7.4
context: ./vendor/laravel/sail/runtimes/7.4

此外，您可能希望更新您的image 名称以反映您的应用程序使用的 PHP 版本。此选项也在您的应用程序中定义docker-compose.yml 文件：

image: sail-8.1/app

更新您的应用程序后docker-compose.yml 文件，你应该重建你的容器镜像：

sail build --no-cache

sail up

节点版本

Sail 默认安装 Node 18。要更改构建图像时安装的节点版本，您可以更新build.args 的定义laravel.test 应用程序中的服务docker-compose.yml 文件：

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '14'

更新您的应用程序后docker-compose.yml 文件，你应该重建你的容器镜像：

sail build --no-cache

sail up

分享您的网站

有时您可能需要公开共享您的网站以便为同事预览您的网站或测试 webhook 与您的应用程序的集成。要共享您的网站，您可以使用share 命令。执行此命令后，您将获得一个随机的laravel-sail.site 您可以用来访问您的应用程序的 URL：

sail share

通过以下方式共享您的网站时share 命令，您应该在TrustProxies 中间件。否则，URL 生成助手如url 和route 将无法确定在 URL 生成期间应使用的正确 HTTP 主机：

/**
 * The trusted proxies for this application.
 *
 * @var array|string|null
 */
protected $proxies = '*';

如果您想为您的共享站点选择子域，您可以提供subdomain 执行时的选项share 命令：

sail share --subdomain=my-sail-site

Note
这share 命令由Expose，一个开源隧道服务，由BeyondCode.

使用 Xdebug 调试

Laravel Sail 的 Docker 配置包括对Xdebug，一种流行且功能强大的 PHP 调试器。为了启用 Xdebug，您需要将一些变量添加到您的应用程序的.env 归档到配置 Xdebug.要启用 Xdebug，您必须在启动 Sail 之前设置适当的模式：

SAIL_XDEBUG_MODE=develop,debug,coverage

Linux主机IP配置

在内部，XDEBUG_CONFIG 环境变量定义为client_host=host.docker.internal 这样 Xdebug 就会针对 Mac 和 Windows (WSL2) 进行正确配置。如果您的本地计算机运行的是 Linux，则应确保您运行的是 Docker Engine 17.06.0+ 和 Compose 1.16.0+。否则，您将需要手动定义此环境变量，如下所示。

首先，您应该通过运行以下命令来确定要添加到环境变量中的正确主机 IP 地址。通常，<container-name> 应该是为您的应用程序提供服务的容器的名称，通常以_laravel.test_1:

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

获得正确的主机 IP 地址后，您应该定义SAIL_XDEBUG_CONFIG 应用程序中的变量.env 文件：

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

Xdebug CLI 用法

Asail debug 命令可用于在运行 Artisan 命令时启动调试会话：

# Run an Artisan command without Xdebug...
sail artisan migrate

# Run an Artisan command with Xdebug...
sail debug migrate

Xdebug 浏览器使用

要在通过 Web 浏览器与应用程序交互时调试您的应用程序，请遵循Xdebug 提供的说明 用于从 Web 浏览器启动 Xdebug 会话。

如果您使用的是 PhpStorm，请查看 JetBrain 的有关文档零配置调试.

Warning
Laravel Sail 依赖artisan serve 为您的应用程序提供服务。这artisan serve 命令只接受XDEBUG_CONFIG 和XDEBUG_MODE Laravel 版本 8.53.0 的变量。旧版本的 Laravel（8.52.0 及以下）不支持这些变量，并且不接受调试连接。

Customization

由于 Sail 只是 Docker，您几乎可以自由定制它的所有内容。要发布 Sail 自己的 Dockerfile，您可以执行sail:publish 命令：

sail artisan sail:publish

运行此命令后，Laravel Sail 使用的 Dockerfiles 和其他配置文件将放置在一个docker 应用程序根目录中的目录。自定义 Sail 安装后，您可能希望更改应用程序容器中的图像名称docker-compose.yml 文件。这样做之后，使用build 命令。如果您使用 Sail 在一台机器上开发多个 Laravel 应用程序，则为应用程序映像分配一个唯一的名称尤为重要：

sail build --no-cache
豫ICP备18041297号-2
Please enter a query in order to search.