Vue.js官网怎么切换Vue 2与Vue 3版本文档？避免看错版本指南

一、核心规律：Vue 2 与 Vue 3 官方域名映射与归档现状

要想避免看错文档，最直接的手段是看清当前浏览器的地址栏。Vue 官方团队在推进 Vue 3 成为默认版本后，对整个站点的域名架构进行了长久性规划：

• Vue 3 官方文档（当前主线）：中文站为 https://cn.vuejs.org/，英文站为 https://vuejs.org/。只要域名中没有任何版本前缀，即代表当前呈现的是最新的 Vue 3 规范。
• Vue 2 官方文档（归档状态）：中文站为 https://v2.cn.vuejs.org/，英文站为 https://v2.vuejs.org/。域名最前方固定带有 v2. 前缀。

需要明确的是，Vue 2 已于 2023 年 12 月 31 日正式到达生命周期终点（EOL）。虽然官方不再推送功能更新与常规维护，但 v2.vuejs.org 文档服务器将被永久保留并向全社区开放查阅。两者属于彼此独立的静态文档系统，内容与路由组织均有显著不同。

二、官网界面切换版本的具体操作步骤

当我们在阅读文档的过程中需要临时查阅另一版本的 API 时，完全无需手动清空地址栏重新搜索，直接利用页面内置的导航控制栏即可快速切换。

1. 从 Vue 3 切换至 Vue 2 归档文档

1. 打开并停留在 Vue 3 中文主站：进入 cn.vuejs.org 任意文档页面（例如教程或 API 参考页）。
2. 定位顶部导航栏右侧的版本指示器：在桌面端界面右上角，依次排布着“文档”、“API”、“演练场”、“生态系统”等菜单，在其右侧可以找到一个标注当前 Vue 3 具体小版本的下拉按钮（例如 v3.x.x ▾）。
3. 展开下拉菜单：鼠标轻触悬停或点击该版本按钮，会弹出一个版本列表浮层。
4. 点击“Vue 2 文档”项：在下拉列表中明确选择 Vue 2 Docs（或中文标注的“Vue 2 文档”）。点击后，浏览器将直接在新标签页或当前页重定向至 v2.cn.vuejs.org。

2. 从 Vue 2 归档文档切回 Vue 3 官方文档

当读者身处 v2.cn.vuejs.org 页面时，界面顶部（或公告区域）常驻有一条黄色或浅灰色的通知横幅，提示：“你正在浏览 Vue 2 的文档。如果你想了解 Vue 3，请查看这里”。此时只需点击横幅中的超链接，或者直接将浏览器地址栏中的 v2. 字符剔除并回车，即可瞬间重返 Vue 3 文档。

三、辨析关键：3秒识别当前文档版本的 4 个显著特征

很多开发者遭遇跨版本困惑并不是因为不会切换，而是“误以为自己正在看当前项目的对应文档”。通过以下四个维度，可以帮助你在打开任何一篇 Vue 相关网页后的 3 秒内作出准确判定。

关键辨析点展开说明

其一，观察顶部的“选项式 / 组合式”开关：这是 Vue 3 官方文档最为标志性的交互设计。Vue 3 同时兼容选项式（Options API）与组合式（Composition API），文档在顶部和代码段上方都提供了实时切换按钮。如果在页面上看到了这个开关，百分之百证明你身处 Vue 3 文档。反之，Vue 2 文档绝无此类开关。

其二，观察根实例初始化代码：如果在文档的基础教程章节中，看到的是如下代码：

// Vue 2 经典创建方式
var app = new Vue({
  el: '#app',
  data: {
    message: 'Hello Vue!'
  }
})

这代表你正在查阅 Vue 2。而在 Vue 3 文档中，全局构造函数被应用实例 API 取代，代码必然呈现为：

// Vue 3 应用实例创建方式
import { createApp, ref } from 'vue'

createApp({
  setup() {
    const message = ref('Hello Vue!')
    return { message }
  }
}).mount('#app')

四、常见误看场景排查与纠偏指南

实际开发中，导致看错文档的最主要根源是搜索引擎（百度、Google 等）的旧权重收录。当我们在搜索栏输入“Vue 自定义指令”、“Vue keep-alive 缓存机制”等高频关键字时，搜索引擎常常将历史排名靠前的 Vue 2 页面推到首位。如果不加辨别直接复制其中的 API，就会在本地工程中引发一系列异常。

典型误用报错场景及修复手段

1. 在 Vue 3 项目中照搬 Vue 2 代码：

   报错现象：调用 Vue.set(target, key, value) 或 this.$set 时提示 TypeError: Vue.set is not a function；调用 this.$on 或 this.$once 时提示对应方法未定义。

   原因与纠偏：Vue 3 内部响应式重构为 ES6 Proxy，属性新增或数组索引修改均能原生自动监听，因此 Vue.set 与 $set 在 Vue 3 中已被彻底移除。同时事件总线相关 API（$on/$off）也已废弃。此时应切换至 cn.vuejs.org，按照 Vue 3 响应式基础及现代化事件通讯规范编写。

2. 在 Vue 2.6 及更早项目中照搬 Vue 3 代码：

   报错现象：在单文件组件中使用 <script setup> 模板直接报错；或从 vue 中解构 ref、reactive 提示未导出。

   原因与纠偏：旧版 Vue 2 原生并不具备组合式 API 核心运行时（除非引入了针对 Vue 2.7 的兼容层或 @vue/composition-api 插件）。在未升级老项目中，必须回到 v2.cn.vuejs.org 查阅纯正的 Options API 说明。

五、团队协作与日常开发避坑实用建议

为了在长期的开发流程中一劳永逸地解决版本看错的问题，推荐团队和个人建立以下三条工作规范：

• 独立书签分类管理：在浏览器收藏夹中分别建立 [Vue3-最新主站]（指向 https://cn.vuejs.org）与 [Vue2-旧版归档]（指向 https://v2.cn.vuejs.org），尽量通过书签直达对应专区，减少对泛用搜索引擎无序跳转的依赖。
• 团队内网文档明确标注技术栈版本：在企业内部 Wiki、代码库 README 或前端开发规范中，如果粘贴官方文档外链，务必注明版本。例如写明“请参考 [Vue 3 组合式函数规范](https://cn.vuejs.org/guide/reusability/composables.html)”，切忌只提供模糊的主页域名。
• 借助现代编辑器插件护航：安装 VS Code 官方的 Vue - Official（原 Volar）插件。当项目配置好 jsconfig.json 或 tsconfig.json 并在 package.json 明确指定 Vue 版本时，编辑器会在代码中直接高亮提示不支持的废弃方法，从源头拦截版本混淆。

六、全文总结

总结而言，Vue 官网的文档版本切换逻辑非常纯粹：默认无前缀的域名属于 Vue 3，带有 v2. 前缀的域名专属于 Vue 2。利用顶部导航栏右侧的版本下拉菜单，可以安全平滑地在两套文档之间跳转。在阅读任何章节时，只需快速看一眼 URL 结构或留意页面有无“选项式 / 组合式”切换开关，就能在数秒内确认当前文档版本，彻底规避跨版本误读带来的调试损耗。