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 等)

参考资料:

Changelog

Laravel 13

产品

包介绍

新仓库探索

升级指南

认证

前端

环境搭建

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

什么是 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 环境检测

​基本配置示例

​按能力细分的配置

​可用能力一览

​快速开始

​总结

什么是 Laravel LSP

为什么需要它

安装

全局安装

从源码安装

分编辑器的配置指南

Sublime Text

Neovim

Cursor

VS Code

OpenCode

GitHub Copilot CLI 中的配置

配置项

PHP 环境检测

基本配置示例

按能力细分的配置

可用能力一览

快速开始

总结