教程导读 · 从 0 到生产 Laravel + Boost 实战录

从这里开始读 → 这是 8 篇实测笔记的入口文档。如果你只想看一篇，看这篇；如果你想看全部，本文档告诉你怎么按顺序读。

一、本教程是什么（5 句话总览）

一本针对 ThinkPHP 老手转 Laravel 的实战教程
配套实战项目 playground/ 跑通了：博客 + 认证 + 队列 + API + 后台 5 件套
全教程以 Laravel Boost 为主线——展示 AI + Boost 怎样让代码接近老手水准
7 篇实测笔记 + 1 份大纲 + 1 份速查 + 本文 = 约 9000 行 / 22 万字
每一行代码都真的跑过测试——总测试 63 个，0.84-2.79s 跑完

这本教程不打算做的事

❌ 不是 Laravel 入门书（已经假设你写过 PHP / 用过 ThinkPHP）
❌ 不是 Filament/Sanctum/Pest 的官方文档替代（关键 API 详细讲，全 API 不讲）
❌ 不教前端（Vite / npm / React 都没用）
❌ 不讲底层（Service Container / Service Provider 一笔带过）

这本教程的特色

✓ 每一篇笔记都是真实战实测——含数字战果（耗时、行数、测试数）+ 时间线 + 踩坑实录
✓ 跨章节复用——13 章 PostPolicy 在 14/16 章0 改动复用
✓ 真实 Bug 诊断流程——SQLite is locked / authorizeResource 不兼容 / Filament v3→v5 跳版本，全部完整经历
✓ 每章都有 ThinkPHP 对照表——5+ 张对照表覆盖路由/Eloquent/Migration/Auth/Queue/API
✓ 每章末尾"复盘"3 个问题：值不值得、Boost 起了什么作用、踩坑教训

二、教程地图（8 篇笔记如何串联）

全部 9 篇文档（按主题分类）

┌─────────────────────────────────────────────────────┐
│ 入口                                                  │
├─────────────────────────────────────────────────────┤
│ 00 教程导读（本篇）                                    │
│ Laravel_Boost_教程大纲                                │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ 环境与工具（2 篇）                                     │
├─────────────────────────────────────────────────────┤
│ 03 环境搭建实测            383 行                      │
│ 12 Boost 工具实战大全      530 行                      │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ 基础速查（1 篇）                                       │
├─────────────────────────────────────────────────────┤
│ 06-11 章节速查           1485 行                      │
│ （路由/Eloquent/Migration/Controller/Blade/Auth）     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ 核心实战（4 篇）⭐⭐⭐                                  │
├─────────────────────────────────────────────────────┤
│ 13 博客实战完整复盘      1279 行   → 数据 + HTTP + 视图 │
│ 15 队列实战              1077 行   → Job + Mail + 测试 │
│ 14 API 化实战            1128 行   → Sanctum + Resource│
│ 16 Filament 后台实战     1106 行   → 后台脚手架        │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ 进阶（1 篇）                                           │
├─────────────────────────────────────────────────────┤
│ 17 Prompt 工程反例集     1549 行                      │
└─────────────────────────────────────────────────────┘

8 篇笔记的"故事线"

03 环境搭建
  ↓ 装 Laravel + Boost + Cursor MCP
  ↓
12 Boost 工具
  ↓ 知道有 9 个工具能用
  ↓
06-11 章节速查
  ↓ 路由 / Eloquent / Migration / Controller / Blade / Auth 速查
  ↓
13 博客实战 ⭐
  ↓ 2 小时做完整博客（CRUD + 权限 + 测试）
  ↓
15 队列实战 ⭐
  ↓ 1.5 小时加异步邮件（Job + Mail）
  ↓
14 API 化实战 ⭐
  ↓ 1.5 小时把博客 API 化（Sanctum + Resource）
  ↓
16 Filament 后台 ⭐
  ↓ 1.5 小时加管理后台
  ↓
17 Prompt 工程反例集
   提炼 prompt 的"5 大病理 + 6 个模板"

跨章节复用关系图（最重要的一张图）

              ┌──────────────────────────────┐
              │   13 章博客（基础底座）         │
              │   - Migration                │
              │   - Post Model + 3 scopes    │
              │   - PostPolicy ⭐            │
              │   - StorePostRequest         │
              │   - UpdatePostRequest        │
              │   - PostController           │
              │   - 5 Blade 视图              │
              │   - PostFactory + Seeder     │
              └──────┬─────────┬─────────┬───┘
                     │         │         │
       ┌─────────────┘         │         └─────────────┐
       │                       │                       │
       ▼                       ▼                       ▼
 ┌───────────┐         ┌───────────┐         ┌─────────────────┐
 │ 15 队列    │         │ 14 API    │         │ 16 Filament 后台 │
 │           │         │           │         │                 │
 │ + Job     │         │ + Sanctum │         │ + admin 字段     │
 │ + Mail    │         │ + Resource│         │ + before() hook │
 │ + Pest    │         │ + Pest    │         │ + Pest          │
 │           │         │           │         │                 │
 │ Policy 0  │         │ Policy 0  │         │ Policy 加 10 行 │
 │ 改动复用   │         │ 改动复用   │         │ before bypass   │
 │ FormReq 0 │         │ FormReq 0 │         │ + FilamentUser  │
 │ 改动复用   │         │ 改动复用   │         │                 │
 └───────────┘         └───────────┘         └─────────────────┘
       ↓                     ↓                       ↓
   触发 Job            发布触发 Job            管理所有文章
   1 行 dispatch       1 行 dispatch          admin bypass

→ 这张图是这本教程最核心的"价值证据"——一次写好的代码（PostPolicy / FormRequest）在 4 个不同场景复用 0 改动。ThinkPHP 项目里你做不到这个。

三、5 条学习路径（按时间预算）

挑一条最贴近你时间预算的路径开始。

