跳到内容

Laravel Valet

简介

正在寻找一种在 macOS 或 Windows 上开发 Laravel 应用程序的更简单方法?查看 Laravel Herd。Herd 包含开始 Laravel 开发所需的一切,包括 Valet、PHP 和 Composer。

Laravel Valet 是 macOS 极简主义者的开发环境。Laravel Valet 配置您的 Mac 以在机器启动时始终在后台运行 Nginx。然后,使用 DnsMasq,Valet 代理 *.test 域上的所有请求,以指向安装在您本地机器上的站点。

换句话说,Valet 是一个速度极快的 Laravel 开发环境,大约使用 7 MB 的 RAM。Valet 不是 SailHomestead 的完整替代品,但如果您想要灵活的基础知识、喜欢极致速度或在 RAM 有限的机器上工作,它提供了一个很好的替代方案。

开箱即用,Valet 支持包括但不限于

但是,您可以扩展 Valet 与您自己的 自定义驱动程序

安装

Valet 需要 macOS 和 Homebrew。在安装之前,您应该确保没有其他程序(如 Apache 或 Nginx)绑定到您本地机器的 80 端口。

要开始使用,您首先需要使用 update 命令确保 Homebrew 是最新的

1brew update

接下来,您应该使用 Homebrew 安装 PHP

1brew install php

安装 PHP 后,您就可以安装 Composer 包管理器了。此外,您应该确保 $HOME/.composer/vendor/bin 目录在您的系统 “PATH” 中。安装 Composer 后,您可以将 Laravel Valet 安装为全局 Composer 包

1composer global require laravel/valet

最后,您可以执行 Valet 的 install 命令。这将配置和安装 Valet 和 DnsMasq。此外,Valet 依赖的守护程序将被配置为在您的系统启动时启动

1valet install

安装 Valet 后,尝试在您的终端上使用类似 ping foobar.test 的命令 ping 任何 *.test 域。如果 Valet 安装正确,您应该看到此域在 127.0.0.1 上响应。

每次您的机器启动时,Valet 都会自动启动其所需的服务。

PHP 版本

您可以指示 Valet 通过 isolate 命令为每个站点使用不同的 PHP 版本,而不是修改您的全局 PHP 版本。

Valet 允许您使用 valet use php@version 命令切换 PHP 版本。如果指定的 PHP 版本尚未安装,Valet 将通过 Homebrew 安装它

2 
3valet use php

您还可以在项目的根目录中创建一个 .valetrc 文件。.valetrc 文件应包含站点应使用的 PHP 版本

1php=php@8.2

创建此文件后,您可以简单地执行 valet use 命令,该命令将通过读取文件来确定站点的首选 PHP 版本。

即使您安装了多个 PHP 版本,Valet 一次只服务一个 PHP 版本。

数据库

如果您的应用程序需要数据库,请查看 DBngin,它提供了一个免费的一体化数据库管理工具,包括 MySQL、PostgreSQL 和 Redis。安装 DBngin 后,您可以使用 root 用户名和空字符串密码连接到 127.0.0.1 上的数据库。

重置您的安装

如果您在让 Valet 安装正常运行方面遇到问题,执行 composer global require laravel/valet 命令,然后执行 valet install 将重置您的安装,并可以解决各种问题。在极少数情况下,可能需要通过执行 valet uninstall --force,然后执行 valet install 来 “硬重置” Valet。

升级 Valet

您可以通过在终端中执行 composer global require laravel/valet 命令来更新您的 Valet 安装。升级后,最好运行 valet install 命令,以便 Valet 可以在必要时对您的配置文件进行其他升级。

升级到 Valet 4

如果您要从 Valet 3 升级到 Valet 4,请按照以下步骤正确升级您的 Valet 安装

  • 如果您已添加 .valetphprc 文件以自定义站点的 PHP 版本,请将每个 .valetphprc 文件重命名为 .valetrc 文件。然后,在 .valetrc 文件的现有内容前添加 php=
  • 更新任何自定义驱动程序,以匹配新驱动程序系统的命名空间、扩展名、类型提示和返回类型提示。您可以参考 Valet 的 SampleValetDriver 作为示例。
  • 如果您使用 PHP 7.1 - 7.4 来服务您的站点,请确保您仍然使用 Homebrew 安装 PHP 8.0 或更高版本,因为 Valet 将使用此版本来运行其某些脚本,即使它不是您的主要链接版本。

服务站点

安装 Valet 后,您就可以开始服务您的 Laravel 应用程序了。Valet 提供了两个命令来帮助您服务您的应用程序:parklink

park 命令

park 命令在您的机器上注册一个包含您的应用程序的目录。一旦目录通过 Valet “parked”,该目录内的所有目录都将在您的 Web 浏览器中通过 http://<directory-name>.test 访问

1cd ~/Sites
2 
3valet park

