建立於 2026-11-11 更新於 2026-11-15
# laravel# lerd# omarchy# zed

Lerd 安裝筆記 (Omarchy)

Lerd 是一款基於 rootless Podman 的本地 PHP 開發環境,專為 Linux、macOS 與 Windows 設計。免去手動配置 Nginx、PHP-FPM、SSL 憑證與 DNS 的繁瑣步驟,自動支援 *.test 網域與 HTTPS。

本篇筆記以 Omarchy (Arch + Hyprland) 環境為基準撰寫。


1. 安裝 Lerd

在 Omarchy 下使用官方 Shell Script 進行安裝:

curl -fsSL https://lerd.sh/install.sh | bash

Lerd 建議 Runtime 使用 crun,可以透過 pacman 安裝:

sudo pacman -S crun

如果想要透過 lerd secure 幫網站啟用 TLS,Lerd 需要 nss 套件中的 certutil 工具,用於在瀏覽器中安裝 TLS 憑證:

sudo pacman -S nss

上述步驟完成後就可以使用 lerd doctor 檢查 Lerd 安裝是否成功:

lerd doctor

安裝過程重點

  • Sudo 權限:僅在安裝初期要求一次 sudo(用於綁定 80/443 port 的 sysctl、設定 systemd linger 以及設定 systemd-resolved 的 .test 網域名稱解析),後續日常使用完全不需 sudo。
  • 環境設定:安裝程式會將二進位檔安裝至 ~/.local/bin/lerd 並自動加入 PATH。
  • 安裝完成後,請重新載入 Shell 或開啟新終端機使 PATH 生效。

2. Omarchy 注意事項

Omarchy 預裝了 Arch Linux 與 Hyprland 桌面環境,具備較新的 Podman(>= 4.5),非常適合搭配 Lerd:

  • 系統托盤與 Glance 外掛:在 Omarchy 上安裝時,Lerd 預設會關閉系統匣圖示(lerd tray off),並自動整合 Omarchy 頂部狀態列的 Glance 外掛(顯示站點、服務、容器記憶體等資訊)。
  • 服務管理:所有容器皆作為 Podman Quadlet 運行,背景 Worker 則透過 systemd user 服務管理,設定檔集中在 ~/.config/lerd 與 ~/.local/share/lerd,不污染系統全域目錄。

3. 專案綁定與啟動

進入 Laravel 或 PHP 專案目錄後執行:

cd ~/code/my-project
lerd link

綁定後即可直接透過 https://my-project.test 造訪專案。


4. 前端 Package Manager 注意事項

Lerd 預設會根據專案前端檔案(如 package.json 中的 packageManager 或 lockfile)偵測包管理器:

  • npm:Lerd 內建提供了 host 端的執行封裝(路徑為 ~/.local/share/lerd/bin/npm)。
  • pnpm:目前 Lerd 預設尚未原生內建 pnpm 的 shim 封裝,官方預期會在未來版本完善支援。目前若在 host 執行建議直接透過系統或 Corepack 安裝的 pnpm。

5. Pest Browser Testing (Playwright) 設定

Pest v4 後加入的瀏覽器測試(pestphp/pest-plugin-browser)使用 Playwright 本地驅動 Chromium。在 Lerd 中,測試程序跑在 PHP-FPM 容器內,因此需要特別配置:

安裝步驟

# 1. 安裝 Pest Browser Plugin 與 Playwright
lerd composer require --dev pestphp/pest-plugin-browser
lerd npm install playwright

# 2. 安裝 Lerd 瀏覽器支援環境
lerd pest:browser install

lerd pest:browser install 會自動將 Alpine 原生 Chromium 及 Xvfb 烘焙入 FPM 容器鏡像中,並將 Lerd 本地根憑證匯入 Chromium。

相關指令

# 診斷瀏覽器測試環境
lerd pest:browser doctor

# 執行測試
lerd test
lerd test --parallel

# 移除瀏覽器環境
lerd pest:browser remove

6. 疑難雜症專區 (Troubleshooting)

Q1: Pest Browser 測試截圖上的中文字全部變成空白?

  • 現象:測試失敗產生的截圖 PNG 中,畫面元件正常,但所有中文文字皆呈透明或空白,只有英數字與圖示可見。

  • 原因:Lerd 的 PHP 容器鏡像(Alpine Linux)預設僅裝有英文字型(Open Sans),沒有 CJK 中文字型,導致容器內的 Chromium 在無頭模式下無法繪製中文字形(但 DOM 中的字串依然存在,因此純文字比對仍可能過關)。

  • 解法:在 Lerd 容器中加入 Alpine 的 Noto CJK 字型套件:

    lerd php:pkg add font-noto-cjk
    

Q2: Pest Browser 測試在同一個測試內有多個 visit() 導致斷言失敗?

  • 現象:在同一個 test(...) 內先後 visit('/page-a') 與 visit('/page-b'),後續斷言找不到元素,檢查截圖發現畫面仍停留在前一個頁面。
  • 原因:Pest Browser Plugin 在同一測試內重複呼叫 visit() 時,不會重新乾淨初始化 Playwright Context 與 Laravel 測試 Session / 登入態,導致後續頁面狀態錯亂。
  • 解法:
    1. 將不同頁面的測試拆分成獨立的測試案例,每個案例只包含單一 visit()。
    2. 若要測試同一頁面流程內的換頁導覽,應使用 ->click(...) 點擊畫面上的連結或按鈕進行跳轉,而非多次呼叫 visit()。

Q3: Zed 使用 Laravel 官方擴充套件出現 Inertia view [...] not found. 或 LSP 找不到 PHP?

  • 現象:在 Zed 安裝 Laravel 官方擴充套件(Laravel (Official) / laravel/lsp)後,對存在的 Inertia 頁面仍報錯 Inertia view [...] not found.,或自動補全與跳轉失效;透過 dev: open language server logs → laravel 可看到 PHP runner error(如 /usr/local/bin/php: No such file or directory,exitCode: 127)。
  • 原因:laravel/lsp 的 phpEnvironment: "auto" 預設只會偵測 Herd、Valet、Sail、Lando、DDEV 與系統預設 PHP,並不認識 Lerd;且從桌面啟動的 Zed 常讀不到 Shell $PATH 裡的 Lerd shim,導致 LSP 退回呼叫 /usr/local/bin/php 而失敗,進而無法執行 Laravel 腳本讀取 config/inertia.php 等設定。
  • 解法:在 Zed 設定檔透過 lsp.laravel.initialization_options.phpCommand 明確指定 PHP 執行指令:
    1. 全域設定(推薦,所有 Lerd 專案共用):先在終端機執行 which php 確認 Lerd shim 路徑(通常為 ~/.local/share/lerd/bin/php),再寫入 ~/.config/zed/settings.json:

      {
        "lsp": {
          "laravel": {
            "initialization_options": {
              "phpCommand": ["/home/allen/.local/share/lerd/bin/php"]
            }
          }
        }
      }
      
    2. 專案層級直接指定 Podman 容器(備用):若 shim 無法在非互動式 LSP 下執行,可在專案 .zed/settings.json 直接呼叫對應版本的容器,並務必加上 -w 指定專案根目錄:

      {
        "lsp": {
          "laravel": {
            "initialization_options": {
              "phpCommand": [
                "podman",
                "exec",
                "-i",
                "-w",
                "/path/to/your/project",
                "lerd-php85-fpm",
                "php"
              ]
            }
          }
        }
      }
      
    3. 存檔後按 Ctrl+Shift+P 執行 zed: restart language server 重新啟動 Laravel LSP 即可。

參考資料