Laravel 10.x 中文文档

简体中文

English

简体中文

English

主题

Laravel Valet ​

介绍 ​

lightbulb

想在 macOS 上更轻松地开发 Laravel 应用程序？请查看 Laravel Herd。Herd 包含开始 Laravel 开发所需的一切，包括 Valet、PHP 和 Composer。

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

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

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

然而，您可以通过自己的自定义驱动扩展 Valet。

安装 ​

exclamation

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

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

shell
brew update

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

shell
brew install php

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

shell
composer global require laravel/valet

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

shell
valet install

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

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

PHP 版本 ​

lightbulb

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

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

shell
valet use php@8.1

valet use php

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

shell
php=php@8.1

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

exclamation

Valet 仅同时服务一个 PHP 版本，即使您安装了多个 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 提供了两个命令来帮助您服务您的应用程序：park 和 link。

"Park" 命令 ​

"Park" 命令注册您机器上的一个目录，其中包含您的应用程序。目录一旦被 Valet "park" 后，该目录中的所有目录都可以在您的浏览器中通过 http://<directory-name>.test 访问：

shell
cd ~/Sites

valet park

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

"Link" 命令也可以用来服务您的 Laravel 应用程序。如果您只想在一个目录中服务一个站点而不是整个目录，此命令非常有用：

shell
cd ~/Sites/laravel

valet link

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

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

shell
cd ~/Sites/laravel

valet link application

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

shell
valet link api.application

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

shell
valet links

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

shell
cd ~/Sites/laravel

valet unlink

使用 TLS 保护站点 ​

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

shell
valet secure laravel

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

shell
valet unsecure laravel

服务默认站点 ​

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

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

每站点 PHP 版本 ​

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

shell
cd ~/Sites/example-site

valet isolate php@8.0

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

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

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

shell
valet php
valet composer
valet which-php

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

shell
valet isolated

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

shell
valet unisolate

共享站点 ​

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

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

shell
valet share-tool ngrok

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

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

shell
cd ~/Sites/laravel

valet share

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

exclamation

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

通过 Ngrok 共享站点 ​

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

shell
valet set-ngrok-token YOUR_TOKEN_HERE
lightbulb

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

通过 Expose 共享站点 ​

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

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

在本地网络上共享站点 ​

Valet 默认将传入流量限制在内部 127.0.0.1 接口上，以便您的开发机器不暴露于来自互联网的安全风险。

如果您希望允许本地网络上的其他设备通过您的机器的 IP 地址（例如：192.168.1.10/application.test）访问您机器上的 Valet 站点，您需要手动编辑该站点的适当 Nginx 配置文件以删除 listen 指令上的限制。您应该删除端口 80 和 443 的 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
<?php

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

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

代理服务 ​

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

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

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

# 通过 TLS + HTTP/2 代理...
valet proxy elasticsearch http://127.0.0.1:9200 --secure

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

shell
valet unproxy elasticsearch

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

shell
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 驱动后，将其放置在 ~/.config/valet/Drivers 目录中，使用 FrameworkValetDriver.php 命名约定。例如，如果您正在为 WordPress 编写自定义 Valet 驱动，您的文件名应为 WordPressValetDriver.php。

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

"serves" 方法 ​

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

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

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

"isStaticFile" 方法 ​

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

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

    return false;
}
exclamation

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

"frontControllerPath" 方法 ​

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

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

本地驱动 ​

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

php
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 list显示所有 Valet 命令的列表。
valet diagnose输出诊断信息以帮助调试 Valet。
valet directory-listing确定目录列表行为。默认是“关闭”，这会为目录呈现 404 页面。
valet forget从“park”目录中运行此命令以将其从“park”目录列表中删除。
valet log查看 Valet 服务写入的日志列表。
valet paths查看所有“park”路径。
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 站点配置。这些文件在运行 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 起，默认情况下对某些文件和目录的访问受到限制。这些限制包括桌面、文档和下载目录。此外，网络卷和可移动卷的访问受到限制。因此，Valet 建议您的站点文件夹位于这些受保护位置之外。

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

版权所有 © 2024-2025 laravel.wiki