Laravel API路由必须写在routes/api.php并配auth:sanctum中间件，用JsonResource封装响应，否则易遇419、404、空响应及跨域失败；web.php中定义API路由会因session/CSRF中间件导致认证异常，且route:cache后更难调试。
直接说结论：Laravel 不需要“新建 API 项目”，所有 API 路由必须写在 routes/api.php，配 auth:sanctum 中间件，返回数据用 JsonResource 封装，否则大概率踩 419、404、空响应、跨域失败这些坑。
API 路由为什么不能写在 web.php 里
写在 routes/web.php 的路由默认走 web 中间件组，会强制启用 StartSession 和 VerifyCsrfToken。API 请求不带 cookie 或 CSRF token，结果就是 419 Page Expired —— 你以为是认证问题，其实是进错了中间件组。
更隐蔽的问题：php artisan route:cache 后，web.php 里的 /api/users 路由可能被缓存成带 session 的版本，彻底无法响应前端请求。
-
routes/api.php是唯一合法入口，Laravel 会自动加/api前缀，并绑定api中间件组（无 session、无 CSRF、自动 JSON 响应） - 要加版本号，用
Route::prefix('v1')->group()，别往 URL query 里塞?v=2 - 别信“路径含 /api 就是 API”——Laravel 只认文件位置和中间件绑定
auth:api 和 auth:sanctum 到底用哪个
auth:api 是 Laravel 自带的守卫别名，但它默认绑的是已弃用的 TokenGuard。Laravel 9+ 移除了 token 字段，直接写 ->middleware('auth:api') 会报错：Call to undefined method Illuminate\Auth\RequestGuard::user()。
新项目必须用 auth:sanctum（配合 laravel/sanctum）或 auth:passport（配合 laravel/passport）。
- 没运行过
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"？中间件根本不会生效 - 临时调试可注释掉
auth:sanctum，但上线前必须补上，且确保config/auth.php中'defaults' => ['guard' => 'api']指向的是你实际配置的 guard - 别手动给 API 路由加
VerifyCsrfToken—— 它本不该出现在api组里
返回 JSON 为什么有时是 HTML、有时是空响应
浏览器直接访问 /api/users，Accept 请求头默认是 text/html，Laravel 就当你是 Web 请求，返回重定向或 HTML 错误页。你以为接口挂了，其实是内容协商失败。
控制器里写 return $user; 看似简洁，但遇到循环引用（比如模型里有闭包关系）会直接抛出 Serialization of 'Closure' is not allowed；而 return response()->json($user) 能绕过序列化陷阱，还能显式设状态码。
- 开发阶段统一用
response()->json()，别依赖隐式转换 - Postman 或前端调用时，必须手动加
Accept: application/json头 - 验证失败返回 422？前提是请求头有
Accept: application/json，否则 Laravel 会重定向回上一页
JsonResource 不只是“套一层”，它解决三个真实问题
直接 return $post; 会触发 Eloquent 默认序列化，忽略 $hidden、$casts、日期格式等配置；更糟的是，toArray() 里如果写 $this->user->name，没预加载就会 N+1；如果写业务逻辑（比如判断是否收藏），会导致同一模型在不同接口返回结构不一致。
JsonResource 是响应层的“视图”，只做字段映射，不做查询、不放 if-else。
- 控制器里必须预加载：
Post::with('user:id,name')->findOrFail($id) - Resource 的
toArray()里只写字段提取：'user' => new UserResource($this->whenLoaded('user'))，别调$this->user->profile - 集合要用
UserResource::collection($users)，不是collect($users)->map(...)
最常被忽略的一点：APP_URL 和 SANCTUM_STATEFUL_DOMAINS 必须完全一致，否则 Cookie 认证连 XSRF-TOKEN 都收不到。本地开发用 http://localhost:3000，后端 APP_URL 却配成 http://127.0.0.1:8000，前端发请求就永远拿不到有效 Cookie。
