做前后端对接的时候，经常遇到API改了，前端调用突然就报错的情况。比如昨天还好好的用户信息接口，今天返回的字段少了一个，前端页面直接显示NaN。这时候就会有人问：API设计到底该不该带版本号？
版本号不是万能钥匙
很多人一听说API要更新，第一反应就是加个v1、v2。但其实不是所有改动都需要升版本。比如修复一个返回时间格式错误的问题，把"2024-01-01T00:00"改成标准ISO格式，这种兼容性调整，完全可以在不升级版本的情况下完成。
就像你家楼下便利店，今天换了新收银系统，但你拿会员卡积分还是照常，没必要通知所有人"我们升级到V2.0服务了"。
什么时候非加不可？
当接口结构发生断裂性变化时，版本号就变得重要了。比如原来查订单返回的是数组，现在改成对象包裹，里面带分页信息。这时候老前端代码直接解析会出错，就必须通过版本区分。
常见的做法是在URL里带上版本：
https://api.example.com/v1/orders
https://api.example.com/v2/orders或者用请求头控制：
Accept: application/json; version=1.0浏览器缓存带来的现实问题
前端最头疼的其实是浏览器缓存。用户手机里还存着旧版JS文件，调的是v1接口，等你把服务器上的默认版本悄悄切换到v2，这些人就打不开页面了。所以即使用了版本号，也得留足过渡期，不能说下线就下线。
有些团队会同时维护两个版本几周，监控日志里老版本的调用量，等降到一定比例再关掉。这就像地铁换乘通道，新线路通了，旧楼梯也不会立马封上。
不加版本怎么保证稳定？
也不是所有系统都靠版本号活着。有些内部微服务之间约定“只能新增字段，不能删改”，这样即使不升版本，也能做到向前兼容。前端拿到数据发现多了一个newBadge字段，不认识就忽略，不影响原有逻辑。
但这种默契在跨公司对接时风险很高。你永远不知道对方会不会哪天突然删掉某个字段，所以对外API更需要明确的版本边界。
说到底，加不加版本号，关键看谁在用。自己团队小步快跑，可以灵活处理；面向外部开发者，还是明明白白标出来更稳妥。