Laravel LSP — 通过 Language Server Protocol 扩展 IDE 能力

本文为 v0.0.19、截至 2026 年 6 月的初步调查内容。目前尚未在 Packagist 上架,还不能通过 composer 安装。

什么是 Laravel LSP

Laravel LSP(Language Server Protocol)是一款官方工具,为编辑器提供“理解 Laravel 框架”的 IDE 能力。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 全局安装:

composer global require laravel/lsp

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

laravel-lsp

从源码安装

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

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

安装 LSP 插件后,在 Preferences: LSP Settings 中添加客户端配置:

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

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

Cursor

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

laravel-lsp

VS Code

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

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
}

按能力细分的配置

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

{
    "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	✓	-	-	-	-

快速开始

安装 — 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 LSP

​为什么需要它

​安装

​全局安装

​从源码安装

​分编辑器的配置指南

​Sublime Text

​Neovim

​Cursor

​VS Code

​OpenCode

​GitHub Copilot CLI 中的配置

​配置项

​PHP 环境检测

​基本配置示例

​按能力细分的配置

​可用能力一览

​快速开始

​总结

什么是 Laravel LSP

为什么需要它

安装

全局安装

从源码安装

分编辑器的配置指南

Sublime Text

Neovim

Cursor

VS Code

OpenCode

GitHub Copilot CLI 中的配置

配置项

PHP 环境检测

基本配置示例

按能力细分的配置

可用能力一览

快速开始

总结