第 3-5 章实测笔记：从零搭建 Laravel + Boost + Cursor

实测时间：2026-05-07 操作系统：Windows 10 (19045) · PowerShell 工作区：D:\workspace\cursor\laravel-boost 关联大纲章节：第 3 章（环境安装）/ 第 4 章（安装 Boost）/ 第 5 章（配置 AI 编辑器）

0. 实测前的环境画像

工具	版本	状态
PHP	8.2.9 NTS（PHPStudy 装的）	✅ 满足 Laravel 12 的 PHP 8.2+
Composer	2.6.6	✅
Node	23.10.0 + npm 11.6.1	✅ 前端构建用
Laravel installer	未安装	⚠️ 不影响，用 `composer create-project` 替代
`pdo_sqlite` 扩展	未启用	🔴 后面踩坑了，见第 5 节

速查命令：

powershell

php --version
composer --version
node --version; npm --version
php -m | Select-String -Pattern "sqlite|pdo|mbstring|openssl"

1. 创建 Laravel 项目（对应第 3 章）

踩坑 1：Composer 国内镜像不可靠

最初用了腾讯云镜像，结果在拉 symfony/deprecation-contracts 时直接 HTTP 404：

The "https://mirrors.cloud.tencent.com/repository/composer/symfony/deprecation-contracts/v3.7.0/symfony-deprecation-contracts-v3.7.0.zip" file could not be downloaded (HTTP/2 404)

切到阿里云镜像 https://mirrors.aliyun.com/composer/，又遇到第二个问题：阿里云镜像里的 laravel/tinker 元数据只有 2.x-dev 没有稳定版，导致依赖解析失败：

Root composer.json requires laravel/tinker ^2.10.1, found laravel/tinker[2.x-dev] but it does not match your minimum-stability.

结论：搭 Laravel 环境时，国内镜像不要轻易用。Packagist 官方源（https://repo.packagist.org）虽然慢一些，但稳。

恢复官方源：

powershell

composer config -g --unset repos.packagist

成功步骤

powershell

cd D:\workspace\cursor\laravel-boost
composer create-project laravel/laravel playground --prefer-dist --no-interaction

耗时约 1 分钟，最终装到 Laravel 12.10.0（不是预期的 13，写大纲时要把版本范围改清楚）。

项目目录速览（对比 ThinkPHP）

Laravel 12	对应 ThinkPHP	备注
`app/Http/Controllers/`	`application/.../controller/`	控制器
`app/Models/`	`application/.../model/`	Eloquent 模型
`routes/web.php` + `routes/api.php`	`route.php` 单文件	路由分文件
`database/migrations/`	无对应（TP 用 SQL 文件）	数据库版本控制
`config/`	`config/`	配置
`.env`	`.env` 或 `config/database.php`	环境变量驱动

2. 安装 Laravel Boost（对应第 4 章）

powershell

cd playground
composer require laravel/boost --dev --no-interaction

Boost 实际版本：^2.4。注意它会自动拉两个依赖：

laravel/mcp (v0) —— Laravel 官方的 MCP 协议层
laravel/roster (v1) —— Boost 内部用来检测项目里装了哪些生态包（Livewire / Filament 等）

这解释了大纲第 2 章说"自动检测并选择生态包"是怎么做到的。

3. 运行 `boost:install`（对应第 4 章核心）

boost:install 默认是交互式的。它支持的参数：

powershell

php artisan boost:install --help

参数	作用
`--guidelines`	安装 AI guidelines
`--skills`	安装 agent skills
`--mcp`	安装 MCP server 配置
`-n` / `--no-interaction`	全自动

非交互模式跑一次：

powershell

php artisan boost:install --guidelines --skills --mcp --no-interaction

输出解读

Adding 8 guidelines to your selected agents
 ┌───────┬──────────────┬────────────┬──────────────┬─────────────┐
 │ boost │ deployments  │ foundation │ laravel/core │ laravel/v12 │
 │ php   │ phpunit/core │ pint/core  │              │             │
 └───────┴──────────────┴────────────┴──────────────┴─────────────┘

  Claude Code... ✓
  Gemini CLI ... ✓

