diff --git a/docs/markdown/changelog-v3.zh-CN.md b/docs/markdown/changelog-v3.zh-CN.md
index a8ad58788..fd67f5cad 100644
--- a/docs/markdown/changelog-v3.zh-CN.md
+++ b/docs/markdown/changelog-v3.zh-CN.md
@@ -17,99 +17,3 @@ Vant 遵循 [Semver](https://semver.org/lang/zh-CN/) 语义化版本规范。
### v3.0.0-alpha.0
`TODO`
-
-#### 不兼容更新
-
-##### v-model API 变更
-
-为了适配 Vue 3 的 v-model API 用法变更，所有提供 v-model 属性的组件在用法上有一定调整。
-
-以下组件的 `v-model` 被重命名为 `v-model:show`：
-
-- ActionSheet
-- Calendar
-- Dialog
-- ImagePreview
-- Notify
-- Popup
-- ShareSheet
-
-```html
-
-
-
-
-```
-
-以下组件 v-model 对应的 prop 重命名为 `modelValue`，event 重命名为 `update:modelValue`：
-
-- Checkbox
-- CheckboxGroup
-- DatetimePicker
-- DropdownItem
-- Field
-- Radio
-- RadioGroup
-- Search
-- Stepper
-- Switch
-- Sidebar
-- Uploader
-
-```html
-
-
-
-
-```
-
-其他改动：
-
-- Circle: `v-model` 重命名为 `v-model:currentRate`
-- CouponList: `v-model` 重命名为 `v-model:code`
-- List: `v-model` 重命名为 `v-model:loading`，`error.sync` 重命名为 `v-model:error`
-- Tabs: `v-model` 重命名为 `v-model:active`
-- TreeSelect: `active-id.sync` 重命名为 `v-model:active-id`
-- TreeSelect: `main-active-index.sync` 重命名为 `v-model:main-active-index`
-
-##### 组件命名调整
-
-- GoodsAction：重命名为 `ActionBar`
-- GoodsActionIcon：重命名为 `ActionBarIcon`
-- GoodsActionButton：重命名为 `ActionBarButton`
-
-##### API 命名调整
-
-以下改动是为了规范 API 命名：
-
-- SwipeCell: `open` 事件的 `detail` 参数重命名为 `name`
-- SwipeCell: `on-close` 属性重命名为 `before-close`，并调整参数结构
-- Toast: `mask` 属性重命名为 `overlay`
-- TreeSelect: `navclick` 事件重命名为 `click-nav`
-- TreeSelect: `itemclick` 事件重命名为 `click-item`
-
-##### 徽标属性命名调整
-
-在之前的版本中，我们通过 info 属性来展示图标右上角的徽标信息，为了更符合社区的命名习惯，我们将这个属性重命名为 badge，影响以下组件：
-
-- Tab
-- Icon
-- GridItem
-- TreeSelect
-- TabbarItem
-- SidebarItem
-- GoodsActionIcon
-
-同时内部使用的 Info 组件也会重命名为 Badge。
-
-##### 废弃组件
-
-- SwitchCell: 移除此组件，可以直接使用 Cell 和 Switch 组件代替
-
-```html
-
-
-
-
-
-```
diff --git a/docs/markdown/migrate-from-v2.zh-CN.md b/docs/markdown/migrate-from-v2.zh-CN.md
new file mode 100644
index 000000000..0ab8380d2
--- /dev/null
+++ b/docs/markdown/migrate-from-v2.zh-CN.md
@@ -0,0 +1,115 @@
+# 从 2.x 版本迁移
+
+## 不兼容更新
+
+### 组件命名调整
+
+GoodsAction 商品导航组件重命名为 **ActionBar 行动栏**。
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### 废弃组件
+
+移除 SwitchCell 组件，可以直接使用 Cell 和 Switch 组件代替。
+
+```html
+
+
+
+
+
+
+
+
+
+```
+
+### 弹窗型组件 v-model 变更
+
+为了适配 Vue 3 的 v-model API 用法变更，所有提供 v-model 属性的组件在用法上有一定调整。
+
+以下弹窗类组件的 `v-model` 被重命名为 `v-model:show`：
+
+- ActionSheet
+- Calendar
+- Dialog
+- ImagePreview
+- Notify
+- Popup
+- ShareSheet
+
+```html
+
+
+
+
+```
+
+### 表单型组件 v-model 内部值变更
+
+以下表单型组件 v-model 对应的 prop 重命名为 `modelValue`，event 重命名为 `update:modelValue`：
+
+- Checkbox
+- CheckboxGroup
+- DatetimePicker
+- DropdownItem
+- Field
+- Radio
+- RadioGroup
+- Search
+- Stepper
+- Switch
+- Sidebar
+- Uploader
+
+```html
+
+
+
+
+```
+
+### 其他组件 v-model 调整
+
+- Circle: `v-model` 重命名为 `v-model:currentRate`
+- CouponList: `v-model` 重命名为 `v-model:code`
+- List: `v-model` 重命名为 `v-model:loading`，`error.sync` 重命名为 `v-model:error`
+- Tabs: `v-model` 重命名为 `v-model:active`
+- TreeSelect: `active-id.sync` 重命名为 `v-model:active-id`
+- TreeSelect: `main-active-index.sync` 重命名为 `v-model:main-active-index`
+
+### API 命名调整
+
+以下改动是为了规范 API 命名：
+
+- SwipeCell: `open` 事件的 `detail` 参数重命名为 `name`
+- SwipeCell: `on-close` 属性重命名为 `before-close`，并调整参数结构
+- Toast: `mask` 属性重命名为 `overlay`
+- TreeSelect: `navclick` 事件重命名为 `click-nav`
+- TreeSelect: `itemclick` 事件重命名为 `click-item`
+
+### 徽标属性命名调整
+
+在之前的版本中，我们通过 info 属性来展示图标右上角的徽标信息，为了更符合社区的命名习惯，我们将这个属性重命名为 badge，影响以下组件：
+
+- Tab
+- Icon
+- GridItem
+- TreeSelect
+- TabbarItem
+- SidebarItem
+- GoodsActionIcon
+
+同时内部使用的 Info 组件也会重命名为 Badge。
diff --git a/vant.config.js b/vant.config.js
index 8b99d25b9..41c2db234 100644
--- a/vant.config.js
+++ b/vant.config.js
@@ -53,6 +53,10 @@ module.exports = {
path: 'changelog-v3',
title: '更新日志',
},
+ {
+ path: 'migrate-from-v2',
+ title: '从 2.x 版本迁移',
+ },
{
path: 'theme',
title: '定制主题',