Laravel API版本控制需贯穿路由、注释、文档与测试四层面：路由用Route::prefix('v1')分组并配独立控制器；控制器方法须用@version、@deprecated等PHPDoc标注；文档页设版本对比模块说明字段与行为变更；部署/docs/v1、/docs/v2等独立入口并拆分Postman集合。
在 Laravel 文档中为 API 接口添加版本控制（如 v1、v2）的说明，核心是让开发者一眼看清路由归属、参数差异和兼容性逻辑，而不是简单在 URL 里写个 /api/v1/users 就完事。
在路由定义中显式体现版本路径
使用分组路由统一前缀，并配合注释或文档生成工具识别版本上下文：
- 在
routes/api.php中按版本分组，例如：
Route::get('/users', [UserController::class, 'index']);
});
Route::prefix('v2')->group(function () {
Route::get('/users', [UserV2Controller::class, 'index']);
});
这样结构清晰，也便于后续生成文档时自动提取版本路径。
在控制器方法上用 PHPDoc 标注版本信息
即使路由已带版本前缀，仍需在每个接口方法顶部明确声明适用版本、是否废弃、变更点：
- 使用
@version、@deprecated、@since等标准标签（支持 Swagger / Scribe / Apiato 等文档工具解析） - 示例：
* 获取用户列表（v1 版本）
* @version 1.0
* @deprecated 请使用 v2/users，该接口将于 2025-06 起停用
* @response 200 {"data": [{"id": 1, "name": "Alice"}]}
*/
public function index(Request $request) { ... }
在文档页面中增加版本对比模块
静态文档（如 Markdown 或 Scribe 生成页）可添加「版本差异」小节，避免用户反复翻页比对：
- 列出字段增删：如
v2新增last_login_at字段，移除is_active - 标注行为变化：如
v2的/users默认返回分页数据，不再支持limit/offset查询参数 - 提供迁移提示：如「从 v1 升级到 v2 需将
status参数改为state」
为不同版本维护独立的文档入口与测试沙箱
避免所有版本混在一个 Swagger UI 页面里造成混淆：
- 部署时区分文档地址，如：
/docs/v1、/docs/v2 - Postman 或 Insomnia 集合按版本拆分，命名含
[v1] User APIs - Scribe 配置中指定
routes分组，让生成器只扫描对应版本路由
不复杂但容易忽略。版本不是加个前缀就结束，而是要贯穿路由、代码注释、文档呈现和测试环境四个层面。