Syncing 1 skills for skills-capable agents
 ┌────────────────────────┐
 │ laravel-best-practices │
 └────────────────────────┘
  Claude Code... ✓
  Gemini CLI ... ✓

Installing MCP servers to your selected Agents
  Claude Code... ✓
  Gemini CLI ... ✓

⚠️ 关键发现：非交互模式不识别 Cursor

--no-interaction 模式只自动配了 Claude Code 和 Gemini CLI——Cursor 没有被检测到，需要手动配置。这一条必须写进第 5 章，否则 Cursor 用户会卡在这里。

产物全清单

playground/
├── .agents/skills/laravel-best-practices/   # 通用 skill 目录（22 个 rule .md）
├── .claude/skills/laravel-best-practices/   # Claude Code 专用副本（同内容）
├── .gemini/settings.json                    # Gemini CLI 配置
├── .mcp.json                                # MCP server 配置（Anthropic 标准）
├── boost.json                               # Boost 自身配置
├── CLAUDE.md                                # Guidelines 文件（10,185 字节，190 行）
└── GEMINI.md                                # Guidelines 文件（与 CLAUDE.md 完全相同）

`CLAUDE.md` 第一段精华

=== foundation rules ===
## Foundational Context
- php - 8.2
- laravel/framework (LARAVEL) - v12
- laravel/prompts (PROMPTS) - v0
- laravel/boost (BOOST) - v2
- laravel/mcp (MCP) - v0
- laravel/pail (PAIL) - v1
- laravel/pint (PINT) - v1
- laravel/sail (SAIL) - v1
- phpunit/phpunit (PHPUNIT) - v11

这就是 Guidelines 锁版本的机制：把当前项目里每个核心包的具体版本告诉 AI，避免 AI 拿 Laravel 9 的语法生成 Laravel 12 的代码。这一段是大纲第 17 章"野路子 PHP"问题的最佳举例素材。

`boost.json` 内容

json

{
  "cloud": false,
  "guidelines": true,
  "mcp": true,
  "nightwatch": false,
  "sail": false,
  "skills": ["laravel-best-practices"]
}

Skills 目录长这样

