API路由必须定义在routes/api.php，使用auth:sanctum中间件，显式调用response()->json()，并确保APP_URL与SANCTUM_STATEFUL_DOMAINS一致。
routes/api.php 是唯一入口，别往 web.php 里塞 API 路由
API 路由必须定义在 routes/api.php，Laravel 会自动加前缀 /api 并启用无 Session、无 CSRF 的状态less中间件。往 routes/web.php 里写 Route::get('/api/users', ...) 看似能跑，但实际会走 session 启动、触发 CSRF 验证，前端调用直接 419；更隐蔽的是，它还会污染缓存路由列表，php artisan route:cache 后可能彻底失效。
实操建议：
- 所有 API 路由只进
routes/api.php，哪怕只是临时调试 - 如果需要自定义前缀（比如
/v1），用路由分组：Route::prefix('v1')->group(...) - 别依赖“路径带 /api 就是 API”这种直觉——Laravel 只认文件位置和中间件绑定
用 api middleware 组，而不是 auth:api
auth:api 是 Laravel 自带的守卫别名，但它默认绑定的是 token 认证（即 TokenGuard），而 Laravel 9+ 已弃用 token 字段，改用 Sanctum 或 Passport。直接写 ->middleware('auth:api') 很容易报错 Call to undefined method Illuminate\Auth\RequestGuard::user()——因为底层 guard 实例根本没 user() 方法。
实操建议：
- 新项目一律用
->middleware('auth:sanctum')（配合 laravel/sanctum）或->middleware('auth:passport')（配合 laravel/passport） - 如果只是测试，先确保
config/auth.php中'defaults' => ['guard' => 'api']指向的是你实际配置的 guard - 别跳过
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"，否则auth:sanctum中间件不生效
返回 JSON 必须显式调用 response()->json() 或 return [...]
Laravel 控制器方法返回数组（如 return ['data' => $users];）时，框架会自动转 JSON，但前提是请求头包含 Accept: application/json。浏览器直接访问 /api/users 时，Accept 头通常是 text/html，结果返回 HTML 错误页或重定向，你以为接口挂了，其实是格式协商失败。
实操建议：
- 开发阶段统一用
response()->json([...])，绕过内容协商逻辑 - Postman 或前端调用时，务必手动加
Accept: application/json请求头 - 不要依赖“返回数组就一定是 JSON”——这是 Laravel 的隐式行为，不是契约
APP_URL 和 SANCTUM_STATEFUL_DOMAIN 必须对齐，否则 Cookie 认证失败
用 Sanctum 做 SPA 认证时，前端发请求带 Cookie，后端却收不到 XSRF-TOKEN 或 laravel_session，常见原因是 APP_URL（.env）和 SANCTUM_STATEFUL_DOMAINS（config/sanctum.php）不一致。比如前端跑在 http://localhost:5173，但 SANCTUM_STATEFUL_DOMAINS 写成 localhost，Chrome 会拒绝发送 Cookie（跨域限制）。
实操建议：
- 本地开发：设
APP_URL=http://localhost:8000，SANCTUM_STATEFUL_DOMAINS=localhost,localhost:5173 - 生产环境：填域名（不含协议），如
example.com,www.example.com，不能带https:// - 改完记得
php artisan config:clear，否则缓存旧配置
API 不是把 web 路由换个路径就能用，中间件链、响应格式、认证上下文、Cookie 域名策略，每个点都卡得死死的。漏掉任意一个，前端就收不到数据，但控制台还显示 200 —— 这种静默失败最耗时间。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