路径 A：5 分钟"是不是值得读" ⏱

适合：还在评估这本教程

读本文 §四"30 个必背知识点" → 看你是否被打动
读 13 章 §0 "战果速览"（约 50 行）→ 看 2 小时博客实战的真实数字
读 17 章 §0-§1（约 80 行）→ 看 prompt 工程对 Laravel 的影响

决策点：如果你 5 分钟后觉得"这些事我现在做不到，但确实想做到"——继续读路径 B。

路径 B：1 小时"快速理解全貌" ⏱⏱

适合：想把握全教程脉络再决定深读哪些

路径 A（10 分钟）
03 章环境搭建实测（10 分钟跳读）
12 章 Boost 工具实战大全 §1-§3（15 分钟）
13 章 §0-§3 + §11（核心数据 + HTTP + 复盘，25 分钟）

结束：你应该已经能用 prompt 让 AI 在 Laravel 项目里写出 80% 老手风格代码。

路径 C：半天"能跟着做一遍博客" ⏱⏱⏱⏱

适合：动手派，想把第 13 章的博客也做出来

路径 A（10 分钟）
03 章环境搭建实测 → 跟着装一遍（30-60 分钟，含踩坑可能）
06-11 章速查 § §6 路由 + §7 Eloquent + §9 Controller + §11 认证（30 分钟跳读）
13 章 → 跟着做一遍博客（2 小时）
跑 php artisan test → 看到 31+ 测试 passed

结束：你的项目里已经有一个完整的博客 + 31 个测试。

路径 D：一天"做完整套实战" ⏱⏱⏱⏱⏱⏱⏱⏱

适合：周末沉浸式跑完整套教程

时段	做什么	时长
上午 8-10	环境（03 章） + Boost 工具（12 章）	2h
上午 10-12	博客实战（13 章）	2h
下午 13-15	队列实战（15 章）	2h
下午 15-17	API 化（14 章）+ Filament 后台（16 章前半）	2h
晚 19-20	6-11 章速查复习 + 17 章 prompt 工程	1h

结束：你的项目里有完整的"博客 + 队列 + API + 后台" + 63+ Pest 测试 passed。 这就是 Laravel 现代项目的标准底座。

路径 E：一周"读懂 + 复用到自己项目" ⏱ × 7

适合：要把这套技术栈用到工作项目

天	内容
Day 1	路径 D（一天跑完实战）
Day 2	重读 17 章 prompt 工程反例集，用模板改写自己工作里 5 个 prompt
Day 3	读 06-11 章速查（深读，不跳）+ 抄速查到自己的 cheatsheet
Day 4	把自己工作项目里最简单的 1 个 CRUD 用 Laravel + Boost 重写——对照 13 章
Day 5	把那个 CRUD 加测试（按 13 章 §6 测试章节模式）
Day 6	加 Sanctum API（按 14 章模式）
Day 7	加 Filament 管理界面（按 16 章模式）

结束：你已经把这本教程真的用到工作项目——而不只是"读完"。

→ 这是教程的最高价值实现方式。

四、30 个必背知识点

这一节是从 8 篇笔记里萃取出来的——每条都附原始章节链接。 打印出来贴墙上 / 抄到笔记本 都值得。

环境与版本（4 条）

1. Laravel 12 要求 PHP 8.2+，PHP 8.1 不再支持

→ 早查 php -v，否则装到一半才知道版本不够。 → 来源：03 章 §1.1

2. Composer 镜像踩坑顺序：腾讯云 → 阿里云 → 官方

→ 国内镜像有时缺包。用 composer config -g repo.packagist composer https://packagist.org 切回官方最稳。 → 来源：03 章 §2.3

3. 不锁版本是查"当前主流版本"的最快方式

bash

composer require some/package --dry-run

→ Filament v3.2 → v5.6.2 跳了 2 个主版本就是这么发现的。 → 来源：16 章 §1

4. Cursor MCP 配置必须用绝对路径

json

{
  "mcpServers": {
    "laravel-boost": {
      "command": "php",
      "args": ["D:/绝对路径/playground/artisan", "boost:mcp"]
    }
  }
}

→ Cursor workspace root 与 Laravel 项目根目录不同，相对路径会找不到 artisan。 → 来源：03 章 §5

Eloquent（6 条）

5. ⭐ Laravel 11+ 用 `casts()` 方法签名版

php

// ✅ Laravel 11+
protected function casts(): array
{
    return ['published_at' => 'datetime'];
}

// ❌ Laravel 10 及之前
protected $casts = ['published_at' => 'datetime'];

→ 来源：06-11 §7.1 | 13 章 §2.2

6. ⭐ 关系命名陷阱：方法名 ≠ 字段前缀必须显式传外键

php

// 方法名 = 字段前缀 → 默认 user_id
public function user(): BelongsTo { return $this->belongsTo(User::class); }

// 方法名 ≠ 字段前缀 → 必须传第二个参数 'user_id'
public function author(): BelongsTo { return $this->belongsTo(User::class, 'user_id'); }

→ 来源：13 章 §2.2

7. ⭐ Local Scope 把"业务条件"集中到 Model

php

public function scopePublished(Builder $query): Builder
{
    return $query->whereNotNull('published_at')->where('published_at', '<=', now());
}

// 调用：Post::published()->paginate(10);

→ 来源：13 章 §2.2

8. ⭐ 永远 eager-load 防 N+1

php

// ❌ N+1
Post::all()->each(fn ($p) => $p->author->name);

// ✓ eager load
Post::with('author')->get()->each(fn ($p) => $p->author->name);

开发期可以全局开启检测：

php

// app/Providers/AppServiceProvider.php boot()
Model::preventLazyLoading(! $this->app->isProduction());

→ 来源：06-11 §7.5

9. `getRouteKeyName()` 让 URL 用 slug 而不是 id

php