这就是全部内容。现在,您在 “parked” 目录中创建的任何应用程序都将自动使用 http://<directory-name>.test 约定进行服务。因此,如果您的 parked 目录包含一个名为 “laravel” 的目录,则该目录中的应用程序将可通过 http://laravel.test 访问。此外,Valet 自动允许您使用通配符子域名(http://foo.laravel.test)访问该站点。

link 命令也可用于服务您的 Laravel 应用程序。如果您想服务目录中的单个站点,而不是整个目录,则此命令很有用

1cd ~/Sites/laravel
2 
3valet link

一旦应用程序使用 link 命令链接到 Valet,您可以使用其目录名称访问该应用程序。因此,在上面的示例中链接的站点可以通过 http://laravel.test 访问。此外,Valet 自动允许您使用通配符子域名(http://foo.laravel.test)访问该站点。

如果您想在不同的主机名上服务应用程序,您可以将主机名传递给 link 命令。例如,您可以运行以下命令,使应用程序在 http://application.test 上可用

1cd ~/Sites/laravel
2 
3valet link application

当然,您也可以使用 link 命令在子域名上服务应用程序

1valet link api.application

您可以执行 links 命令以显示所有已链接目录的列表

1valet links

unlink 命令可用于销毁站点的符号链接

1cd ~/Sites/laravel
2 
3valet unlink

使用 TLS 保护站点安全

默认情况下,Valet 通过 HTTP 服务站点。但是,如果您想使用 HTTP/2 通过加密 TLS 服务站点,您可以使用 secure 命令。例如,如果您的站点通过 Valet 在 laravel.test 域上服务,您应该运行以下命令来保护它

1valet secure laravel

要 “取消保护” 站点并恢复为通过纯 HTTP 服务其流量,请使用 unsecure 命令。与 secure 命令一样,此命令接受您希望取消保护的主机名

1valet unsecure laravel

服务默认站点

有时,您可能希望配置 Valet 在访问未知 test 域时服务 “默认” 站点,而不是 404。为了实现这一点,您可以将 default 选项添加到您的 ~/.config/valet/config.json 配置文件,其中包含应作为默认站点的站点的路径

1"default": "/Users/Sally/Sites/example-site",

每个站点的 PHP 版本

默认情况下,Valet 使用您的全局 PHP 安装来服务您的站点。但是,如果您需要在各种站点之间支持多个 PHP 版本,您可以使用 isolate 命令来指定特定站点应使用的 PHP 版本。isolate 命令配置 Valet 为位于您当前工作目录中的站点使用指定的 PHP 版本

1cd ~/Sites/example-site
2 
3valet isolate [email protected]

如果您的站点名称与包含它的目录名称不匹配,您可以使用 --site 选项指定站点名称

1valet isolate [email protected] --site="site-name"

为了方便起见,您可以使用 valet phpcomposerwhich-php 命令来代理对适当的 PHP CLI 或工具的调用,这取决于站点配置的 PHP 版本

1valet php
2valet composer
3valet which-php

您可以执行 isolated 命令以显示所有隔离站点及其 PHP 版本的列表

1valet isolated

要将站点恢复为 Valet 全局安装的 PHP 版本,您可以从站点的根目录调用 unisolate 命令

1valet unisolate

共享站点

Valet 包括一个与世界共享您的本地站点的命令,提供了一种在移动设备上测试您的站点或与团队成员和客户共享它的简单方法。

开箱即用,Valet 支持通过 ngrok 或 Expose 共享您的站点。在共享站点之前,您应该使用 share-tool 命令更新您的 Valet 配置,指定 ngrokexpose

1valet share-tool ngrok

如果您选择一个工具并且没有通过 Homebrew(对于 ngrok)或 Composer(对于 Expose)安装它,Valet 将自动提示您安装它。当然,这两个工具都要求您在开始共享站点之前验证您的 ngrok 或 Expose 帐户。

要共享站点,请在您的终端中导航到站点的目录并运行 Valet 的 share 命令。一个公开可访问的 URL 将被放入您的剪贴板,并准备好直接粘贴到您的浏览器中或与您的团队共享

1cd ~/Sites/laravel
2 
3valet share

要停止共享您的站点,您可以按 Control + C

如果您正在使用自定义 DNS 服务器(如 1.1.1.1),ngrok 共享可能无法正常工作。如果您的机器上是这种情况,请打开您的 Mac 系统设置,转到网络设置,打开高级设置,然后转到 DNS 选项卡,并将 127.0.0.1 添加为您的第一个 DNS 服务器。

通过 Ngrok 共享站点

使用 ngrok 共享您的站点需要您 创建一个 ngrok 帐户设置一个身份验证令牌。拥有身份验证令牌后,您可以使用该令牌更新您的 Valet 配置

1valet set-ngrok-token YOUR_TOKEN_HERE

