AB
AB
AiBoss站

全部分类

教程

Laravel Boost 教程：让 AI 编码代理读懂你的 Laravel 项目

教程

Laravel Boost 教程：让 AI 编码代理读懂你的 Laravel 项目

Laravel Boost 是面向 AI 编码代理的 MCP 服务器，把项目的真实数据库结构、依赖版本与 Laravel 生态文档喂给代理，减少「看起来对但跑不起来」的代码。本教程覆盖安装、编辑器接入、内置工具清单、Guidelines 与 Skills 的区别、完整实操示例与日常维护要点。

用 AI 编码代理写 Laravel 代码时，常见的问题不是代理不会写 PHP，而是它写的是「通用 PHP」。它会调用早已废弃的 API，凭空假设数据表字段，把 Livewire 或 Inertia 的版本搞混，写出的测试跑不通。根源在于代理手里只有泛化的语言知识，没有你这个项目的上下文。Laravel Boost 就是为补上这块缺口而生的：它是一个面向 AI 编码代理的 MCP 服务器，把项目的真实结构、已安装依赖的版本、以及 Laravel 生态的文档检索能力暴露给代理，让代理从「通用助手」变成「了解你项目的 Laravel 开发者」。它适合已经在用 Cursor、Claude Code、PhpStorm、GitHub Copilot、Gemini CLI 等工具，并且希望减少返工与人工纠偏的 Laravel 开发者。

准备工作

在动手之前，先确认环境满足要求，并想清楚要接入哪个编辑器。

环境要求

  • Laravel 10、11、12 及以上版本
  • PHP 8.1 及以上
  • 项目使用 Composer 管理依赖
  • 已经安装并配置好至少一个支持 MCP 的 AI 编码代理

版本支持范围、PHP 最低版本这类信息会随发布变化，实际以官网当前信息为准。

Boost 提供什么

Laravel Boost 是一个 Composer 包，安装后主要带来三样东西：

  • Laravel 专用 MCP 服务器：内置 15 个以上的工具，覆盖应用信息、数据库结构、路由、日志、文档检索等
  • 版本感知的 AI 指南（Guidelines）：可按需组合，告诉代理这个项目该遵循什么约定
  • 文档检索 API：覆盖 Laravel 生态的大量文档条目，并按项目实际安装的包版本做匹配

换句话说，它同时给代理两样东西：Laravel 的语境，以及你这个项目的语境。

安装前需要知道的取舍

Boost 作为开发依赖安装，会生成若干配置文件。这些文件由命令重新生成，因此通常建议加入 .gitignore，避免团队成员之间反复产生无意义的差异。如果团队希望统一代理行为，也可以选择把其中一部分纳入版本控制，这属于团队约定，不是工具强制。

操作步骤

第一步：安装 Composer 包

在项目根目录执行：

composer require laravel/boost --dev

使用 --dev 表示它只进入开发依赖，不会部署到生产环境。

第二步：运行安装命令

php artisan boost:install

boost:install 是交互式的。它会自动检测你正在使用的编辑器（Cursor、Claude Code、PhpStorm 等），并据此生成对应的配置文件。安装过程中会生成的主要文件包括：

  • .mcp.json：MCP 服务器注册信息
  • CLAUDE.md 或 AGENTS.md：给代理的项目说明入口
  • .cursor/rules/ 目录下的指南文件
  • boost.json：Boost 自身的配置

这些文件会被后续的更新命令重新生成，因此建议加入 .gitignore。

第三步：在编辑器中启用

不同编辑器的启用方式略有差别。

Cursor

  1. 按 Cmd + Shift + P（Windows / Linux 下为 Ctrl + Shift + P）打开命令面板
  2. 打开「MCP Settings」
  3. 把 laravel-boost 这一项打开

Claude Code

用一条命令注册本地 stdio 类型的 MCP 服务器：

claude mcp add -s local -t stdio laravel-boost php artisan boost:mcp

这里的 -s local 表示作用域为本机，-t stdio 表示通过标准输入输出通信，最后是要执行的命令。

其他编辑器

PhpStorm、GitHub Copilot、Gemini CLI 等工具的接入方式类似，核心都是把 php artisan boost:mcp 注册为一个 stdio 类型的 MCP 服务器。具体菜单路径以各编辑器当前版本的界面为准。

第四步：确认代理能调用工具

启用之后，不需要你手动指定调用哪个工具。代理会根据任务自行决定。你可以先用一个简单的问题验证链路是否打通，例如让代理说明当前项目的 Laravel 版本和已安装的主要包。如果它能给出与 composer.json、composer.lock 一致的结果，说明 MCP 连接正常。

内置工具清单

Boost 提供的工具是它真正产生价值的地方。代理会在需要时自动调用它们，你不需要记住调用语法，但了解每个工具能做什么，有助于你写出更精准的提示词。