public function getRouteKeyName(): string { return 'slug'; }

→ URL 自动变成 /posts/my-first-post，而不是 /posts/1。 → 来源：13 章 §2.2

10. 现代外键：`foreignId()->constrained()->cascadeOnDelete()`

php

$table->foreignId('user_id')
    ->constrained()
    ->cascadeOnDelete();

→ 一行 = 老语法 4 行。 → 来源：13 章 §2.1

路由 & Controller（5 条）

11. ⭐ Laravel 11+ 中间件用 `HasMiddleware` 接口

php

class PostController extends Controller implements HasMiddleware
{
    public static function middleware(): array
    {
        return [
            new Middleware('auth', except: ['index', 'show']),
        ];
    }
}

→ Laravel 10 的 __construct + $this->middleware() 被移除。 → 来源：13 章 §3.1

12. ⭐ `authorizeResource()` 与 `HasMiddleware` 不兼容 ⚠️

php

// ❌ 不工作（Laravel 11+ 加 HasMiddleware 后）
public function __construct() {
    $this->authorizeResource(Post::class, 'post');
}

// ✓ 工作 — 每方法手动 authorize
public function update(UpdatePostRequest $request, Post $post): RedirectResponse {
    $this->authorize('update', $post);
    // ...
}

→ 来源：14 章 §8

13. `Route::resource` = 7 条路由（含 create/edit）；`Route::apiResource` = 5 条（去掉 create/edit）

→ 来源：14 章 §5

14. 路由顺序：具体路由必须放在通配路由前

php

// ✓ 正确
Route::get('/posts/featured', [PostController::class, 'featured']);
Route::resource('posts', PostController::class);

// ❌ 错误：/posts/featured 永远到不了
Route::resource('posts', PostController::class);
Route::get('/posts/featured', [PostController::class, 'featured']);

→ 来源：06-11 §6.6

15. API 路由用 `Route::name('api.')` 前缀避免和 web 冲突

php

Route::name('api.')->group(function () {
    Route::apiResource('posts', PostController::class);
    // 路由名变成 api.posts.show
});

→ 来源：14 章 §3

验证、权限、安全（5 条）

16. ⭐ Form Request 同时服务 web 和 API（0 改动）

请求	Laravel 自动行为
带 `Accept: application/json` 头	失败返 JSON 422 含 `{ errors: {...} }`
普通浏览器请求	redirect back + withErrors

→ 同一段验证规则 = 两端服务。来源：14 章 §5

17. ⭐ `Rule::unique()->ignore()` 处理"编辑时唯一不撞自己"

php

// UpdatePostRequest
'slug' => [
    'required', 'string', 'max:255',
    Rule::unique('posts', 'slug')->ignore($this->route('post')),
],

→ 来源：13 章 §3.2

18. ⭐ Policy `?User` vs `User` 类型签名表达"游客可访问"

php

public function viewAny(?User $user): bool { ... }   // ?User = 允许游客
public function view(?User $user, Post $post): bool { ... }
public function create(User $user): bool { ... }      // User = 必须登录
public function update(User $user, Post $post): bool { ... }

→ 来源：13 章 §3.3

19. ⭐ Policy `before()` hook 让 admin 跨端 bypass

php

public function before(?User $user, string $ability): ?bool
{
    if ($user?->is_admin === true) return true;
    return null;  // 让具体方法继续
}

→ 不到 10 行代码让 admin 在 web/API/Filament 三端 bypass，不污染普通规则。 → 来源：16 章 §6

20. ⭐ 登录的 4 个安全细节

php

public function login(Request $request) {
    if (Auth::attempt($credentials, $request->boolean('remember'))) {
        $request->session()->regenerate();              // ① 防 session fixation
        return redirect()->intended(route('home'));     // ② 回跳原始访问页
    }
    return back()
        ->withErrors([...])
        ->onlyInput('email');                           // ③ 不回填 password
}

public function logout(Request $request) {
    Auth::logout();
    $request->session()->invalidate();                  // ④ logout 三件套之一
    $request->session()->regenerateToken();             // ④ logout 三件套之一
    // ...
}

→ 来源：13 章 §5.2

Blade & 视图（2 条）

21. `@forelse / @empty` 处理空状态

blade

@forelse ($posts as $post)
    <article>{{ $post->title }}</article>
@empty
    <p>没有文章</p>
@endforelse

→ 来源：06-11 §10.2

22. `@can` 在视图直接调 Policy

blade

@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcan

→ 不需要在 Controller 传任何东西，Blade 自动调 PostPolicy::update()。 → 来源：13 章 §4.2

队列、Job、Mail（4 条）

23. ⭐ Laravel 12 默认 `QUEUE_CONNECTION=database` 且 jobs 表已内置

→ 不需要 make:queue-table——jobs/failed_jobs 在 0001_01_01_000002_* 已经 Ran。 → 来源：15 章 §2

24. ⭐ Job 的 5 个老手细节

php

class SendXxxJob implements ShouldQueue
{
    use Queueable;             // Laravel 11+ 聚合 4 个 trait

    public int $tries = 3;     // 重试次数
    public int $backoff = 5;   // 重试间隔（秒）

    public function __construct(public Post $post) {}     // PHP 8 属性提升

    public function handle(): void { /* ... */ }

    public function failed(\Throwable $e): void {         // 钩子：tries 用完后调用
        logger()->error('XXX failed', ['post_id' => $this->post->id]);
    }
}

→ 来源：15 章 §3

25. ⭐ Markdown 邮件 + 双输出（HTML + 纯文本）

blade

<x-mail::message>
# 标题

正文内容...

<x-mail::button :url="$url">查看</x-mail::button>
</x-mail::message>

→ Laravel 自动产出 HTML 版（响应式）+ 纯文本版（兼容老客户端）。 → 来源：15 章 §3

26. ⭐ Windows + SQLite 队列锁问题的解决路径

