Laravel无需“API专用模板”，标准项目通过配置即可转为纯API服务：关闭视图、禁用session、统一JSON响应，官方生态均基于此设计。
直接说结论：Laravel 不需要“新建 API 项目”，而是用 laravel new 或 composer create-project 创建标准项目，再通过配置和结构约定把它变成纯 API 服务——强行找“API 专用模板”反而容易踩坑。
为什么 Laravel 没有官方的 “API-only” 项目命令？
Laravel 从 5.5 开始就把 api 路由中间件、资源响应、无 CSRF 保护等 API 支持内建在标准安装里。所谓“API 项目”，本质是关掉视图层、禁用 session、统一返回 JSON——这些靠配置就能完成，不需要独立分支或模板。
常见错误现象：laravel new myapp --api 报错或静默忽略；用第三方“laravel-api-starter”模板，结果升级困难、中间件行为不一致、Auth 策略和标准文档对不上。
- 所有官方文档和生态工具（如 Sanctum、Passport）都默认面向标准 Laravel 项目
-
php artisan make:controller --api只是生成不带create/edit方法的骨架，不是切换项目模式 - 真正影响 API 行为的是
config/app.php中的providers和app/Http/Kernel.php中的中间件注册
怎么把标准 Laravel 项目快速转成生产级 API 服务？
重点不是“新建”，而是“裁剪+加固”。以下改动在新项目初始化后 5 分钟内就能完成：
- 删掉
resources/views目录（如果确定不用 SSR 或邮件模板） - 注释掉
App\Providers\ViewServiceProvider在config/app.php的providers数组中 - 在
app/Http/Kernel.php的$middlewareGroups['web']里移除\App\Http\Middleware\EncryptCookies::class和\Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class（API 不依赖 Cookie 加密） - 确保
routes/api.php中的路由都套在Route::middleware('api')下，且该中间件组已启用\Illuminate\Routing\Middleware\SubstituteBindings::class - 在
app/Exceptions/Handler.php的render()方法开头加判断：if ($request->expectsJson()) { return $this->prepareJsonResponse($request, $exception); }，避免 HTML 错误页泄露路径
php artisan serve 能不能跑 API？本地调试要注意什么？
能跑，但默认配置会埋雷：开发服务器不校验 CORS、不模拟真实 Nginx 的 header 传递、APP_URL 配错会导致 JWT 签名失败或 Storage URL 返回 http://localhost 而非你的前端域名。
使用场景：Postman 或 curl 测试单接口没问题；联调 Vue/React 前端时大概率跨域失败或图片链接 404。
- 本地调试务必配好
.env：APP_URL=https://api.yourapp.test（哪怕只是 hosts 绑定）、SESSION_DRIVER=cookie改成SESSION_DRIVER=none（API 不用 session） - CORS 不要依赖
fruitcake/laravel-cors的全局中间件，改用routes/api.php局部配置：Route::middleware('cors')->group(function () { ... }); - 静态资源（如上传文件）URL 必须走
Storage::url()，且config/filesystems.php中'url' => env('APP_URL').'/storage'要与前端请求域名一致
API 项目最常被忽略的兼容性点
不是路由或模型，而是时间格式、分页键名、空数组 vs null 的 JSON 序列化表现——这些在 Postman 里看着正常，到了 Flutter 或 Swift 客户端就解析失败。
-
Carbon默认序列化为 ISO-8601 字符串，但 iOSDateFormatter对T和Z的容忍度低，建议在AppServiceProvider中统一：Carbon::setToStringFormat('Y-m-d H:i:s'); - 不要依赖
LengthAwarePaginator的默认 JSON 结构，前端可能期望{ data: [], meta: { total: 10 } }，需重写toArray()或用SimplePagination+ 手动构造 - Eloquent 模型中
$casts = ['options' => 'array']遇到数据库字段为NULL时，会序列化成"null"字符串而非 JSONnull，应在 Accessor 中显式处理：return $this->attributes['options'] === null ? null : json_decode($this->attributes['options'], true);
API 的边界模糊点永远在“你以为客户端能容错”的地方——比如多一个空格、少一个引号、时间多三位毫秒，或者分页里混进了 links 数组但前端只认 next 字段。别信“它应该能解析”，信你打印出来的 json_encode($response, JSON_UNESCAPED_UNICODE) 实际输出。
