API 版本化文档的 SEO 处理：旧版该留还是该删

接口升版本时，旧文档别急着删。2025 年 5 月我们帮一个短信 API 做 v1 到 v2 的迁移，他们原计划把 v1 文档整体下架，我们拦住了。到 9 月，v1 文档每月还带来 1800 多次自然访问，占文档站总流量的 21%，那些用户还在用旧接口，或者正在从别家迁移过来。

旧文档的三个真实价值

第一，存量用户会搜。接口不会一夜之间换完，大客户的迁移周期经常是 12 到 18 个月。把文档删掉，他们会去搜缓存页或者第三方教程，你失去的是接触点。

第二，长尾词还在旧页面里。老接口的名字、参数名、报错信息，这些词搜索引擎已经认了旧 URL。页面一删，排名掉得很快，重新做回来要三到六个月。

第三，迁移指南需要一个落点。旧文档页顶部放一条“本版本已停止维护，迁移到 v2 看这里”，这是最自然的迁移入口，比发邮件有效。

怎么处理才不出重复内容

我们的做法分三步。第一步，旧版文档保留独立目录，路径里带版本号，比如 /docs/v1/，新版是 /docs/v2/。第二步，旧版每页顶部加一条醒目提示，写清停止支持的时间和迁移链接。第三步，canonical 指向自己，不要指向新版——这两页内容不同，指向新版会让搜索引擎把旧页丢掉。

真正要合并的是“同名不同版”的重复页。比如参数说明页在两版里几乎一样，就把旧版那页设成 noindex，只保留入口页和差异页。这个边界我们一般按改动幅度定：参数变了超过三成，独立页；不到三成，合并加版本标注。

版本号要不要进 title

要。用户搜“短信 API v2 发送”和“短信 API 发送”，是两个意图。title 里带版本号，点击率会高，也避免了用户点进去发现版本不对。

还有一个小技巧：在旧版页面底部列出“本版和 v2 的差异”，用表格，五行以内。这张表经常被第三方博客转引，带外链回来。

什么时候可以删

两种情况可以删。一是旧版停止支持超过 24 个月，且月访问低于 100，先做 301 到新版对应页，观察一个季度。二是旧版从来没被索引过，那删了也没损失。

最后一句：版本迁移期至少留 6 个月的并行文档，别在发版当天就切。用户迁移是跟着自己的迭代节奏走的，不是你发公告的节奏。

判断这件事别拍脑袋，看 Search Console 里那些 URL 的展示和点击，数据会告诉你答案。我们现在的默认动作是：先留，加提示，设 canonical，半年后再看数据决定。删文档是不可逆的，留文档的成本只是几十个页面的维护。