阶段	推荐
学习/演示	`QUEUE_CONNECTION=sync`
本地开发	MySQL/PostgreSQL + database 队列
生产	MySQL/PostgreSQL + Redis 队列 + Horizon

→ SQLite 整文件级锁，Web + Worker + Tinker 任意 2 个进程同时写就会撞。 → 来源：15 章 §8

API（2 条）

27. ⭐ JsonResource 三件套：`whenLoaded` + `toIso8601String` + 衍生字段

php

return [
    'id' => $this->id,
    'published_at' => $this->published_at?->toIso8601String(),       // ISO8601
    'is_published' => $this->published_at !== null && $this->published_at->isPast(),  // 衍生
    'author' => new UserResource($this->whenLoaded('author')),       // 防 N+1
];

→ 来源：14 章 §4

28. ⭐ Sanctum Token 格式 `{id}|{plaintext}` + 撤销当前 token

php

// 颁发
$token = $user->createToken('mobile-app')->plainTextToken;

// 撤销当前（不影响其他设备）⭐
$request->user()->currentAccessToken()->delete();

→ 来源：14 章 §3

测试（2 条）

29. ⭐ `fake()` 三剑客（测试黄金法则：fake 副作用）

php

Queue::fake();    // dispatch 不真的入队
Mail::fake();     // 不真的发邮件
Bus::fake();      // dispatch chain/batch 不真的触发
Event::fake();    // event 不真的触发
Log::spy();       // 间谍模式，记录但仍透传

// 然后 assert
Queue::assertPushed(SomeJob::class);
Mail::assertSent(SomeMail::class);
Log::shouldHaveReceived('error')->withArgs(...);

→ 来源：15 章 §6 | 14 章 §7

30. ⭐ `Sanctum::actingAs($user)` 测 API 不需要先登录

php

$user = User::factory()->create();
Sanctum::actingAs($user);

getJson('/api/me')->assertOk();

→ 不需要先 POST /api/login 拿 token。 → 来源：14 章 §7

30 条到此。这些是从 8800 行笔记里萃取出来的"必背"——其他细节遇到时翻对应章节。

五、问题导航表（"我想做 X" → 看哪一篇 / 哪一节）

实战中遇到具体问题时，直接对照下表跳转。

环境与配置

我想做 X	看哪里
检查 PHP / Composer / Node 版本	03 §1
切换 Composer 镜像	03 §2.3
装 Laravel Boost	03 §4
Cursor 接入 MCP	03 §5
解决"找不到 sqlite 驱动"	03 §3.2
解决 Tinker 进程缓存陷阱	13 §2.6

数据库 / 模型

我想做 X	看哪里
加新模型 X 完整流程	06-11 §0 "改一个功能要改哪些文件"
写 Migration 字段类型	06-11 §8.1
写现代外键	06-11 §8.2
Eloquent CRUD 速查	06-11 §7.2
写 Local Scope	06-11 §7.4
防 N+1	06-11 §7.5
写 Factory 包含 state	06-11 §8.4
写幂等 Seeder	06-11 §8.6

路由 / Controller / 权限

我想做 X	看哪里
路由 7 种写法	06-11 §6.1
`Route::resource` 等价 7 路由	06-11 §6.2
路由模型绑定（按 slug）	06-11 §6.5
Resource Controller 模板	06-11 §9.1
Form Request 标准模板	06-11 §9.2
30 个验证规则速查	06-11 §9.3
Policy 7 方法模板	06-11 §11.4
Policy `before` hook	16 §6
HasMiddleware 接口（v11+）	13 §3.1

视图 / Blade

我想做 X	看哪里
24 条 Blade 语法速查	06-11 §10.1
写组件 + `@props`	06-11 §10.3
`@can` + `@error`	13 §4.2
中间件三步走	06-11 §10.6

认证

我想做 X	看哪里
认证方案选型表（Sanctum/Passport/Breeze 等）	06-11 §11.1
手写 demo 登录	13 §5
Sanctum API Token	14 §3
logout 三件套	13 §5.2

队列 / 邮件 / 异步

我想做 X	看哪里
5 种队列驱动选型	15 §2
Job 标准模板	15 §3
Mailable + Markdown 邮件	15 §3
`Queue::fake()` 测试技巧	15 §6
Job 失败 / 重试 / failed_jobs	15 §5 §7
SQLite 队列锁问题	15 §8

API

我想做 X	看哪里
Sanctum 安装 + Token 颁发	14 §2-§3
`JsonResource` 字段白名单	14 §4
API 错误响应规范化	14 §6
API 测试技巧（`Sanctum::actingAs`）	14 §7
`apiResource` vs `resource`	14 §5

Filament 后台

我想做 X	看哪里
装 Filament v5	16 §2
`FilamentUser` 接口 + `is_admin` 字段	16 §3
生成 PostResource	16 §4
状态徽章（虚拟字段）	16 §5
Policy `before` hook bypass	16 §6
v3 → v5 命名空间变化	16 §8

Boost 工具

我想做 X	看哪里
9 个工具大全	12 章
`application-info` 用法	12 §1
`database-schema` / `database-query`	12 §2-3
`tinker` 工具	12 §5
`search-docs` 查最新文档	12 §6

Prompt 工程

我想做 X	看哪里
5 大病理对照	17 §2-§6
6 个 prompt 模板	17 §8
ThinkPHP 老手专属反例	17 §7

六、Laravel 12 / 11+ 最值得记住的 10 个新特性

Laravel 11 是分水岭——大量 API 重构。这 10 个特性是最影响 ThinkPHP 老手的，同时是 AI 训练数据最容易过时的部分。

