介绍

[!NOTE]
正在寻找在 macOS 或 Windows 上更轻松地开发 Laravel 应用程序的方法？查看 Laravel Herd (opens in a new tab)。Herd 包含了开始 Laravel 开发所需的一切，包括 Valet、PHP 和 Composer。

Laravel Valet (opens in a new tab) 是为 macOS 极简主义者提供的开发环境。Laravel Valet 会在您的 Mac 启动时，在后台始终运行 Nginx (opens in a new tab)。然后，使用 DnsMasq (opens in a new tab)，Valet 将 *.test 域上的所有请求代理到安装在本地机器上的站点。

换句话说，Valet 是一个快速的 Laravel 开发环境，仅使用大约 7MB 的内存。Valet 并不是 Sail 或 Homestead 的完全替代品，但如果您想要灵活的基础设置、追求极快的速度，或者在内存有限的机器上工作，它是一个很好的选择。

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

但是，您可以使用自己的自定义驱动程序来扩展 Valet。

安装

[!WARNING]
Valet 需要 macOS 和 Homebrew (opens in a new tab)。在安装之前，您应该确保没有其他程序（如 Apache 或 Nginx）绑定到本地机器的 80 端口。

首先，您需要使用 update 命令确保 Homebrew 是最新的：

brew update

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

brew install php

安装 PHP 后，您可以准备安装 Composer 包管理器 (opens in a new tab)。此外，您应该确保系统的“PATH”中包含 $HOME/.composer/vendor/bin 目录。安装 Composer 后，您可以将 Laravel Valet 作为全局 Composer 包进行安装：

composer global require laravel/valet

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

valet install

一旦安装了 Valet，您可以在终端中使用 ping foobar.test 等命令来ping 任何 *.test 域名。如果 Valet 安装正确，您应该看到该域名在 127.0.0.1 上响应。

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

PHP 版本

[!NOTE]
您可以通过 isolate 命令指示 Valet 使用每个站点的 PHP 版本，而不是修改全局 PHP 版本。

Valet 允许您使用 valet use php@version 命令切换 PHP 版本。如果指定的 PHP 版本尚未通过 Homebrew 安装，Valet 会通过 Homebrew 进行安装：

valet use php@8.2
 
valet use php

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

php=php@8.2

创建此文件后，您只需执行 valet use 命令，该命令将通过读取文件来确定站点首选的 PHP 版本。

[!WARNING]
即使您安装了多个 PHP 版本，Valet 一次也只服务一个 PHP 版本。

数据库

如果您的应用程序需要数据库，请查看 DBngin (opens in a new tab)，它提供了一个免费的一体化数据库管理工具，包括 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 安装：

服务站点

一旦安装了 Valet，您就可以开始为您的 Laravel 应用程序提供服务。Valet 提供了两个命令来帮助您为应用程序提供服务：park 和 link。

“Park”命令

“Park”命令会在您的机器上注册一个包含您的应用程序的目录。一旦该目录被 Valet “停放”，该目录内的所有目录都可以在您的网络浏览器中通过 http://<目录名称>.test 访问：

cd ~/Sites
 
valet park

就是这么简单。现在，您在“停放”目录中创建的任何应用程序都将自动按照 http://<目录名称>.test 的约定进行服务。因此，如果您的停放目录包含一个名为“laravel”的目录，该目录中的应用程序将可以在 http://laravel.test 访问。此外，Valet 自动允许您使用通配符子域名（http://foo.laravel.test）访问该站点。

link 命令

link 命令也可用于为您的 Laravel 应用提供服务。如果您希望在一个目录中为单个站点提供服务，而不是整个目录，那么此命令非常有用：

cd ~/Sites/laravel
 
valet link

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

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

cd ~/Sites/laravel
 
valet link application

当然，您也可以使用 link 命令在子域上为应用程序提供服务：

valet link api.application

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

valet links

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

cd ~/Sites/laravel
 
valet unlink

使用 TLS 保护站点

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

valet secure laravel

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

valet unsecure laravel

提供默认站点

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

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

每个站点的 PHP 版本

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

cd ~/Sites/example-site
 
valet isolate php@8.0

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

valet isolate php@8.0 --site="site-name"

为了方便起见，您可以使用 valet php、composer 和 which-php 命令根据站点配置的 PHP 版本代理调用相应的 PHP CLI 或工具：

valet php
valet composer
valet which-php

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

valet isolated

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

valet unisolate

共享站点

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

默认情况下，Valet 支持通过 ngrok 或 Expose 共享您的站点。在共享站点之前，您应该使用 share-tool 命令更新您的 Valet 配置，指定 ngrok 或 expose：

valet share-tool ngrok

如果您选择了一个工具，但未通过 Homebrew（对于 ngrok）或 Composer（对于 Expose）安装它，Valet 将自动提示您安装它。当然，这两个工具都要求您在开始共享站点之前对您的 ngrok 或 Expose 账户进行身份验证。

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

