> ## 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.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 提供的功能：

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

## 为什么需要它

编辑器内置的 PHP 补全无法理解 Laravel 框架的抽象层。例如：

* 在 `Route::get()` 的第一个参数中输入 URI 模式时没有补全
* 输入 `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 别名以便使用 `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 辅助 docblock

这是 v0.0.27 中新增的选项。当 Pest 测试或 Composer autoload 文件发生变化时，会为 Pest 辅助函数自动生成并更新 docblock：

| 选项                      | 类型        | 默认值                                     | 说明                            |
| ----------------------- | --------- | --------------------------------------- | ----------------------------- |
| `pestGenerateDocBlocks` | `boolean` | `true`                                  | 是否生成并持续更新 Pest 辅助函数的 docblock |
| `pestHelperFilePath`    | `string`  | `"storage/framework/testing/_pest.php"` | Pest 辅助函数的输出路径（相对于项目根目录）      |

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

## 提供的功能一览

| 功能领域               | 补全 | 悬停 | 诊断 | 链接 | 快速修复 |
| ------------------ | -- | -- | -- | -- | ---- |
| 路由                 | ✓  | ✓  | ✓  | ✓  | -    |
| 视图 & Blade         | ✓  | ✓  | ✓  | ✓  | ✓    |
| 翻译                 | ✓  | ✓  | -  | -  | -    |
| 配置                 | ✓  | ✓  | ✓  | ✓  | -    |
| 环境变量               | ✓  | ✓  | ✓  | ✓  | ✓    |
| 资源 & 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 Reverb](/zh-CN/reverb.md)
- [Laravel 13 新功能汇总](/zh-CN/blog/laravel-13-new-features.md)
- [Core —— AT Protocol 核心操作](/zh-CN/packages/laravel-bluesky/core.md)
- [Laravel Fortify 与 Starter Kit](/zh-CN/advanced/fortify.md)
- [Laravel Passkeys 初步调查(passkeys-server + @laravel/passkeys)](/zh-CN/blog/passkeys-introduction.md)