#	特性	影响	警告
1	`bootstrap/app.php` 替代 Kernel.php	中间件注册 / 异常处理 / 路由配置都在这一个文件	AI 可能仍找老 `app/Http/Kernel.php`
2	`HasMiddleware` 接口 + 静态 `middleware()`	Controller 中间件注册新方式	`__construct + $this->middleware()` 被移除
3	`casts()` 方法签名版	替代 `$casts` 属性	老代码仍能用，但新代码用方法
4	`php artisan install:api`	一键装 API（Sanctum + routes/api.php）	老教程让你手动 publish + migrate
5	`routes/api.php` 不默认创建	需要 `install:api` 才有	装 Laravel 后初次 `route:list` 没 api 路由
6	`Foundation\Queue\Queueable` 聚合 trait	替代旧 `Bus\Queueable + InteractsWithQueue + SerializesModels + Dispatchable`	use 的命名空间变了
7	`withExceptions` 注册渲染器	API 错误响应规范化的标准位置	不再写 `App\Exceptions\Handler`
8	jobs / failed_jobs migration 内置	不需要 `make:queue-table`	老教程让你 make migration
9	`?User` 类型签名表达"游客可访问"	Policy 设计可读性提升	老 Policy 是 `User`（无 ?）
10	*`expectsJson()` + `is('api/')` 自动判断响应格式**	Form Request 同时服务 web 和 API	ThinkPHP 老手会重写 API 验证（不需要）

→ 这 10 个特性是"AI 写出 v9/v10 旧代码"的最常见来源。 → 解决方案：每次让 AI 写代码前，先调 application-info 工具确认版本。详见 17 章 §4。

七、Boost 工具按使用频率排序

实测 9 个工具的"使用频率星级"——根据 13/14/15/16 章实战的真实使用次数。

TOP 5 必用工具（每天都用）⭐⭐⭐⭐⭐

#	工具	真实场景	替代方案
1	`application-info`	确认 Laravel/PHP 版本 → AI 用对 API	自己手工查 composer.json
2	`database-schema`	看现有表结构 → 写新 migration 时不用瞎猜	`php artisan db:show`
3	`search-docs`	查最新版本文档（17K+ chunks）	浏览器搜文档
4	`database-query`	验证 seed 数据、debug 业务查询	tinker（但 tinker 有缓存陷阱）
5	`tinker`	试 model / 关系 / scope 一键	启动 `php artisan tinker` 但不能并行

中频工具（每周用）⭐⭐⭐

#	工具	用途
6	`read-log-entries`	debug 队列失败 / API 报错时看最近日志
7	`last-error`	快速看最近一条 error
8	`database-connections`	多数据库时切换

低频工具（按需用）⭐⭐

#	工具	用途
9	`browser-logs` / `get-absolute-url`	浏览器测试时 debug

→ 完整工具说明 + 真实参数 / 输出 / 用例：12 章

召唤工具的 prompt 模板

开始任务前，先调以下工具确认现状：
1. application-info：项目版本和数据库类型
2. database-schema：相关表结构
3. search-docs（如果用到任何 Laravel API）：拿最新文档

任务过程中，遇到任何不确定的事实（路由是否存在、字段是否存在、配置值是多少），
直接调对应的 Boost 工具确认，不要假设。

→ 把这段加到任何 prompt 开头，AI 用工具的概率提升一截。来源：17 章 §4

八、踩坑大全（按章排序的 12 大坑）

这是教程最值钱的一节——12 个真实踩坑 + 完整诊断 + 修复路径。任何一个坑都可能让你浪费半小时到半天，所以值得提前知道。

环境层（3 个）

坑 1：腾讯云 Composer 镜像 404 ❌

现象：composer create-project 报 404 Not Found。根因：腾讯云镜像缺包同步。修复：切阿里云 → 还有问题切官方。详情：03 章 §2.3

坑 2：SQLite 驱动未启用 ❌

现象：could not find driver。根因：PHP 默认不启 sqlite3 扩展。修复：编辑 php.ini 启用 extension=pdo_sqlite + extension=sqlite3，重启。详情：03 章 §3.2

坑 3：Cursor MCP 找不到 artisan ❌

现象：MCP 服务器启动失败。根因：Cursor workspace root 与 Laravel 项目根目录不同。修复：.cursor/mcp.json 必须用绝对路径指向 artisan。详情：03 章 §5

数据层（2 个）

坑 4：Tinker 长进程缓存陷阱 ⚠️

现象：seed 后 tinker 里 User::find(1) 返回 null。根因：tinker 进程启动时已建立旧连接 / 类映射缓存。修复：重启 tinker（exit 再进）。或用 Boost 的 database-query 工具（每次新连接）。详情：13 章 §2.6

坑 5：UNIQUE 约束违反（重复 seed） ❌

现象：第二次跑 php artisan db:seed 报 UNIQUE constraint failed。根因：seeder 用 User::factory()->create([...]) 反复创建已存在邮箱。修复：用 User::firstOrCreate(...) + if ($user->wasRecentlyCreated) 幂等模式。详情：13 章 §2.5

HTTP 层（2 个）

坑 6：路由顺序错乱 ❌

现象：/posts/featured 永远到不了，被 posts/{post} 当 slug=featured 拦截。根因：Route::resource 在前，具体路由在后。修复：具体路由必须放在通配路由前。详情：06-11 §6.6

坑 7：API 路由名和 web 路由名冲突 ⚠️

现象：route('posts.show', $post) 在视图里指向不期望的 URL。根因：API 用 Route::apiResource('posts') 注册了同名路由。修复：API 用 Route::name('api.')->group(...) 加前缀。详情：14 章 §3

安全 / 权限层（1 个）

坑 8：`authorizeResource()` 与 `HasMiddleware` 不兼容 ⚠️⭐

现象：Error: Call to a member function only() on array at AuthorizesRequests.php:104。根因：authorizeResource() 内部调 $this->middleware()，但 Laravel 11+ 加 HasMiddleware 接口后该实例方法被移除。修复：每个方法手动调 $this->authorize(...)。详情：14 章 §8

