> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Laravel 官方的 Language Server Protocol 實作。為編輯器提供框架感知的補完與 hover 功能。

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

## 什麼是 Laravel LSP

**Laravel LSP**（Language Server Protocol）是為編輯器提供 Laravel 框架感知 IDE 功能的官方工具。[Language Server Protocol](https://microsoft.github.io/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 全域安裝：

```bash theme={null}
composer global require laravel/lsp
```

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

```bash theme={null}
laravel-lsp
```

### 由原始碼安裝

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

```bash theme={null}
gh repo clone laravel/lsp
cd lsp
composer install
php server
```

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

```bash theme={null}
# 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](https://github.com/laravel/sublime-extension)。

### Zed

安裝並設定官方 [Laravel Zed extension](https://github.com/laravel/zed-extension)。

### VS Code

安裝並設定官方 [Laravel VS Code extension](https://github.com/laravel/vs-code-extension)。

### Cursor

Cursor 支援 VS Code 擴充功能，因此可直接使用上述 [Laravel VS Code extension](https://github.com/laravel/vs-code-extension)。

### Neovim

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

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

vim.lsp.enable("laravel_lsp")
```

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

```lua theme={null}
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 設為自訂伺服器：

```json theme={null}
{
    "$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` 進行全域設定，不需另外的編輯器設定：

```json theme={null}
{
  "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`。

### 基本設定範例

```json theme={null}
{
    "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 輸出路徑（相對專案根目錄）        |

```json theme={null}
{
    "pestGenerateDocBlocks": true,
    "pestHelperFilePath": "storage/framework/testing/_pest.php"
}
```

### 各功能設定

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

```json theme={null}
{
    "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          | ✓  | -     | -  | -  | -    |

## 快速開始

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

## 總結

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

**必要條件：**

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

**參考資料：**

* [Laravel LSP GitHub 儲存庫](https://github.com/laravel/lsp)
* [Language Server Protocol 官方](https://microsoft.github.io/language-server-protocol/)
* [GitHub Copilot CLI LSP 設定指南](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers)


## Related topics

- [Laravel Fortify 與啟動套件](/zh-TW/advanced/fortify.md)
- [Laravel 13 新功能彙總](/zh-TW/blog/laravel-13-new-features.md)
- [Laravel Sail](/zh-TW/sail.md)
- [Core — AT Protocol 核心操作](/zh-TW/packages/laravel-bluesky/core.md)
- [Laravel Passkeys 初步調查（passkeys-server + @laravel/passkeys）](/zh-TW/blog/passkeys-introduction.md)