Laravel LSP — 基于 Language Server Protocol 的 IDE 功能扩展

本文基于 v0.0.27，信息截至 2026 年 7 月。现已注册到 Packagist，可通过 composer global require laravel/lsp 安装。

什么是 Laravel LSP

Laravel LSP（Language Server Protocol）是官方提供的工具，可为编辑器提供理解 Laravel 框架的 IDE 功能。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 全局安装：

composer global require laravel/lsp

请确保 Composer 的 global bin 目录已加入 PATH，然后可通过以下命令启动：

laravel-lsp

从源码安装

如果想使用开发版，可以克隆仓库后运行：

gh repo clone laravel/lsp
cd lsp
composer install
php server

设置 shell 别名以便使用 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

安装并配置官方的 Laravel Sublime Text extension。

Zed

安装并配置官方的 Laravel Zed extension。

VS Code

安装并配置官方的 Laravel VS Code extension。

Cursor

Cursor 兼容 VS Code 扩展，因此可直接使用上述 Laravel VS Code extension。

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

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
}

Pest 辅助 docblock

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

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

{
    "pestGenerateDocBlocks": true,
    "pestHelperFilePath": "storage/framework/testing/_pest.php"
}

按功能配置

各功能都可以单独启用或禁用。后缀有 Completion、Diagnostics、Hover、Link 等：

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

快速开始

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

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI 中的配置

配置选项

PHP 环境检测

基本配置示例

Pest 辅助 docblock

按功能配置

提供的功能一览

快速开始

小结

​什么是 Laravel LSP

​为什么需要它

​安装

​全局安装

​从源码安装

​各编辑器配置指南

​Sublime Text

​Zed

​VS Code

​Cursor

​Neovim

​OpenCode

​GitHub Copilot CLI 中的配置

​配置选项

​PHP 环境检测

​基本配置示例

​Pest 辅助 docblock

​按功能配置

​提供的功能一览

​快速开始

​小结

什么是 Laravel LSP

为什么需要它

安装

全局安装

从源码安装

各编辑器配置指南

Sublime Text

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI 中的配置

配置选项

PHP 环境检测

基本配置示例

Pest 辅助 docblock

按功能配置

提供的功能一览

快速开始

小结