AI 训练数据陈旧的最大风险——网上 90% 教程仍写 authorizeResource()。

队列层（2 个）

坑 9：Windows + SQLite + 队列锁冲突 ⚠️⭐

现象：SQLSTATE[HY000]: General error: 5 database is locked，worker FAIL。根因：SQLite 整文件级锁，Web 进程 + Worker 进程同时写就会撞。Windows 锁释放更慢。修复：开发用 QUEUE_CONNECTION=sync；生产用 MySQL/PostgreSQL + Redis 队列。详情：15 章 §4 §8

坑 10：网上教程让你 `make:queue-table` ❌

现象：php artisan make:queue-failed-table 报 ERROR Migration already exists。根因：Laravel 12 默认就内置 jobs/failed_jobs migration（0001_01_01_000002_*）。修复：什么都不用做。如果项目里已经有这两个 migration 就不需要再生成。详情：15 章 §2

第三方包层（2 个）

坑 11：Filament v3 教程已全面过时 ⚠️⭐

现象：网上教程的 use Filament\Forms\Form; 等在 v5 项目里全是 Undefined。根因：v3 → v5 跳了 2 个主版本，命名空间大量重组。修复：用 make:filament-resource Post --generate 让 Filament 自己生成 stub。详情：16 章 §8

坑 12：`composer require filament/filament:"^3.2"` 不兼容 Laravel 12 ❌

现象：requires illuminate/console ^10.0。根因：Filament v3.2 是 Laravel 10 时代的版本。修复：去掉版本约束 composer require filament/filament -W，让 Composer 自动选最新。详情：16 章 §1

元教训：12 个坑里有 5 个是"AI 训练数据陈旧"的体现（坑 8、10、11、12，加上很多 prompt 反例里出现的 v9/v10 写法）。
Boost 的 application-info + search-docs 是这类问题的预防针。详见 17 章 §4。

九、配套实战项目 playground/

教程不止是文字——playground/ 是真实可跑的项目。

项目状态摘要

playground/                                  Laravel 12.58 + PHP 8.2.9 + SQLite
├── 框架包
│   ├── laravel/framework  ^12.0
│   ├── laravel/sanctum    4.3.2
│   ├── filament/filament  5.6.2
│   ├── pestphp/pest       3.x
│   └── laravel/boost      2.4.6
│
├── 15 个数据表
│   ├── users (含 is_admin)
│   ├── posts
│   ├── personal_access_tokens (Sanctum)
│   ├── jobs / failed_jobs (队列)
│   └── ... 其他 Laravel 默认表
│
├── 业务代码（约 2200 行）
│   ├── 11 个 web 路由
│   ├── 8 个 API 路由
│   ├── 3 个 admin 后台路由
│   ├── PostController（web）
│   ├── Api\AuthController + Api\PostController（API）
│   ├── Filament\Resources\Posts\* （6 文件后台）
│   ├── Post / User Eloquent 模型
│   ├── PostPolicy（含 before hook）
│   ├── StorePostRequest / UpdatePostRequest
│   ├── PostResource / UserResource
│   ├── PostFactory / UserFactory
│   ├── DatabaseSeeder（幂等）
│   ├── SendPostPublishedEmailJob + PostPublishedMail
│   └── 5 个 Blade 视图 + 1 个邮件 Markdown 模板
│
└── 测试（共 63 个 / 189 断言）
    ├── PostListingTest        12 测试（web 公开读）
    ├── PostManagementTest     19 测试（web CRUD）
    ├── PostQueueTest           9 测试（队列 + 邮件）
    ├── Api/AuthApiTest         6 测试（API 认证）
    ├── Api/PostApiTest        12 测试（API CRUD）
    └── Admin/AdminPanelTest    5 测试（Filament 后台）

跑测试

bash

cd playground
php artisan test                    # 63 passed in 0.84s-2.79s
php artisan test --filter PostQueue # 跑特定测试

启动

bash

cd playground
php artisan serve                   # http://127.0.0.1:8000

默认测试账号

邮箱	密码	权限
`test@example.com`	`password`	admin（能登 /admin 后台）
5 个 factory 用户	`password`	普通用户（不能登后台）

默认数据

6 个用户
20 篇文章（含已发布 / 草稿 / 定时各种状态）
0 个 jobs（用 sync 队列，不入库）
0 个 personal_access_tokens（按需创建）

十、教程编写心得 + 致谢

这本教程的写作过程

这本教程的特殊之处：它不是先写后做，而是边做边写。

具体过程：

阶段	做什么	产出
1	实测 Laravel + Boost 环境搭建	03 章笔记
2	实测 Boost 9 个工具的真实用法	12 章笔记
3	实战做一个博客	13 章笔记
4	加异步邮件 → 撞 SQLite 锁 → 完整诊断修复	15 章笔记
5	API 化 → 撞 `authorizeResource` 兼容坑 → 完整诊断修复	14 章笔记
6	加 Filament 后台 → 装上 v5.6.2 而不是 v3 → 完整应对版本意外	16 章笔记
7	提炼 prompt 工程的"反例 + 模板"	17 章笔记
8	把基础章节速查整理成手册	06-11 章速查
9	把所有笔记串成"一本书"	本文档

→ 每一篇笔记都是真实做出来的，不是想象出来的。 → 每个踩坑都是真的撞过的——不是"理论上可能会出问题"。 → 每段代码都跑过测试——不是"应该能跑"。

这本教程能让 ThinkPHP 老手收获什么

3 个层次：

第一层：知识层

Laravel 12 / Filament 5 / Sanctum 4 的最新 API
7 个核心抽象（路由 / 控制器 / Eloquent / Migration / Form Request / Policy / Blade）
3 个高阶抽象（队列 / API / 后台脚手架）
ThinkPHP → Laravel 的概念对照（5 张速查表）

第二层：方法层

