500错误无日志需先开启APP_DEBUG=true并清缓存，再检查logging.php中channel配置及日志写入；apiResource 404需确认中间件、路由前缀与加载路径；419错误要区分CSRF与Bearer Token认证场景；N+1问题须在Eloquent查询中正确使用with预加载。
500 错误没日志？先确认 APP_DEBUG 和日志通道
Laravel API 返回 500 却看不到具体错误，大概率是 APP_DEBUG=false 下静默失败。生产环境关掉调试是常态，但排查时必须临时打开——改 .env 文件里的 APP_DEBUG=true，再清缓存：php artisan config:clear。注意：别在正式服务器长期开着，改完立刻关。
另一个常见盲区是日志写入失败。检查 config/logging.php 中默认 channel 是否为 stack，底层是否指向 daily 或 stderr；如果用了 papertrail 或 slack 等远程驱动，本地查不到日志纯属正常。快速验证方式：手动触发一条日志：Log::error('test from api');，然后看 storage/logs/laravel.log 里有没有。
Route::apiResource 404 但路由存在？检查中间件和前缀
用 Route::apiResource('posts', PostController::class) 写了路由，php artisan route:list 也显示了，但请求 /api/posts 还是 404，问题往往不在路由注册本身，而在中间件或 URL 前缀上。
- 确认该路由是否被
api中间件组包裹（routes/api.php默认有），否则throttle、auth:sanctum等可能提前终止请求，且不报错只返回 404 - 检查
RouteServiceProvider里mapApiRoutes()是否真的加载了routes/api.php（有些项目删了这行或改了路径） - API 路由默认带
/api/前缀，但如果你在RouteServiceProvider里改过prefix，或用了Route::prefix('v1')嵌套，实际路径可能是/api/v1/posts，别漏掉
Postman 测试 419？sanctum 的 CSRF 和 token 机制要分清
前端发 POST 请求到 Laravel API 报 419（CSRF token mismatch），但用 Postman 直接调却成功——这不是后端 bug，而是混淆了两种认证场景：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- Web 页面（含 SPA）走的是
web中间件，依赖 Cookie + CSRF Token，必须在请求头带X-XSRF-TOKEN，且服务端需启用EnsureFrontendRequestsAreStateful - 纯 API 调用（如移动端、Postman）应走
api中间件，用auth:sanctum配合 Bearer Token，完全绕过 CSRF - 检查
app/Http/Kernel.php中api组是否包含throttle:api但漏掉了auth:sanctum，导致未认证直接拒
简单验证：用 Postman 发 GET /api/user，Header 加 Authorization: Bearer {your-token}，如果成功，说明 Sanctum 正常；失败则重点查 config/sanctum.php 的 stateful 域名配置是否匹配当前请求来源。
数据库查询慢得离谱？别急着优化 SQL，先看 N+1 和 with 加载时机
API 接口响应从 200ms 突然涨到 3s，DB::enableQueryLog() 查出来十几条重复的 select * from users where id = ? —— 典型 N+1。但很多人只记得加 with('author')，却忽略了它只对 Eloquent 模型生效，对 DB::table() 或原生查询无效。
-
with()必须在最终执行前调用，比如Post::with('user')->get()有效，但$posts = Post::get(); $posts->load('user')是懒加载，仍可能触发 N+1 - 如果控制器里用了
Resource类，确保在 Resource 的toArray()里没偷偷访问未预加载的关系属性（如$this->user->name） - 使用
toSql()检查生成的语句：Post::with('user')->toSql()是单条 JOIN 查询，而Post::get()->map(...)里访问$post->user就是多条独立查询
真正卡住的往往不是单条慢查询，而是几十次毫秒级查询堆出来的延迟。开 DB::listen() 打印所有 SQL，在开发环境一眼就能定位。
