Laravel LSP — 以 Language Server Protocol 擴充 IDE 功能

本文為 v0.0.27，2026 年 7 月時的資訊。已登錄於 Packagist，可用 composer global require laravel/lsp 安裝。

什麼是 Laravel LSP

Laravel LSP（Language Server Protocol）是為編輯器提供 Laravel 框架感知 IDE 功能的官方工具。Language Server Protocol 是 LSP 用戶端（編輯器）與 LSP 伺服器（Laravel LSP）間通訊的標準協定，可讓多個編輯器獲得統一的開發體驗。 Laravel LSP 提供的功能：

補完 — 路由、view、設定 key、翻譯 key、Livewire 元件等的自動補完
hover 資訊 — 游標懸停時顯示說明、文件與情境資訊
診斷 — 即時偵測程式碼中的問題
文件連結 — 檔案與資源之間的連結功能
快速修正 — 對常見問題自動提出修正
跳至定義 — 跳至符號定義位置

為何需要

編輯器標準的 PHP 補完無法理解 Laravel 框架的抽象層。例如：

在 Route::get() 的第 1 個引數輸入 URI pattern 沒有補完
輸入 view('users.index') 的 view 名稱時，實際 view 檔名不會被補完
設定檔的 key（config('app.name')）或翻譯 key（trans('messages.welcome')）不在補完對象內
編輯器標準也不支援 Blade 模板內的補完與驗證

Laravel LSP 理解這些「框架特有的情境」，並提供精確的補完與診斷。

安裝

全域安裝

使用 Composer 全域安裝：

composer global require laravel/lsp

確認 Composer 的 global bin 目錄已加入 PATH，即可用以下指令啟動：

laravel-lsp

由原始碼安裝

想用開發版可 clone 儲存庫執行：

gh repo clone laravel/lsp
cd lsp
composer install
php server

設定 shell alias 讓 laravel-lsp 指令可用：

# Zsh
echo 'alias laravel-lsp="php /path/to/lsp/server"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'alias laravel-lsp="php /path/to/lsp/server"' >> ~/.bashrc
source ~/.bashrc

各編輯器設定指南

Laravel LSP 使用標準 LSP 協定，因此支援 LSP 的所有編輯器都可運作。以下介紹主要編輯器的設定方式。

Sublime Text

安裝並設定官方 Laravel Sublime Text extension。

Zed

安裝並設定官方 Laravel Zed extension。

VS Code

安裝並設定官方 Laravel VS Code extension。

Cursor

Cursor 支援 VS Code 擴充功能，因此可直接使用上述 Laravel VS Code extension。

Neovim

於 Neovim 0.11 以上，可直接加入自訂 LSP 設定：

vim.lsp.config("laravel_lsp", {
    cmd = { "laravel-lsp" },
    filetypes = { "php", "blade" },
    root_markers = { "artisan", "composer.json", ".git" },
})

vim.lsp.enable("laravel_lsp")

若使用 nvim-lspconfig，可如下註冊：

local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")

if not configs.laravel_lsp then
    configs.laravel_lsp = {
        default_config = {
            cmd = { "laravel-lsp" },
            filetypes = { "php", "blade" },
            root_dir = lspconfig.util.root_pattern("artisan", "composer.json", ".git"),
        },
    }
end

lspconfig.laravel_lsp.setup({})

OpenCode

於 opencode.json 啟用 LSP 支援，並將 Laravel LSP 設為自訂伺服器：

{
    "$schema": "https://opencode.ai/config.json",
    "lsp": {
        "laravel-lsp": {
            "command": ["laravel-lsp"],
            "extensions": [".php", ".blade.php"]
        }
    }
}

GitHub Copilot CLI 的設定

若使用 GitHub Copilot CLI，可於 ~/.copilot/lsp-config.json 進行全域設定，不需另外的編輯器設定：

{
  "lspServers": {
    "laravel-lsp": {
      "command": "laravel-lsp",
      "fileExtensions": {
        ".php": "php",
        ".blade.php": "blade"
      }
    }
  }
}

Copilot CLI 的 LSP 伺服器設定也支援 initializationOptions，因此可完整使用後述的細部設定。

設定選項

LSP 用戶端可透過 initializationOptions 將細部設定傳給 Laravel LSP。