工具作用
Application Info获取 PHP 与 Laravel 版本、已安装的包、Eloquent 模型清单
Database Schema读取全部数据表的结构
Database Query对真实数据库执行查询，主要用于读取
List Routes查看路由列表及其绑定的中间件
Tinker在应用上下文中执行 PHP 代码
Search Docs按已安装包的版本检索对应文档
Last Error / Read Log Entries读取最近的错误与日志记录
Browser Logs获取浏览器控制台的报错信息
List Artisan Commands列出当前可用的 Artisan 命令

此外还有用于反馈的 Report Feedback 工具，后面会单独说明。

Guidelines 与 Skills 的区别

这两个概念容易混淆，但分工很明确。

  • Guidelines：从一开始就始终加载的基础规则，例如 Laravel 的通用约定、项目的编码风格
  • Skills：只在需要时才加载的详细知识，例如 Livewire、Pest、Inertia 相关的具体做法

这样分层的好处是上下文不会被无关内容撑满。如果所有知识都常驻，代理的注意力会被稀释，反而降低准确度。按需加载让它在处理具体任务时才引入对应领域的细节。

自定义的指南和技能同样可以添加。你可以把项目特有的约定写进指南，把某个内部组件的用法写成技能，让代理在涉及该组件时才读取。

一个完整示例

下面用三个由浅入深的场景，说明接入 Boost 之后代理的工作方式有什么不同。

场景一：给模型加一个查询作用域

提示词可以这样写：

给 User 模型加一个 active 作用域，只取 status 为 active 的记录。

接入 Boost 之后，代理会先通过 Application Info 和 Database Schema 确认现状：User 模型在哪里、status 字段实际叫什么、是字符串还是枚举。然后它会参考项目里已有作用域的写法，用符合当前 Laravel 版本的方式实现，必要时还会补上测试。

没有 Boost 时，代理很可能直接假设字段名是 status、值是字符串 'active'，而实际项目里可能是枚举或者布尔字段，结果就是一段需要你手动改的代码。

场景二：排查白屏

提示词：

用户列表页出现白屏，帮我查原因并修复。

代理的处理路径大致是：先用 Last Error 读取最近的异常，再用 Browser Logs 看前端控制台的报错，然后定位到相关的控制器和视图，最后给出修改方案。整个过程不需要你手动复制粘贴日志。

场景三：写对 Livewire 或 Inertia 的代码

这两个生态的 API 在不同大版本之间差异明显。Boost 会读取项目实际安装的版本，据此给出对应的写法，从而降低代理推荐过时 API 的概率。这一点在升级期间尤其有用：代理不会把旧版本的写法混进新版本的项目里。

把三个场景串起来的最小流程

  1. 确认 Boost 已安装并启用，代理能读到 Application Info
  2. 用自然语言描述任务，不需要指定调用哪个工具
  3. 观察代理是否先做现状确认（读 schema、读版本、读日志）
  4. 拿到代码后自行审查，再决定是否合并

日常维护

定期更新

php artisan boost:update

这个命令会重新生成配置文件与指南内容。把它挂到 Composer 的 post-update-cmd 脚本里，可以在每次依赖更新后自动同步，省去手动执行的步骤。

把项目目的写清楚

在配置中补充应用的概要说明，能进一步提升代理的理解程度。代理知道这个项目是做什么的、面向谁、有哪些核心概念之后，给出的实现会更贴近实际意图，而不是只满足字面需求。

提交反馈

Boost 内置了 Report Feedback 工具。你只需要告诉代理「这个工具有用」或者「这里不对劲」，反馈就会传达到 Laravel 团队。这是一个低成本的参与方式，遇到工具行为异常时值得用一下。

注意事项

  • 生成的代码必须人工审查。 Boost 能显著提升代理输出的贴合度，但最终判断仍然要由人来做。它降低的是返工量，不是取消评审环节。
  • 生成的文件建议加入 .gitignore。 这些文件会被 boost:update 重新生成，纳入版本控制容易产生噪音。若团队有统一代理行为的需要，再单独约定。
  • Database Query 以读取为主。 让代理直接对数据库执行写操作风险较高，涉及数据变更时应当由人执行迁移或明确授权的命令。
  • 版本与配额信息以官网为准。 支持的 Laravel 与 PHP 版本范围、工具数量、文档条目规模都可能随版本变化，本文不给出固定数字作为长期依据。
  • 接入方式随编辑器版本变化。 菜单名称与命令参数可能调整，遇到不一致时以编辑器当前版本的说明为准。
  • 上下文分层需要维护。 Guidelines 与 Skills 的划分如果长期不整理，会逐渐退化成「什么都常驻」，失去按需加载的意义。

把 Boost 接进项目之后，代理的行为会从「凭印象写 Laravel」转向「先查证再动手」。这个转变带来的直接收益是更少的返工和更容易评审的代码，而代价只是两条安装命令和一次编辑器配置。

返回