Laravel API版本控制推荐使用URL路径方式，如/api/v1/users和/api/v2/users，通过路由前缀分组管理不同版本逻辑，结构清晰易维护；也可通过请求头Accept字段识别版本，保持URL干净但不利于调试；建议按版本分离控制器与服务层，复用公共逻辑并差异化处理响应数据；同时需管理版本弃用状态并在响应头中提示，配合文档工具生成各版本独立文档，确保平滑迁移。该方案兼顾可维护性与扩展性，适合多数项目需求。
Laravel 实现 API 版本控制是构建可维护、可扩展接口系统的重要环节。随着业务发展，API 需要不断迭代，而旧版本仍需支持老客户端。合理的版本化路由设计能有效隔离不同版本逻辑，避免对现有服务造成影响。
使用 URL 路径进行版本控制
这是 Laravel 中最常见且推荐的方式。将版本号嵌入 URL 路径中，例如 /api/v1/users 和 /api/v2/users，通过不同的路由文件或前缀分组管理。
在 routes/api.php 中可通过路由前缀分离版本：
// v1 版本
Route::prefix('v1')->group(function () {
Route::get('users', [V1\UserController::class, 'index']);
Route::post('users', [V1\UserController::class, 'store']);
});
// v2 版本
Route::prefix('v2')->group(function () {
Route::get('users', [V2\UserController::class, 'index']);
Route::post('users', [V2\UserController::class, 'store']);
});
这种方式结构清晰，易于理解与调试，适合大多数项目。
通过请求头识别版本
部分项目选择不在 URL 中暴露版本号，而是通过自定义请求头（如 Accept: application/vnd.myapp.v1+json）来决定调用哪个版本逻辑。
实现方式通常是在中间件中解析请求头，并根据版本信息动态绑定控制器或服务：
class ApiVersionMiddleware
{
public function handle($request, \Closure $next)
{
$version = $request->header('Accept', 'v1');
// 根据版本设置后续逻辑上下文
app()->instance('api.version', $version);
return $next($request);
}
}
该方法保持 URL 干净，但不利于直接测试和 SEO，适合内部系统或对 URL 美观要求高的场景。
控制器与服务层分离设计
为避免重复代码，建议按版本组织控制器和服务类。例如创建独立命名空间：
App/Http/Controllers/Api/V1/UserController.php App/Http/Controllers/Api/V2/UserController.php
每个版本控制器处理自身逻辑，共享模型但可拥有各自的资源类（Resource）、表单请求（FormRequest）等。若功能变化不大，也可提取通用逻辑到 BaseService 类中复用。
例如 v2 仅新增字段返回，可在资源类中差异化处理：
// V1/UserResource.php
return [
'id' => $this->id,
'name' => $this->name,
];
// V2/UserResource.php
return [
'id' => $this->id,
'name' => $this->name,
'email_verified' => $this->email_verified_at !== null,
];
版本弃用与文档管理
上线新版本后，旧版本应设置合理生命周期。可在响应头中标注弃用状态：
return response()->json($data)->header('X-API-Warn', 'This version is deprecated');
配合接口文档工具（如 Swagger / Scribe），为每个版本生成独立文档，明确标注支持状态和迁移路径。
基本上就这些。Laravel 的路由系统足够灵活，结合良好的目录结构和命名规范，API 版本控制并不复杂但容易忽略长期维护成本。选择合适策略的关键在于团队协作习惯、客户端兼容需求以及发布频率。URL 路径版本化是最直观稳妥的选择，适合绝大多数项目。
