Laravel默认不解析Accept头中的版本号，需通过中间件用正则提取并存入$request->version，fallback默认值1；路由按版本分流应动态绑定而非硬编码；响应头统一添加API-Version确保一致性。
Accept头里带版本号怎么解析
Laravel 默认不解析 Accept 头里的版本参数，比如 application/vnd.app.v1+json 这种写法，request->header('Accept') 只会原样返回字符串，不会自动提取 v1。得自己切、正则匹配，或者用中间件预处理。
推荐在中间件里做一次解析，存到 request 属性里，后续控制器直接用：$request->version。别在每个 controller 里重复写 preg_match。
- 用
preg_match('/v(\d+)/', $accept, $matches)提取数字版本，注意要加i修饰符兼容大小写 - 如果
Accept是多个值（逗号分隔），只取第一个有效类型，避免被text/html这类兜底值干扰 - 没匹配到版本时，建议 fallback 到默认值（如
1），而不是报错——客户端可能根本没传
如何让路由按版本分流
不能靠 Route::prefix('api/v{version}') 这种路径方式，因为用户明确要求用 Accept 头。得用中间件 + 路由分组动态绑定，或在控制器里 if-else 分支。
更干净的做法是：定义一个顶层路由，中间件解析出 version 后，用 Route::current()->setParameter('version', $v) 注入，再让控制器方法接收 $version 参数；或者直接用服务容器绑定不同版本的 service 实例。
- 别在路由定义里硬编码
v1、v2，否则新增版本就得改路由文件，违背 API 版本可扩展原则 - 如果用控制器方法参数自动注入，确保 route model binding 或自定义 resolver 支持从 request 取值
- 注意 Laravel 的路由缓存会忽略运行时参数，所以开发期测试没问题，上线后要清缓存再验证
响应头里怎么同步返回当前生效版本
客户端发了 Accept: application/vnd.app.v2+json，你处理完 v2 逻辑，但响应头没回显版本信息，前端调试时就很难确认到底走的是哪个分支。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
最简单是在中间件或基类控制器里统一加响应头：$response->header('API-Version', $request->version)。别只在某个 controller 里写，容易漏。
- 值必须和实际执行的逻辑一致，比如匹配到
v2但代码里写死v1，会误导调用方 - 不要用
X-API-Version这种非标准 header，优先用API-Version或 RFC 兼容的Content-Version - 如果用了 API 资源类（
JsonResource），记得在with()里也塞版本字段，否则 JSON body 里还是看不到
为什么不用 Laravel 的 Accept negotiation 机制
因为 Laravel 内置的 Request::getAcceptableContentTypes() 只用来做 MIME 类型协商（比如 json vs xml），不解析 vendor + version 后缀。它把 application/vnd.app.v1+json 当成一个完整 type，不会帮你拆 v1 出来。
强行塞进 config/app.php 的 providers 里注册自定义 mime type 也没用——Laravel 没暴露钩子让你改解析逻辑。
- 别试图重写
Request类或 patch 核心，升级 Laravel 时大概率崩 - 第三方包如
laravel-api-versioning看似省事，但多数只支持路径或 query 参数，对Accept头支持弱，且增加维护负担 - 真正麻烦的不是解析，而是版本间行为差异：比如 v1 返回
user.name，v2 改成user.full_name，这种字段映射得在资源层或 transformer 里控制，光靠 header 解析解决不了
版本控制最难的从来不是读 header，而是保持各版本接口语义稳定、错误码一致、文档可追溯。header 方式看着轻量，但一旦开始做灰度或降级，就得补上路由标记、日志打点、监控维度这些配套动作。
