Laravel 8 中文文档 Laravel Sail

• 介绍
• 安装 & 设定
  • 安装 Sail 到当前应用中
  • 配置 Bash 别名
• 启动 & 停止 Sail
• 执行命令
  • 执行 PHP 命令
  • 执行 Composer 命令
  • 执行 Artisan 命令
  • 执行 Node / NPM 命令
• 与数据库交互
  • MySQL
  • Redis
• 运行测试
  • Laravel Dusk
• 预览电子邮件
• 容器 CLI
• PHP 版本
• 共享您的网站
• 定制化

介绍

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

Sail 的核心是 docker-compose.yml 文件和存储在项目根目录的 sail 脚本。sail 脚本为 CLI 提供了便捷的方法，可用于与 docker-compose.yml 文件定义的 Docker 容器进行交互。

Laravel Sail 支持 macOS、 Linux 和 Windows (通过 WSL2)。

安装 & 设定

Laravel Sail 会随着所有全新的 Laravel 应用程序一起自动安装，因此你可以立即的开始使用它. 要了解如何创建一个新的 Laravel 应用程序，请查阅适合您目前操作系统的 安装文档。

补充：此处是指一开始使用 Laravel 8.x 创建应用，若您还在使用先前的版本，或是由先前的版本升级至 8.x，请参照下述步骤安装 Sail 到您当前的应用.

安装 Sail 到当前应用中

假如您对使用 Sail 在您现有的 Laravel 应用感到兴趣，您可以透过 Composer 套件管理简单的安装 Sail. 当然，这些步骤是假设您现有的本地开发环境允许你安装 Copmoser 依赖：

composer require laravel/sail --dev

在 Sail 完成安装后，您可以运行 sail:install Artisan 命令. 这个命令将会发布 Sail 的 docker-compose.yml 文件到您应用程序的根目录:

php artisan sail:install

最后，您可以开始 Sail. 要继续学习如何使用 Sail，请接着阅读本文挡的其余部份:

./vendor/bin/sail up

配置 Bash 别名

默认情况下，Sail 命令使用 vendor/bin/sail 脚本调用，该脚本已包含在所有新建的 Laravel 应用程序中：

./vendor/bin/sail up

但与其重复的输入 vendor/bin/sail 来执行 Sail 命令，您可能会希望配置一个 Bash 别名方便你更容易的执行 Sail 命令：

alias sail='bash vendor/bin/sail'

补充: 透过 vim ~/.bashrc 加入别名，可以让别名常驻

一旦配置了 Bash 别名，您可以通过简单的键入 sail 来执行 Sail 命令. 本文接下来的示例都假定您已经配置了此别名:

sail up

启动 & 停止 Sail

Laravel Sail 的 docker-compose.yml 文件中定义了各种 Docker 容器，这些容器可以一起工作帮助您建构 Laravel 应用程序. 每一个容器都定义在 docker-compose.yml 文件中的 services 配置内. laravel.test 容器是为应用程序提供服务的主要应用程序容器。

在开始 Sail 之前，您应该确认没有其他的网站服务器或数据库正运行在您的本地计算机上. 要开始启用 docker-compose.yml 文件中定义的所有 Docker 容器，请执行 up 命令：

sail up

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

sail up -d

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

要停止所有容器，只需按 Control + C 即可停止容器的执行. 如果容器在后台运行，您可以使用 down 命令:

sail down

执行命令

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

当您阅读 Laravel 文档时，您可能经常看到在未使用 Sail 的状况下运行 Composer，Artisan 或是 Node / NPM 命令. 以下示例假设您已经在本地计算机上安装上述工具. 如果您打算使用 Sail 建构您的本地开发环境 ，您需要改用 Sail 运行这些命令:

# 在本地运行 Artisan 命令...
php artisan queue:work

# 在 Laravel Sail 中运行 Artisan 命令...
sail artisan queue:work

执行 PHP 命令

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

sail php --version

sail php script.php

执行 Composer 命令

Composer 命令可以使用 composer 命令执行. Laravel Sail 的应用程序容器中已经安装 Composer 2.x:

sail composer require laravel/sanctum

在已运行的应用中安装 Composer 依赖

假如您与团队一起开发应用程序，您也许不是最初创建 Laravel 应用程序的人. 因此，当您克隆应用程序的仓库到本地计算机后，将缺少安装 Composer 依赖也包含了 Sail.

您可以导航到应用程序目录下并执行以下命令来安装应用所需的依赖，这个命令使用一个包含 PHP 与 Composer 的小型 Docker 容器进行应用程序依赖的安装:

docker run --rm
    -v $(pwd):/opt
    -w /opt
    laravelsail/php80-composer:latest
    composer install

执行 Artisan 命令

Artisan 命令可以使用 artisan 命令执行:

sail artisan queue:work

执行 Node / NPM 命令

Node 命令可以使用 node 命令执行，而 NPM 命令可以使用 npm 命令执行:

sail node --version

sail npm run prod

与数据库交互

MySQL

您可能已经注意到，应用程序的 docker-compose.yml 文件包含一个 MySQL 容器的条目. 该容器使用了 Docker volume，以便即使在停止和重新启动容器时依然可以持久存储数据库中存储的数据. 另外，当 MySQL 容器启动时，它将确保存在名称与您的 DB_DATABASE 环境变量的值匹配的数据库.

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

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

Redis

应用程序的 docker-compose.yml 文件也包含 Redis 容器. 该容器使用 Docker volume，以便即使在停止和重新启动容器后，Redis 数据中存储的数据也可以持久保存. 启动容器后，可以通过将应用程序 .env 文件中的环境变量 REDIS_HOST 设置为 redis 来连接到应用程序中的 Redis 实例.

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

运行测试

Laravel 提供了出色的开箱即用测试，您可以使用 Sail 的 test 命令运行应用程序的 功能和单元测试. 任何 PHPUnit 可接受的 CLI 选项都可以透过 test 命令传递:

sail test

sail test --group orders

Sail test 命令相当于运行 Artisan test 命令:

sail artisan test

Laravel Dusk

Laravel Dusk 提供了非常优雅的，易于使用的浏览器自动化测试 API. 有了 Sail，进行浏览器测试更加方便了，甚至不用在你的本地电脑上安装 Selenium 或者任何其他工具. 要开启这项功能，请在 docker-compose.yml 文件中取消 Selenium 服务注释:

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

下一步，请确认 docker-compose.yml 文件中的 laravel.test 服务配置 depends_on 是否包含了 selenium 条目:

depends_on:
    - mysql
    - redis
    - selenium

最后，您可以透过启动 Sail 并运行 dusk 命令来进行 Dusk 测试:

sail dusk

预览电子邮件

Sail 默认的 docker-compose.yml 文件中包含了一个服务条目 MailHog. MailHog 会在你本地开发的过程中拦截应用程序发送的电子邮件，并提供一个便捷的 Web 界面，方便您透过浏览器预览电子邮件. 使用 Sail 时，MailHog 默认的主机名称是 mailhog 并使用 1025 端口:

MAIL_HOST=mailhog
MAIL_PORT=1025

当 Sail 运行时，您可以透过 http://localhost:8025 访问 MailHog 的 Web 界面.

容器 CLI

有时候，你可能想要在应用容器中开启一个 Bash 会话。 这时可以执行 shell 命令，然后你就可以访问容器中的文件和已安装的服务了，同时还可以执行其他任意指令:

sail shell

想打开一个新的 Laravel Tinker 会话，你可以执行 tinker 命令:

sail tinker

PHP 版本

Sail 目前支持通过 PHP 8.0 或 PHP 7.4 为您的应用程序提供服务. 想更改应用程序使用的 PHP 版本，请在 docker-compose.yml 文件定义的容器 laravel.test 中调整 build 定义:

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

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

此外，你如果想更新你的镜像名称来反映当前使用的 PHP 版本，您可以在 docker-compose.yml 文件中调整 image 字段:

image: sail-8.0/app

在修改过 docker-compose.yml 文件之后，您应该要重建容器镜像然后重启 Sail:

sail build --no-cache

sail up

共享您的网站

有时候您可能需要公开您的网站分享给同事或是测试应用与网路挂钩的集成。想共享您的网站时，可以使用 share 命令. 当您执行此命令后，将会获取一个随机的网址，例如 laravel-sail.site 用来访问您的应用程序:

sail share

假如您想自定子域名，您可以在执行 share 命令时加上 subdomain 参数:

sail share --subdomain=my-sail-site

share 命令由 Expose 提供， 一个开源的网络隧道服务 BeyondCode.

定制化

因为 Sail 就是 Docker，所以你可以自由的定制任何内容，使用 sail:publish 命令可以发布 Sail 自己的 Dockerfile 方便您定制:

php artisan sail:publish

运行这个命令后，在你的项目根目录下会生成一个 docker 目录，里面包含有关你应用的 Dockerfile 和其他配置文件。当您自行定制 Sail 配置之后，您必须使用 build 命令来重新构建容器:

sail build --no-cache

• Laravel Sail