您可以将其他 ngrok 参数传递给 share 命令,例如 valet share --region=eu。有关更多信息,请查阅 ngrok 文档

通过 Expose 共享站点

使用 Expose 共享您的站点需要您 创建一个 Expose 帐户通过您的身份验证令牌使用 Expose 进行身份验证

您可以查阅 Expose 文档,以获取有关它支持的其他命令行参数的信息。

在本地网络上共享站点

默认情况下,Valet 将传入流量限制为内部 127.0.0.1 接口,以便您的开发机器不会暴露于来自 Internet 的安全风险。

如果您希望允许本地网络上的其他设备通过您机器的 IP 地址(例如:192.168.1.10/application.test)访问您机器上的 Valet 站点,您将需要手动编辑该站点的相应 Nginx 配置文件,以删除对 listen 指令的限制。您应该删除端口 80 和 443 的 listen 指令上的 127.0.0.1: 前缀。

如果您尚未在项目上运行 valet secure,您可以通过编辑 /usr/local/etc/nginx/valet/valet.conf 文件来打开所有非 HTTPS 站点的网络访问。但是,如果您通过 HTTPS 服务项目站点(您已为站点运行 valet secure),那么您应该编辑 ~/.config/valet/Nginx/app-name.test 文件。

更新 Nginx 配置后,运行 valet restart 命令以应用配置更改。

站点特定的环境变量

某些使用其他框架的应用程序可能依赖于服务器环境变量,但没有提供在您的项目中配置这些变量的方法。Valet 允许您通过在项目的根目录中添加 .valet-env.php 文件来配置站点特定的环境变量。此文件应返回站点/环境变量对的数组,这些对将被添加到数组中指定的每个站点的全局 $_SERVER 数组中

1<?php
2 
3return [
4 // Set $_SERVER['key'] to "value" for the laravel.test site...
5 'laravel' => [
6 'key' => 'value',
7 ],
8 
9 // Set $_SERVER['key'] to "value" for all sites...
10 '*' => [
11 'key' => 'value',
12 ],
13];

代理服务

有时您可能希望将 Valet 域代理到您本地机器上的另一个服务。例如,您可能偶尔需要在运行 Valet 的同时在 Docker 中运行单独的站点;但是,Valet 和 Docker 不能同时绑定到端口 80。

为了解决这个问题,您可以使用 proxy 命令生成代理。例如,您可以将来自 http://elasticsearch.test 的所有流量代理到 http://127.0.0.1:9200

1# Proxy over HTTP...
2valet proxy elasticsearch http://127.0.0.1:9200
3 
4# Proxy over TLS + HTTP/2...
5valet proxy elasticsearch http://127.0.0.1:9200 --secure

您可以使用 unproxy 命令删除代理

1valet unproxy elasticsearch

您可以使用 proxies 命令列出所有已代理的站点配置

1valet proxies

自定义 Valet 驱动程序

您可以编写自己的 Valet “驱动程序” 来服务在 Valet 本身不支持的框架或 CMS 上运行的 PHP 应用程序。当您安装 Valet 时,将创建一个 ~/.config/valet/Drivers 目录,其中包含一个 SampleValetDriver.php 文件。此文件包含一个示例驱动程序实现,以演示如何编写自定义驱动程序。编写驱动程序仅需要您实现三个方法:servesisStaticFilefrontControllerPath

所有三种方法都接收 $sitePath$siteName$uri 值作为其参数。$sitePath 是机器上正在服务的站点的完全限定路径,例如 /Users/Lisa/Sites/my-project$siteName 是域的 “host” / “site name” 部分 (my-project)。$uri 是传入的请求 URI (/foo/bar)。

完成自定义 Valet 驱动程序后,使用 FrameworkValetDriver.php 命名约定将其放置在 ~/.config/valet/Drivers 目录中。例如,如果您正在为 WordPress 编写自定义 valet 驱动程序,则您的文件名应为 WordPressValetDriver.php

让我们看一下您的自定义 Valet 驱动程序应实现的每个方法的示例实现。

serves 方法

如果您的驱动程序应处理传入的请求,则 serves 方法应返回 true。否则,该方法应返回 false。因此,在此方法中,您应该尝试确定给定的 $sitePath 是否包含您尝试服务的类型的项目。

例如,假设我们正在编写 WordPressValetDriver。我们的 serves 方法可能如下所示

1/**
2 * Determine if the driver serves the request.
3 */
4public function serves(string $sitePath, string $siteName, string $uri): bool
5{
6 return is_dir($sitePath.'/wp-admin');
7}

isStaticFile 方法

isStaticFile 应确定传入的请求是否用于 “静态” 文件,例如图像或样式表。如果文件是静态的,则该方法应返回磁盘上静态文件的完全限定路径。如果传入的请求不是用于静态文件,则该方法应返回 false

