Laravel 8.x Sail 文档
Laravel Sail
介绍
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
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: