URL路径嵌入版本号（如/v1/user/info）最稳妥，需响应体显式返回version字段、数据库变更兼容旧版、小程序端配合渐进升级并监控各版本失败率。
用 URL 路径做版本标识最稳妥
小程序接口的版本控制，首选在 URL 路径里嵌入版本号，比如 /v1/user/info、/v2/user/info。这样客户端明确知道调哪个版本，nginx 或 apache 也能按路径做路由、限流、灰度，php 后端也无需在逻辑里反复判断版本字段。
不推荐把版本塞进请求头（如 X-API-Version: v2）或参数（如 ?version=v2），前者容易被忽略或覆盖，后者可能被缓存、日志误记、CDN 透传异常。
- 路由层就该分发到对应控制器，例如 laravel 中用
Route::prefix('v1')->group(...)，thinkphp 用route.php配置'v1/user/info' => 'api/v1.User/info' - 不要让同一个控制器方法通过
if ($version === 'v2') { ... }分支处理多版本逻辑——耦合高、难测试、易漏修 - 版本号建议用
v1、v2这种整数形式，避免v1.2.3带来语义混淆和路由匹配麻烦
接口响应里必须带 version 字段
即使 URL 已含版本，也要在 jsON 响应体里显式返回 "version": "v2"。这不是冗余，而是给前端、运维、监控留出可验证依据——比如某次上线后发现小程序实际调的是 /v1 接口，但响应里却写了 "version": "v2"，立刻能定位是反向代理配置错了。
这个字段必须由服务端写死，不能从请求中读取或拼接；否则容易被伪造或遗漏。
立即学习“PHP免费学习笔记（深入）”；
- 统一在基类响应方法里注入，例如
return $this->success(['data' => $data], 200, ['version' => 'v2']) - 避免在每个接口里手动加
'version' => 'v2'，容易漏、难维护 - 如果用了 API 文档工具（如 Swagger），记得同步更新
version字段的描述和示例值
数据库变更必须兼容旧版接口
接口升级时，数据库结构往往要改，但 /v1 接口还在运行，不能直接删字段、改类型或加非空约束。必须保证老版本接口的数据读写不受影响。
常见做法是：新增字段（如 user_status_v2）、保留旧字段（user_status）、用视图或中间层做映射，而不是靠 PHP 层 if-else 补丁式兼容。
- 加新字段时设默认值，避免
INSERT报错；改字段类型前先确认/v1是否还依赖原格式（比如 int 改成 VARCHAR 可能导致 json 序列化差异） - 删除字段前，至少等所有调用
/v1的小程序版本下线完毕，并在监控里确认该接口调用量归零 - 用 migration 工具管理变更，每条记录标注影响的接口版本范围，例如
// affects: v1, v2
别忘了小程序端的版本兼容策略
PHP 接口可以多版本并存，但小程序代码本身没有“自动降级”机制。如果 /v2 接口返回了新字段，而老版小程序没处理，可能直接白屏或报 JS 错误。
所以后端不能只管“能跑”，还要配合前端做渐进式升级：新字段加 NULLable、旧字段暂不废弃、关键结构变动提供双字段过渡期（如同时返回 avatar 和 avatar_url）。
- 接口文档里明确标注字段的生效版本，例如
"avatar_url": {"since": "v2", "deprecated_in": null} - 监控里单独埋点统计各版本接口的失败率，特别关注
JSON.parse异常或字段 undefined 报错，这些往往是前端未适配新结构的信号 - 灰度发布时，用小程序
version+channel参数控制后端分流，而不是只靠接口路径
接口版本不是加个前缀就完事，真正的难点在于数据层与客户端行为的长期共存。一个字段的废弃，往往比新增更耗精力。