AI + Boost 协作的标准工作流（9 工具 + 5 大 prompt 病理 + 6 个模板）
测试驱动开发的真实体验（63 个 Pest 测试在 < 3 秒跑完）
跨章节抽象复用的实证（PostPolicy 在 web/API/Filament 三端0 改动复用）
调试链路 SOP（看 log → failed_jobs → queue:retry）

第三层：心法层

AI 训练数据陈旧的真实风险（12 个坑里 5 个来源于此）
网上教程过时的应对策略（用 make: 生成 stub 而非照抄）
版本意外的处理（Filament v3 → v5.6.2 跳 2 个主版本）
学习心态：踩坑不是浪费，是教程最值钱的部分

致谢

Laravel 团队 —— 12 年来一直引领 PHP 框架现代化方向
Filament 团队 —— v5 的 schema 体系真的优雅
Pest 团队 —— Pest 让 PHP 测试体验追上 Vitest
Cursor 团队 —— MCP + 编辑器集成让 AI 协作真的能跑
ThinkPHP 社区 —— 中国 PHP 圈的入门启蒙
被 SQLite 锁坑过的所有同行 —— 我们的痛是一致的

给读者的话

一本教程的价值不在于读完，在于让你下次写代码时多想 3 秒钟。
多想"这是 v9 的写法还是 v12 的？" 多想"这次 prompt 我有没有让 AI 调工具？" 多想"我这次的代码里有没有写测试？"
多想 3 秒钟，省 3 小时调试。

附：完整文档清单

#	文档	行数	链接
0	教程导读（本篇）	~750	你正在读的这篇
1	教程大纲	347	Laravel_Boost_教程大纲.md
2	环境搭建实测	383	03-环境搭建实测.md
3	6-11 章节速查	1485	06-11-章节速查.md
4	Boost 工具实战大全	530	12-Boost工具实战大全.md
5	博客实战完整复盘 ⭐	1279	13-博客实战完整复盘.md
6	API 化实战 ⭐	1128	14-API化实战.md
7	队列实战 ⭐	1077	15-队列实战.md
8	Filament 后台实战 ⭐	1106	16-Filament后台实战.md
9	Prompt 工程反例集	1549	17-Prompt工程反例集.md

合计：约 9600 行 / 24 万字

如果觉得这本教程有用，把它分享给身边正在从 ThinkPHP 转 Laravel 的同行 — 让他们少走半年弯路。

教程导读 · 从 0 到生产 Laravel + Boost 实战录 ​

一、本教程是什么（5 句话总览） ​

这本教程不打算做的事 ​

这本教程的特色 ​

二、教程地图（8 篇笔记如何串联） ​

全部 9 篇文档（按主题分类） ​

8 篇笔记的"故事线" ​

跨章节复用关系图（最重要的一张图） ​

三、5 条学习路径（按时间预算） ​

路径 A：5 分钟"是不是值得读" ⏱ ​

路径 B：1 小时"快速理解全貌" ⏱⏱ ​

路径 C：半天"能跟着做一遍博客" ⏱⏱⏱⏱ ​

路径 D：一天"做完整套实战" ⏱⏱⏱⏱⏱⏱⏱⏱ ​

路径 E：一周"读懂 + 复用到自己项目" ⏱ × 7 ​

四、30 个必背知识点 ​

环境与版本（4 条） ​

1. Laravel 12 要求 PHP 8.2+，PHP 8.1 不再支持 ​

2. Composer 镜像踩坑顺序：腾讯云 → 阿里云 → 官方 ​

3. 不锁版本是查"当前主流版本"的最快方式 ​

4. Cursor MCP 配置必须用绝对路径 ​

Eloquent（6 条） ​

5. ⭐ Laravel 11+ 用 casts() 方法签名版 ​

6. ⭐ 关系命名陷阱：方法名 ≠ 字段前缀必须显式传外键 ​

7. ⭐ Local Scope 把"业务条件"集中到 Model ​

8. ⭐ 永远 eager-load 防 N+1 ​

9. getRouteKeyName() 让 URL 用 slug 而不是 id ​

10. 现代外键：foreignId()->constrained()->cascadeOnDelete() ​

路由 & Controller（5 条） ​

11. ⭐ Laravel 11+ 中间件用 HasMiddleware 接口 ​

12. ⭐ authorizeResource() 与 HasMiddleware 不兼容 ⚠️ ​

13. Route::resource = 7 条路由（含 create/edit）；Route::apiResource = 5 条（去掉 create/edit） ​

14. 路由顺序：具体路由必须放在通配路由前 ​

15. API 路由用 Route::name('api.') 前缀避免和 web 冲突 ​

验证、权限、安全（5 条） ​

16. ⭐ Form Request 同时服务 web 和 API（0 改动） ​

17. ⭐ Rule::unique()->ignore() 处理"编辑时唯一不撞自己" ​

18. ⭐ Policy ?User vs User 类型签名表达"游客可访问" ​

19. ⭐ Policy before() hook 让 admin 跨端 bypass ​

20. ⭐ 登录的 4 个安全细节 ​

Blade & 视图（2 条） ​

21. @forelse / @empty 处理空状态 ​

22. @can 在视图直接调 Policy ​

队列、Job、Mail（4 条） ​

23. ⭐ Laravel 12 默认 QUEUE_CONNECTION=database 且 jobs 表已内置 ​

24. ⭐ Job 的 5 个老手细节 ​

25. ⭐ Markdown 邮件 + 双输出（HTML + 纯文本） ​

26. ⭐ Windows + SQLite 队列锁问题的解决路径 ​

API（2 条） ​

27. ⭐ JsonResource 三件套：whenLoaded + toIso8601String + 衍生字段 ​

28. ⭐ Sanctum Token 格式 {id}|{plaintext} + 撤销当前 token ​

测试（2 条） ​

