Valet

📝 此頁面為 Laravel 官方文檔的繁體中文翻譯。查看原始英文版本

Laravel Valet

簡介

[!NOTE] 正在尋找更簡單的方式在 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 是最新的：

brew update

接下來，您應該使用 Homebrew 來安裝 PHP：

brew install php

安裝 PHP 之後，您就可以安裝 Composer 套件管理器了。此外，您應該確保 $HOME/.composer/vendor/bin 目錄在您系統的「PATH」中。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] 與其修改全域 PHP 版本，您可以指示 Valet 透過 isolate 指令使用每個網站的 PHP 版本。

Valet 允許您使用 valet use php@version 指令切換 PHP 版本。如果指定的 PHP 版本尚未安裝，Valet 將透過 Homebrew 安裝它：

valet use php@8.2

您也可以使用以下指令切換回 PHP 7：

valet use php

您可以在專案根目錄中建立 .valetrc 檔案。.valetrc 檔案應包含該網站應使用的 PHP 版本：

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，請按照以下步驟正確升級您的 Valet 安裝：

  • 如果您已新增 .valetphprc 檔案來自訂網站的 PHP 版本，請將每個 .valetphprc 檔案重新命名為 .valetrc。然後，在 .valetrc 檔案的現有內容前加上 php=。
  • 更新任何自訂驅動程式以匹配新驅動程式系統的命名空間、擴充功能、型別提示和傳回型別提示。您可以參閱 Valet 的 SampleValetDriver 作為範例。
  • 如果您使用 PHP 7.1 - 7.4 來提供網站服務，請確保您仍然使用 Homebrew 安裝 8.0 或更高版本的 PHP，因為 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 指令。例如，如果您的網站在 laravel.test 網域上由 Valet 提供服務，您應該執行以下指令來保護它：

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

valet share-tool ngrok

如果您選擇了一個工具但尚未透過 Homebrew（用於 ngrok 和 cloudflared）或 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 帳戶並設定認證令牌。一旦您有了認證令牌，您可以使用該令牌更新您的 Valet 設定：

valet set-ngrok-token YOUR_TOKEN_HERE

[!NOTE] 您可以將額外的 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

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：

# 透過 HTTP 代理...
valet proxy elasticsearch http://127.0.0.1:9200

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

您可以使用 unproxy 指令移除代理：

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;
}

[!WARNING] 只有當 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 list 顯示所有 Valet 指令的列表。
valet diagnose 輸出診斷資訊以協助 Valet 除錯。
valet directory-listing 決定目錄列表行為。預設為「off」，即為目錄呈現 404 頁面。
valet forget 從「停放」目錄中執行此指令以將其從停放目錄列表中移除。
valet log 查看由 Valet 服務寫入的日誌列表。
valet paths 查看所有「停放」路徑。
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 條目。