.agents/skills/laravel-best-practices/ 下有 1 个 SKILL.md + 22 个 rules/*.md：

advanced-queries / architecture / blade-views / caching / collections / config /
db-performance / eloquent / error-handling / events-notifications / http-client /
mail / migrations / queue-jobs / routing / scheduling / security / style /
testing / validation

SKILL.md 用 YAML frontmatter 定义元信息：

yaml

---
name: laravel-best-practices
description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. ..."
license: MIT
metadata:
  author: laravel
---

→ 这是 Anthropic Agent Skills 标准格式。description 告诉 AI"什么时候该激活我"，正对应大纲第 17 章的"Skills 按需激活（减少上下文污染）"。

4. 让 Cursor 接入 Boost MCP（对应第 5 章）

关键差异：Cursor vs Claude Code 的 MCP 配置

Claude Code：自动读 Laravel 项目根目录下的 .mcp.json（Anthropic 标准位置）
Cursor：必须手动写 .cursor/mcp.json，且位置在 Cursor 工作区的根目录

我的 Cursor 工作区是外层 D:\workspace\cursor\laravel-boost，不是 Laravel 项目根 playground/。所以 Boost 自动生成的 playground/.mcp.json 对 Cursor 来说没用。

Boost 默认配置（在 playground 内运行时有效）

json

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["artisan", "boost:mcp"]
    }
  }
}

Cursor 工作区配置（在外层运行时必须用绝对路径）

写到 D:\workspace\cursor\laravel-boost\.cursor\mcp.json：

json

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": [
        "D:/workspace/cursor/laravel-boost/playground/artisan",
        "boost:mcp"
      ]
    }
  }
}

两点注意：

路径用正斜杠 /，避免 Windows 反斜杠的 JSON 转义问题
不要写 cwd 字段，部分 Cursor 版本不识别——直接用 artisan 绝对路径，Laravel 框架靠 __DIR__ 自动定位项目根

进程冒烟测试（不重启 Cursor 也能验证）

powershell

$proc = Start-Process -FilePath "php" `
  -ArgumentList "D:/workspace/cursor/laravel-boost/playground/artisan","boost:mcp" `
  -PassThru -RedirectStandardError "err.log" -RedirectStandardOutput "out.log" `
  -NoNewWindow
Start-Sleep -Seconds 4
if (-not $proc.HasExited) {
    Write-Host "OK pid=$($proc.Id)"
    Stop-Process -Id $proc.Id -Force
}

预期：进程持续运行 4 秒不退出（stdio MCP server 在等 client 发 JSON-RPC），err.log 为空。如果秒退、有报错堆栈，那就是 PHP 找不到 artisan 路径，回去检查绝对路径。

真正的连通性验证

需要重启 Cursor → 让它重新加载 .cursor/mcp.json → 在 Cursor 设置面板的 MCP 列表里确认 laravel-boost 是绿灯 → 然后让 AI 调一条 mcp_laravel-boost_application_info 之类的工具，看到返回 PHP/Laravel 版本就算通了。

5. SQLite 驱动踩坑（PHPStudy 用户必看）

Laravel 12 默认配置 DB_CONNECTION=sqlite，安装最后一步会跑 php artisan migrate，结果报错：

WARN  could not find driver
(Connection: sqlite, Database: D:\workspace\cursor\laravel-boost\playground\database\database.sqlite,
SQL: select exists (select 1 from "main".sqlite_master ... ))

根因排查

powershell

# 1) 确认 PHP 是哪个：
(Get-Command php).Source
# → D:\phpstudy_pro\Extensions\php\php8.2.9nts\php.exe

# 2) 看 ext 目录有没有 dll：
Get-ChildItem "D:\phpstudy_pro\Extensions\php\php8.2.9nts\ext" `
  | Where-Object { $_.Name -match "sqlite|pdo" }
# → php_pdo_sqlite.dll 和 php_sqlite3.dll 都有！

# 3) 看 php.ini 有没有启用：
$ini = "D:\phpstudy_pro\Extensions\php\php8.2.9nts\php.ini"
Get-Content $ini -Encoding UTF8 | Select-String "sqlite"
# → ;extension=pdo_sqlite     ← 注释掉了
# → ;extension=sqlite3        ← 注释掉了

修复步骤

powershell

# 备份
$ini = "D:\phpstudy_pro\Extensions\php\php8.2.9nts\php.ini"
Copy-Item $ini "$ini.bak.$(Get-Date -Format yyyyMMdd-HHmmss)"

# 编辑 php.ini，找两行：
#   ;extension=pdo_sqlite
#   ;extension=sqlite3
# 去掉行首的分号

# 验证
php -m | Select-String "sqlite"
# 期待：pdo_sqlite / sqlite3 都出现

验证 migrate 通过

INFO  Running migrations.
  0001_01_01_000000_create_users_table  11.04ms DONE
  0001_01_01_000001_create_cache_table   8.56ms DONE
  0001_01_01_000002_create_jobs_table    9.44ms DONE

6. 阶段 ① 完工 checklist

[x] PHP 8.2.9 + Composer 2.6.6 + Node 23 全装好
[x] Laravel 12.10.0 项目在 playground/
[x] Boost v2.4 + laravel/mcp + laravel/roster 已装
[x] boost:install --guidelines --skills --mcp 跑过
[x] playground/.mcp.json 自动生成（Claude Code 用）
[x] playground/CLAUDE.md 自动生成（10KB Guidelines）
[x] playground/.agents/skills/laravel-best-practices/ 22 条规则
[x] D:\workspace\cursor\laravel-boost\.cursor\mcp.json 手写（Cursor 用）
[x] boost:mcp 进程冒烟测试通过
[x] PHPStudy 的 pdo_sqlite + sqlite3 已启用
[x] php artisan migrate 跑通，3 张默认表建立
[ ] 重启 Cursor → MCP 真正连通 → AI 调用 application_info 成功（用户操作）

7. 给大纲的修订建议（写回 `Laravel_Boost_教程大纲.md`）

章节	当前内容	建议补充
第 3 章	"Composer 安装与换源（国内镜像）"	反向警告：腾讯云缺包 / 阿里云缺稳定版元数据，优先用官方源
第 3 章	"PHP 版本检查与升级"	加一节"PHPStudy 用户的扩展启用清单"（pdo_sqlite / sqlite3 都默认关）
第 4 章	"运行初始化命令：`php artisan boost:install`"	加 `--no-interaction` 参数说明 + `--guidelines/--skills/--mcp` 三个独立开关
第 4 章	"生成的文件说明"	加上 `boost.json` / `.agents/` / `CLAUDE.md = GEMINI.md` 这些细节
第 5 章	"Cursor 接入 Boost MCP 步骤"	重点重写：`boost:install` 不识别 Cursor，必须手动写 `.cursor/mcp.json`，且 Cursor 工作区根 ≠ Laravel 项目根时要用绝对路径
第 5 章	"验证连接是否成功"	加上"进程冒烟测试"这个不重启 Cursor 也能做的离线验证
顶部说明	"工具版本：Laravel 10/11/12/13"	改为 "Laravel 10/11/12（实测 12.10.0）"——13 还没 GA，别误导

8. 下一步：阶段 ② 摸清 Boost 工具

打算让 AI 通过新接入的 MCP 调用以下工具，每个工具都记录真实输入输出（写到 docs/04-Boost工具实测.md）：

工具	不依赖数据库？	优先级
`application_info`	✅	P0（第一个验证用）
`list_routes`	✅	P0
`list_artisan_commands`	✅	P0
`read_config`	✅	P1
`search_docs`	✅	P0（最有价值的差异化能力）
`database_schema`	❌ 需 sqlite	P1（已修好）
`database_query`	❌ 需 sqlite	P1
`tinker`	✅ 但需 Laravel 上下文	P1
`read_log_entries`	✅	P2
`last_error`	✅	P2

第 3-5 章 实测笔记：从零搭建 Laravel + Boost + Cursor ​

0. 实测前的环境画像 ​

1. 创建 Laravel 项目（对应第 3 章） ​

踩坑 1：Composer 国内镜像不可靠 ​

成功步骤 ​

项目目录速览（对比 ThinkPHP） ​

2. 安装 Laravel Boost（对应第 4 章） ​

3. 运行 boost:install（对应第 4 章核心） ​

输出解读 ​

⚠️ 关键发现：非交互模式不识别 Cursor ​

产物全清单 ​

CLAUDE.md 第一段精华 ​

boost.json 内容 ​

Skills 目录长这样 ​

4. 让 Cursor 接入 Boost MCP（对应第 5 章） ​

关键差异：Cursor vs Claude Code 的 MCP 配置 ​

Boost 默认配置（在 playground 内运行时有效） ​

Cursor 工作区配置（在外层运行时必须用绝对路径） ​

进程冒烟测试（不重启 Cursor 也能验证） ​

真正的连通性验证 ​

5. SQLite 驱动踩坑（PHPStudy 用户必看） ​

根因排查 ​

修复步骤 ​

验证 migrate 通过 ​

6. 阶段 ① 完工 checklist ​

7. 给大纲的修订建议（写回 Laravel_Boost_教程大纲.md） ​

8. 下一步：阶段 ② 摸清 Boost 工具 ​

第 3-5 章实测笔记：从零搭建 Laravel + Boost + Cursor

0. 实测前的环境画像

1. 创建 Laravel 项目（对应第 3 章）

踩坑 1：Composer 国内镜像不可靠

成功步骤

项目目录速览（对比 ThinkPHP）

2. 安装 Laravel Boost（对应第 4 章）

3. 运行 `boost:install`（对应第 4 章核心）

输出解读

⚠️ 关键发现：非交互模式不识别 Cursor

产物全清单

`CLAUDE.md` 第一段精华

`boost.json` 内容

Skills 目录长这样

4. 让 Cursor 接入 Boost MCP（对应第 5 章）

关键差异：Cursor vs Claude Code 的 MCP 配置

Boost 默认配置（在 playground 内运行时有效）

Cursor 工作区配置（在外层运行时必须用绝对路径）

进程冒烟测试（不重启 Cursor 也能验证）

真正的连通性验证

5. SQLite 驱动踩坑（PHPStudy 用户必看）

根因排查

修复步骤

验证 migrate 通过

6. 阶段 ① 完工 checklist

7. 给大纲的修订建议（写回 `Laravel_Boost_教程大纲.md`）

8. 下一步：阶段 ② 摸清 Boost 工具