Laravel 中文文档

主题

全部文档

Laravel Valet ​

简介 ​

INFO

想在 macOS 或 Windows 上更轻松地开发 Laravel 应用？试试 Laravel Herd。Herd 包含开始 Laravel 开发所需的一切，包括 Valet、PHP 和 Composer。

Laravel Valet 是面向 macOS 极简主义者的开发环境。Laravel Valet 会配置你的 Mac，在开机时始终在后台运行 Nginx。然后，通过 DnsMasq，Valet 会将 *.test 域名上的所有请求代理到本机安装的站点。

换句话说，Valet 是极速的 Laravel 开发环境，大约只占用 7 MB 内存。Valet 并非 Sail 或 Homestead 的完整替代品，但若你需要灵活的基础能力、追求极致速度，或在内存有限的机器上工作，它是很好的选择。

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

不过，你也可以用自己的自定义驱动扩展 Valet。

安装 ​

WARNING

Valet 需要 macOS 和 Homebrew。安装前，请确保没有其他程序（如 Apache 或 Nginx）占用本机的 80 端口。

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

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 域名。若安装正确，应看到该域名响应 127.0.0.1。

每次开机时，Valet 会自动启动所需服务。

PHP 版本 ​

INFO

不必修改全局 PHP 版本，你可以通过 isolate 命令让 Valet 为每个站点使用不同的 PHP 版本。

Valet 允许你使用 valet use php@version 命令切换 PHP 版本。若指定版本尚未安装，Valet 会通过 Homebrew 安装：

shell
valet use php@8.2

valet use php

你也可以在项目根目录创建 .valetrc 文件。该文件应包含站点应使用的 PHP 版本：

shell
php=php@8.2

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

WARNING

即使安装了多个 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，请按以下步骤正确升级：

  • 若曾添加 `.valetphprc` 文件自定义站点 PHP 版本，请将每个 `.valetphprc` 重命名为 `.valetrc`，然后在 `.valetrc` 现有内容前加上 `php=`。
  • 更新所有自定义驱动，使其符合新驱动系统的命名空间、扩展、类型提示与返回类型提示。可参考 Valet 的 [SampleValetDriver](https://github.com/laravel/valet/blob/d7787c025e60abc24a5195dc7d4c5c6f2d984339/cli/stubs/SampleValetDriver.php) 作为示例。
  • 若使用 PHP 7.1–7.4 服务站点，请仍通过 Homebrew 安装 8.0 或更高版本的 PHP，因为 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 选项，其值为应作为默认站点的路径：

"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 或 cloudflared：

shell
valet share-tool ngrok

若选择的工具尚未通过 Homebrew（ngrok 和 cloudflared）或 Composer（Expose）安装，Valet 会自动提示你安装。当然，这些工具都需要你先验证 ngrok 或 Expose 账户才能开始共享站点。

要共享站点，请在终端进入站点目录并运行 Valet 的 share 命令。公开可访问的 URL 会放入剪贴板，可直接粘贴到浏览器或与团队共享：

shell
cd ~/Sites/laravel

valet share

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

WARNING

若使用自定义 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

INFO

你可以将额外的 ngrok 参数传给 share 命令，例如 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 的 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
<?php

return [
    // Set $_SERVER['key'] to "value" for the laravel.test site...
    'laravel' => [
        'key' => 'value',
    ],

    // Set $_SERVER['key'] to "value" for all sites...
    '*' => [
        'key' => 'value',
    ],
];

代理服务 ​

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

为此，可使用 proxy 命令生成代理。例如，可将 http://elasticsearch.test 的所有流量代理到 http://127.0.0.1:9200：

shell
# Proxy over HTTP...
valet proxy elasticsearch http://127.0.0.1:9200

# Proxy over 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 是域名的「host」/「站点名」部分（my-project）。$uri 是传入请求的 URI（/foo/bar）。

完成自定义 Valet 驱动后，请按 FrameworkValetDriver.php 命名约定将其放在 ~/.config/valet/Drivers 目录。例如，若为 WordPress 编写自定义驱动，文件名应为 WordPressValetDriver.php。

下面来看自定义 Valet 驱动应实现的每个方法的示例。

serves 方法 ​

若驱动应处理传入请求，serves 方法应返回 true；否则返回 false。因此，在该方法中应判断给定的 $sitePath 是否包含你要服务的项目类型。

例如，假设我们在编写 WordPressValetDriver。serves 方法可能如下所示：

php
/**
 * Determine if the driver serves the request.
 */
public function serves(string $sitePath, string $siteName, string $uri): bool
{
    return is_dir($sitePath.'/wp-admin');
}

isStaticFile 方法 ​

isStaticFile 应判断传入请求是否针对「静态」文件（如图片或样式表）。若是静态文件，方法应返回磁盘上该静态文件的完整路径；若不是，应返回 false：

php
/**
 * Determine if the incoming request is for a static file.
 *
 * @return string|false
 */
public function isStaticFile(string $sitePath, string $siteName, string $uri)
{
    if (file_exists($staticFilePath = $sitePath.'/public/'.$uri)) {
        return $staticFilePath;
    }

    return false;
}

WARNING

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

frontControllerPath 方法 ​

frontControllerPath 方法应返回应用「前端控制器」的完整路径，通常是 index.php 或等效文件：

php
/**
 * Get the fully resolved path to the application's front controller.
 */
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
{
    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true;
    }

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

其他 Valet 命令 ​

CommandDescription
valet list显示所有 Valet 命令的列表。
valet diagnose输出诊断信息以协助调试 Valet。
valet directory-listing决定目录列表行为。默认为「off」，会对目录渲染 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 socket。仅在 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 条目。