PHP 環境偵測

phpEnvironment 選項控制建立專案資料索引時使用的 PHP 指令。預設 auto 為自動偵測：

值	PHP 指令行為
`auto`	依 Herd → Valet → Sail → Lando → DDEV → 本機 PHP 順序偵測
`herd`	使用 `herd which-php`
`valet`	使用 `valet which-php`
`sail`	於 Sail 執行中時使用 `./vendor/bin/sail php`
`lando`	使用 `lando php`
`ddev`	使用 `ddev php`
`local`	直接使用本機 PHP 執行檔

若偵測失敗或傳入無效值，會回退到 php。

基本設定範例

{
    "phpEnvironment": "auto",
    "phpCommand": ["php"],
    "definitionProvider": false
}

Pest Helper Docblock

於 v0.0.27 新增的選項。當 Pest 測試或 Composer autoload 檔變更時，會自動產生與更新 Pest helper 的 docblock：

選項	型別	預設值	說明
`pestGenerateDocBlocks`	`boolean`	`true`	是否產生並持續更新 Pest helper 的 docblock
`pestHelperFilePath`	`string`	`"storage/framework/testing/_pest.php"`	Pest helper 輸出路徑（相對專案根目錄）

{
    "pestGenerateDocBlocks": true,
    "pestHelperFilePath": "storage/framework/testing/_pest.php"
}

各功能設定

各功能可個別啟停。後綴有 Completion、Diagnostics、Hover、Link 等：

{
    "routeCompletion": true,
    "routeDiagnostics": true,
    "viewDiagnostics": false,
    "translationHover": true,
    "configLink": true,
    "envCompletion": true,
    "bladeComponentLink": true
}

功能一覽

功能領域	補完	Hover	診斷	連結	快速修正
路由	✓	✓	✓	✓	-
View 與 Blade	✓	✓	✓	✓	✓
翻譯	✓	✓	-	-	-
設定	✓	✓	✓	✓	-
環境變數	✓	✓	✓	✓	✓
Asset 與 Mix	✓	✓	✓	✓	-
Middleware	✓	✓	✓	✓	-
Inertia	✓	-	✓	✓	-
Livewire	✓	✓	-	✓	-
Auth 與 Policy	✓	✓	✓	✓	-
Container Binding	✓	✓	✓	✓	-
Validation	✓	-	-	-	-
Controller Action	✓	-	✓	✓	-
Eloquent	✓	-	-	-	-

快速開始

安裝 — composer global require laravel/lsp
設定編輯器 — 參考上述各編輯器指南
開啟 Laravel 專案 — 伺服器會從根目錄索引 routes、views、translations、config 等專案資料
使用補完 — PHP 檔或 Blade 模板中會自動運作框架感知補完

總結

Laravel LSP 是能大幅提升開發者體驗的工具。它理解編輯器標準功能無法處理的框架特有情境，提供更精確、更有用的補完與診斷。 必要條件：

PHP 8.2 以上
Composer
支援 LSP 的編輯器（Sublime Text、Neovim、Cursor、VS Code 等）

參考資料：

更新日誌

Laravel 13

產品

套件介紹

新版存放庫調查

升級指南

認證

前端

環境建置

Laravel LSP — 以 Language Server Protocol 擴充 IDE 功能

什麼是 Laravel LSP

為何需要

安裝

全域安裝

由原始碼安裝

各編輯器設定指南

Sublime Text

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI 的設定

設定選項

PHP 環境偵測

基本設定範例

Pest Helper Docblock

各功能設定

功能一覽

快速開始

總結

​什麼是 Laravel LSP

​為何需要

​安裝

​全域安裝

​由原始碼安裝

​各編輯器設定指南

​Sublime Text

​Zed

​VS Code

​Cursor

​Neovim

​OpenCode

​GitHub Copilot CLI 的設定

​設定選項

​PHP 環境偵測

​基本設定範例

​Pest Helper Docblock

​各功能設定

​功能一覽

​快速開始

​總結

什麼是 Laravel LSP

為何需要

安裝

全域安裝

由原始碼安裝

各編輯器設定指南

Sublime Text

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI 的設定

設定選項

PHP 環境偵測

基本設定範例

Pest Helper Docblock

各功能設定

功能一覽

快速開始

總結