> ## 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 实现。为编辑器提供框架级别的补全和悬停信息等能力。

<Info>
  本文为 v0.0.19、截至 2026 年 6 月的初步调查内容。目前尚未在 Packagist 上架,还不能通过 composer 安装。
</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 提供的能力:

* **补全** — 路由、视图、配置键、翻译键、Livewire 组件等的自动补全
* **悬停信息** — 光标停在符号上时显示说明、文档、上下文信息
* **诊断** — 实时检测代码中的问题
* **文档链接** — 文件和资源之间的链接功能
* **快速修复** — 常见问题的自动修复建议
* **跳转到定义** — 跳转到符号定义处

## 为什么需要它

编辑器自带的 PHP 补全无法理解 Laravel 框架的抽象层。例如:

* 在 `Route::get()` 的第一个参数里输入 URI pattern 时没有补全
* 在 `view('users.index')` 中输入视图名时,实际的视图文件名不会被补全
* 配置文件的键(`config('app.name')`)和翻译键(`trans('messages.welcome')`)不在补全范围
* Blade 模板内的补全和校验,编辑器自带能力也不支持

Laravel LSP 理解这些"框架特有的上下文",并提供准确的补全和诊断。

## 安装

### 全局安装

用 Composer 全局安装:

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

确认 Composer 的 global bin 目录在 `PATH` 中,然后通过以下命令启动:

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

### 从源码安装

想使用开发版时,可以克隆仓库并运行:

```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

安装 [LSP 插件](https://packagecontrol.io/packages/LSP) 后,在 `Preferences: LSP Settings` 中添加客户端配置:

```json theme={null}
{
    "clients": {
        "laravel-lsp": {
            "enabled": true,
            "command": ["laravel-lsp"],
            "selector": "embedding.php | text.html.blade"
        }
    }
}
```

### 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({})
```

### Cursor

Cursor 支持 VS Code 扩展,因此只要装了 Laravel 扩展就能自动使用。本地开发时使用兼容 VS Code 的 LSP 客户端,并指定命令:

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

### VS Code

VS Code 同样具备 LSP 客户端能力,可以通过扩展进行配置。

### 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
}
```

### 按能力细分的配置

每项能力都可以独立开关。后缀有 `Completion`、`Diagnostics`、`Hover`、`Link` 等:

```json theme={null}
{
    "routeCompletion": true,
    "routeDiagnostics": true,
    "viewDiagnostics": false,
    "translationHover": true,
    "configLink": true,
    "envCompletion": true,
    "bladeComponentLink": true
}
```

## 可用能力一览

| 能力领域               | 补全 | 悬停 | 诊断 | 链接 | 快速修复 |
| ------------------ | -- | -- | -- | -- | ---- |
| 路由                 | ✓  | ✓  | ✓  | ✓  | -    |
| 视图 & Blade         | ✓  | ✓  | ✓  | ✓  | ✓    |
| 翻译                 | ✓  | ✓  | -  | -  | -    |
| 配置                 | ✓  | ✓  | ✓  | ✓  | -    |
| 环境变量               | ✓  | ✓  | ✓  | ✓  | ✓    |
| Asset & Mix        | ✓  | ✓  | ✓  | ✓  | -    |
| Middleware         | ✓  | ✓  | ✓  | ✓  | -    |
| Inertia            | ✓  | -  | ✓  | ✓  | -    |
| Livewire           | ✓  | ✓  | -  | ✓  | -    |
| Auth & Policies    | ✓  | ✓  | ✓  | ✓  | -    |
| Container Bindings | ✓  | ✓  | ✓  | ✓  | -    |
| Validation         | ✓  | -  | -  | -  | -    |
| Controller Actions | ✓  | -  | ✓  | ✓  | -    |
| 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 MCP](/zh/mcp.md)
- [Laravel Scout](/zh/scout.md)
- [Core —— AT Protocol 核心操作](/zh/packages/laravel-bluesky/core.md)
- [Laravel 与 AI 开发](/zh/ai.md)
- [Laravel Wayfinder 介绍](/zh/blog/wayfinder-introduction.md)