cd ~/Sites/laravel
 
valet share

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

[!WARNING]
如果您使用的是自定义 DNS 服务器（如 1.1.1.1），ngrok 共享可能无法正常工作。如果您的机器出现这种情况，请打开您的 Mac 系统设置，转到网络设置，打开高级设置，然后转到 DNS 选项卡，并将 127.0.0.1 作为您的第一个 DNS 服务器。

通过 ngrok 共享站点

使用 ngrok 共享您的站点需要您 创建一个 ngrok 账户 (opens in a new tab) 并 设置一个身份验证令牌 (opens in a new tab)。一旦您有了身份验证令牌，您可以使用该令牌更新您的 Valet 配置：

valet set-ngrok-token YOUR_TOKEN_HERE

[!NOTE]
您可以向 share 命令传递其他 ngrok 参数，例如 valet share --region=eu。有关更多信息，请参考 ngrok 文档 (opens in a new tab)。

通过 Expose 共享站点

使用 Expose 共享您的站点需要您 创建一个 Expose 账户 (opens in a new tab) 并 通过您的身份验证令牌与 Expose 进行身份验证 (opens in a new tab)。

您可以参考 Expose 文档 (opens in a new tab) 以获取有关其支持的其他命令行参数的信息。

在您的本地网络上共享站点

默认情况下，Valet 将传入流量限制在内部的 127.0.0.1 接口，以避免您的开发机器面临来自互联网的安全风险。

如果您希望允许您本地网络上的其他设备通过您机器的 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 数组中：

<?php

return [
    // 为 laravel.test 站点将 $_SERVER['key'] 设置为 "value"...
    'laravel' => [
        'key' => 'value',
    ],

    // 为所有站点将 $_SERVER['key'] 设置为 "value"...
    '*' => [
        'key' => 'value',
    ],
];

代理服务

有时您可能希望将 Valet 域代理到您本地机器上的其他服务。例如，您可能偶尔需要在运行 Docker 中的单独站点的同时运行 Valet；然而，Valet 和 Docker 不能同时绑定到端口 80。

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

# 通过 HTTP 进行代理...
valet proxy elasticsearch http://127.0.0.1:9200

通过 TLS + HTTP/2 进行代理...

使用 valet proxy elasticsearch http://127.0.0.1:9200 --secure 命令为 elasticsearch 进行代理。

您可以使用 `unproxy` 命令来移除一个代理：

```shell
valet unproxy elasticsearch

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

valet proxies

自定义 Valet 驱动

您可以编写自己的 Valet“驱动”，以服务于 Valet 本身不原生支持的框架或 CMS 上运行的 PHP 应用程序。当您安装 Valet 时，会创建一个 ~/.config/valet/Drivers 目录，其中包含一个 SampleValetDriver.php 文件。该文件包含一个示例驱动程序的实现，以展示如何编写自定义驱动程序。编写驱动程序只需要您实现三个方法：serves、isStaticFile 和 frontControllerPath。

这三个方法都会接收 $sitePath、$siteName 和 $uri 值作为它们的参数。$sitePath 是您机器上正在服务的站点的完全限定路径，例如 /Users/Lisa/Sites/my-project。$siteName 是域的“主机”/“站点名称”部分（my-project）。$uri 是传入的请求 URI（/foo/bar）。

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

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

serves 方法

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

例如，假设我们正在编写一个 WordPressValetDriver。我们的 serves 方法可能看起来像这样：

/**
 * 确定驱动程序是否服务该请求。
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

isStaticFile 方法

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

/**
 * 确定传入的请求是否是针对静态文件的。
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

[!警告]
只有当 serves 方法对传入的请求返回 true 且请求 URI 不是 / 时，才会调用 isStaticFile 方法。

frontControllerPath 方法

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

/**
 * 获取应用程序前端控制器的完全解析路径。
 */
public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
{
    return $sitePath.'/public/index.php';
}

本地驱动

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

use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    /**
     * 确定驱动程序是否服务该请求。
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

    /**
     * 获取应用程序前端控制器的完全解析路径。
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): string
    {
        return $sitePath.'/public_html/index.php';
    }
}

其他 Valet 命令

Valet 目录和文件

在对您的 Valet 环境进行问题排查时，您可能会发现以下目录和文件信息有所帮助：

~/.config/valet

包含 Valet 的所有配置。您可能希望对此目录进行备份。

~/.config/valet/dnsmasq.d/

此目录包含 DNSMasq 的配置。

~/.config/valet/Drivers/

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

~/.config/valet/Nginx/

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

~/.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 起，默认情况下对某些文件和目录的访问受到限制 (opens in a new tab)。这些限制包括桌面、文档和下载目录。此外，网络卷和可移动卷的访问也受到限制。因此，Valet 建议您的站点文件夹位于这些受保护位置之外。

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