29. ⭐ fake() 三剑客（测试黄金法则：fake 副作用） ​

30. ⭐ Sanctum::actingAs($user) 测 API 不需要先登录 ​

五、问题导航表（"我想做 X" → 看哪一篇 / 哪一节） ​

环境与配置 ​

数据库 / 模型 ​

路由 / Controller / 权限 ​

视图 / Blade ​

认证 ​

队列 / 邮件 / 异步 ​

API ​

Filament 后台 ​

Boost 工具 ​

Prompt 工程 ​

六、Laravel 12 / 11+ 最值得记住的 10 个新特性 ​

七、Boost 工具按使用频率排序 ​

TOP 5 必用工具（每天都用）⭐⭐⭐⭐⭐ ​

中频工具（每周用）⭐⭐⭐ ​

低频工具（按需用）⭐⭐ ​

召唤工具的 prompt 模板 ​

八、踩坑大全（按章排序的 12 大坑） ​

环境层（3 个） ​

坑 1：腾讯云 Composer 镜像 404 ❌ ​

坑 2：SQLite 驱动未启用 ❌ ​

坑 3：Cursor MCP 找不到 artisan ❌ ​

数据层（2 个） ​

坑 4：Tinker 长进程缓存陷阱 ⚠️ ​

坑 5：UNIQUE 约束违反（重复 seed） ❌ ​

HTTP 层（2 个） ​

坑 6：路由顺序错乱 ❌ ​

教程导读 · 从 0 到生产 Laravel + Boost 实战录

一、本教程是什么（5 句话总览）

这本教程不打算做的事

这本教程的特色

二、教程地图（8 篇笔记如何串联）

全部 9 篇文档（按主题分类）

8 篇笔记的"故事线"

跨章节复用关系图（最重要的一张图）

三、5 条学习路径（按时间预算）

路径 A：5 分钟"是不是值得读" ⏱

路径 B：1 小时"快速理解全貌" ⏱⏱

路径 C：半天"能跟着做一遍博客" ⏱⏱⏱⏱

路径 D：一天"做完整套实战" ⏱⏱⏱⏱⏱⏱⏱⏱

路径 E：一周"读懂 + 复用到自己项目" ⏱ × 7

四、30 个必背知识点

环境与版本（4 条）

1. Laravel 12 要求 PHP 8.2+，PHP 8.1 不再支持

2. Composer 镜像踩坑顺序：腾讯云 → 阿里云 → 官方

3. 不锁版本是查"当前主流版本"的最快方式

4. Cursor MCP 配置必须用绝对路径

Eloquent（6 条）

5. ⭐ Laravel 11+ 用 `casts()` 方法签名版

6. ⭐ 关系命名陷阱：方法名 ≠ 字段前缀必须显式传外键

7. ⭐ Local Scope 把"业务条件"集中到 Model

8. ⭐ 永远 eager-load 防 N+1

9. `getRouteKeyName()` 让 URL 用 slug 而不是 id

10. 现代外键：`foreignId()->constrained()->cascadeOnDelete()`

路由 & Controller（5 条）

11. ⭐ Laravel 11+ 中间件用 `HasMiddleware` 接口

12. ⭐ `authorizeResource()` 与 `HasMiddleware` 不兼容 ⚠️

13. `Route::resource` = 7 条路由（含 create/edit）；`Route::apiResource` = 5 条（去掉 create/edit）

14. 路由顺序：具体路由必须放在通配路由前

15. API 路由用 `Route::name('api.')` 前缀避免和 web 冲突

验证、权限、安全（5 条）

16. ⭐ Form Request 同时服务 web 和 API（0 改动）

17. ⭐ `Rule::unique()->ignore()` 处理"编辑时唯一不撞自己"

18. ⭐ Policy `?User` vs `User` 类型签名表达"游客可访问"

19. ⭐ Policy `before()` hook 让 admin 跨端 bypass

20. ⭐ 登录的 4 个安全细节

Blade & 视图（2 条）

21. `@forelse / @empty` 处理空状态

22. `@can` 在视图直接调 Policy

队列、Job、Mail（4 条）

23. ⭐ Laravel 12 默认 `QUEUE_CONNECTION=database` 且 jobs 表已内置

24. ⭐ Job 的 5 个老手细节

25. ⭐ Markdown 邮件 + 双输出（HTML + 纯文本）

26. ⭐ Windows + SQLite 队列锁问题的解决路径

API（2 条）

27. ⭐ JsonResource 三件套：`whenLoaded` + `toIso8601String` + 衍生字段

28. ⭐ Sanctum Token 格式 `{id}|{plaintext}` + 撤销当前 token

测试（2 条）

29. ⭐ `fake()` 三剑客（测试黄金法则：fake 副作用）

30. ⭐ `Sanctum::actingAs($user)` 测 API 不需要先登录

五、问题导航表（"我想做 X" → 看哪一篇 / 哪一节）

环境与配置

数据库 / 模型

路由 / Controller / 权限

视图 / Blade

认证

队列 / 邮件 / 异步

API

Filament 后台

Boost 工具

Prompt 工程

六、Laravel 12 / 11+ 最值得记住的 10 个新特性

七、Boost 工具按使用频率排序

TOP 5 必用工具（每天都用）⭐⭐⭐⭐⭐

中频工具（每周用）⭐⭐⭐

低频工具（按需用）⭐⭐

召唤工具的 prompt 模板

八、踩坑大全（按章排序的 12 大坑）

环境层（3 个）

坑 1：腾讯云 Composer 镜像 404 ❌

坑 2：SQLite 驱动未启用 ❌

坑 3：Cursor MCP 找不到 artisan ❌

数据层（2 个）

坑 4：Tinker 长进程缓存陷阱 ⚠️

坑 5：UNIQUE 约束违反（重复 seed） ❌

HTTP 层（2 个）

坑 6：路由顺序错乱 ❌