Laravel API版本控制应通过路由前缀、命名空间和中间件实现路径隔离，而非Accept头；v2可复用v1服务类与模型，但需独立控制器和Resource类，避免跨版本共享。
在 Laravel 中，API 版本控制不靠第三方包也能做得清晰可控——核心是用路由分组隔离版本逻辑，配合命名空间与中间件约束访问边界。
如何用 Route::prefix() + middleware 定义版本入口
别把版本号硬编码进每个控制器方法里。直接在路由定义层做隔离：
-
prefix统一加v1或api/v2，让 URL 路径天然体现版本 - 必须绑定
api中间件组（含throttle、auth:sanctum等），避免 v1 路由意外走 web 中间件 - 显式指定
namespace，例如App\Http\Controllers\V1，防止控制器混用
Route::prefix('api/v1')->middleware(['api'])->namespace('App\Http\Controllers\V1')->group(function () {
Route::get('/users', [UserController::class, 'index']);
Route::post('/posts', [PostController::class, 'store']);
});
为什么不能只靠 Accept 头做版本识别
HTTP Accept 头（如 application/vnd.app.v1+json）看似优雅，但实际落地问题多：
- 前端调用时容易漏设 header，尤其在 Swagger、curl、Postman 测试阶段
- CDN、反向代理（如 Nginx）可能过滤或改写 header，导致版本路由匹配失败
- Laravel 的路由匹配优先级中，URL 路径权重远高于 request header，强行用
Accept会绕过路由缓存机制，影响性能 - 调试时
php artisan route:list看不到版本区分，可维护性下降
如何让 v2 兼容部分 v1 接口而不重复写逻辑
不是所有接口都需要重写。常见做法是复用模型和资源类，但控制器层保持独立：
- v2 控制器可直接调用 v1 的 service 类（如
App\Services\V1\UserService），只要契约没变 - 响应格式升级时，用不同
Resource类：v1 用UserResource，v2 改用UserV2Resource - 若 v2 新增字段但旧客户端不能崩，不要删 v1 的字段；而是让 v1 Resource 显式
only字段，v2 Resource 再扩展 - 禁止跨版本共享控制器——哪怕只改一行，也应新建控制器，否则
git blame和权限控制都会混乱
容易被忽略的陷阱：中间件顺序与路由缓存
版本路由一旦上线，php artisan route:cache 就成了刚需，但这里有两个关键点：
- 自定义版本中间件（如
EnsureApiVersion）必须放在api组内，且不能依赖Request的未解析属性（比如在中间件里读$request->route()前，确保路由已匹配） - 如果用了
Route::domain()配合版本（如v2.api.example.com），要确认APP_URL和生成 URL 的辅助函数（如route()）是否配置了url或asset_url - 测试时用
php artisan serve默认不支持多子域，本地验证域名版需配valet或修改 hosts + Nginx
真正的难点不在怎么写路由，而在于每次新增 v3 时，能否快速判断哪些接口该废弃、哪些要迁移、哪些得保留兼容——这取决于你从 v1 就坚持的控制器职责分离和资源类封装粒度。