1/**
2 * Determine if the incoming request is for a static file.
3 *
4 * @return string|false
5 */
6public function isStaticFile(string $sitePath, string $siteName, string $uri)
7{
8 if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
9 return $staticFilePath;
10 }
11 
12 return false;
13}

只有当 serves 方法为传入的请求返回 true 且请求 URI 不是 / 时,才会调用 isStaticFile 方法。

frontControllerPath 方法

frontControllerPath 方法应返回应用程序 “前端控制器” 的完全限定路径,通常是 “index.php” 文件或等效文件

1/**
2 * Get the fully resolved path to the application's front controller.
3 */
4public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
5{
6 return $sitePath.'/public/index.php';
7}

本地驱动程序

如果您想为单个应用程序定义自定义 Valet 驱动程序,请在应用程序的根目录中创建一个 LocalValetDriver.php 文件。您的自定义驱动程序可以扩展基本 ValetDriver 类或扩展现有的应用程序特定驱动程序,例如 LaravelValetDriver

1use Valet\Drivers\LaravelValetDriver;
2 
3class LocalValetDriver extends LaravelValetDriver
4{
5 /**
6 * Determine if the driver serves the request.
7 */
8 public function serves(string $sitePath, string $siteName, string $uri): bool
9 {
10 return true;
11 }
12 
13 /**
14 * Get the fully resolved path to the application's front controller.
15 */
16 public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
17 {
18 return $sitePath.'/public_html/index.php';
19 }
20}

其他 Valet 命令

命令 描述
valet list 显示所有 Valet 命令的列表。
valet diagnose 输出诊断信息以帮助调试 Valet。
valet directory-listing 确定目录列表行为。默认为 “off”,为目录呈现 404 页面。
valet forget 从 “parked” 目录运行此命令以将其从 parked 目录列表中删除。
valet log 查看 Valet 服务写入的日志列表。
valet paths 查看所有 “parked” 路径。
valet restart 重启 Valet 守护程序。
valet start 启动 Valet 守护程序。
valet stop 停止 Valet 守护程序。
valet trust 为 Brew 和 Valet 添加 sudoers 文件,以允许在不提示输入密码的情况下运行 Valet 命令。
valet uninstall 卸载 Valet:显示手动卸载的说明。传递 --force 选项以强制删除 Valet 的所有资源。

Valet 目录和文件

在对 Valet 环境问题进行故障排除时,您可能会发现以下目录和文件信息很有用

~/.config/valet

包含 Valet 的所有配置。您可能希望维护此目录的备份。

~/.config/valet/dnsmasq.d/

此目录包含 DNSMasq 的配置。

~/.config/valet/Drivers/

此目录包含 Valet 的驱动程序。驱动程序决定了如何服务特定的框架/CMS。

~/.config/valet/Nginx/

此目录包含 Valet 的所有 Nginx 站点配置。在运行 installsecure 命令时,会重建这些文件。

~/.config/valet/Sites/

此目录包含您的 链接项目 的所有符号链接。

~/.config/valet/config.json

此文件是 Valet 的主配置文件。

~/.config/valet/valet.sock

此文件是 Valet 的 Nginx 安装使用的 PHP-FPM 套接字。这仅在 PHP 正常运行时存在。

~/.config/valet/Log/fpm-php.www.log

此文件是 PHP 错误的用户日志。

~/.config/valet/Log/nginx-error.log

此文件是 Nginx 错误的用户日志。

/usr/local/var/log/php-fpm.log

此文件是 PHP-FPM 错误的系统日志。

/usr/local/var/log/nginx

此目录包含 Nginx 访问和错误日志。

/usr/local/etc/php/X.X/conf.d

此目录包含各种 PHP 配置设置的 *.ini 文件。

/usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf

此文件是 PHP-FPM 池配置文件。

~/.composer/vendor/laravel/valet/cli/stubs/secure.valet.conf

此文件是用于为您的站点构建 SSL 证书的默认 Nginx 配置。

磁盘访问

自 macOS 10.14 以来,默认情况下,对某些文件和目录的访问受到限制。这些限制包括桌面、文稿和下载目录。此外,网络卷和可移动卷访问受到限制。因此,Valet 建议您的站点文件夹位于这些受保护位置之外。

但是,如果您希望从这些位置之一服务站点,您将需要为 Nginx 提供 “完全磁盘访问权限”。否则,您可能会遇到服务器错误或来自 Nginx 的其他不可预测的行为,尤其是在服务静态资源时。通常,macOS 会自动提示您授予 Nginx 对这些位置的完全访问权限。或者,您可以手动通过 系统偏好设置 > 安全性与隐私 > 隐私 并选择 完全磁盘访问权限 来完成此操作。接下来,在主窗口窗格中启用任何 nginx 条目。

Laravel 是最有效的方式来
构建、部署和监控软件。