diff --git a/demo/pages/docs/common-issues/enUS/index.md b/demo/pages/docs/common-issues/enUS/index.md
index 4fc194a59..0685b827e 100644
--- a/demo/pages/docs/common-issues/enUS/index.md
+++ b/demo/pages/docs/common-issues/enUS/index.md
@@ -2,7 +2,9 @@
 
 ## 1. The difference between @update:xxx and on-update:xxx
 
-There is no difference between `@update:xxx` and `on-update:xxx` when used in templates.
+### Case 1
+
+If you are not using `v-model:xxx` with `on-update:xxx` on the same component, there is no difference between `@update:xxx` and `on-update:xxx` when used in templates.
 
 In Naive UI, all API documents use the `on-update:xxx` format, because `@` is just a shorthand provided by Vue.
 
@@ -10,4 +12,16 @@ If you prefer camelCase, you can use `onUpdate:xxx`.
 
 If you are using JSX, you can use `onUpdateXxx` (all `onUpdate:xxx` have an equivalent implementation of `onUpdateXxx`).
 
+### Case 2
+
+If you are using `v-model:xxx`, you should use `@update:xxx` on the same component.
+
+✅ example `<n-input v-model:value="xxx" @update:value="yyy" />`.
+
+❌ example `<n-input v-model:value="xxx" :on-update:value="yyy" />`.
+
+That is because `v-model:value="xxx"` will be transformed to `:onUpdate:value="xxx"`. If you are using `@update:value="yyy"` together, it will be `:onUpdate:value="[xxx, yyy]"`, and then Naive UI would take care of if.
+
+However if you are using `on-update:value="yyy"`, Vue would generate code like `:onUpdate:value="xxx" :on-update-value="yyy"` and the second one would override the first one in Vue runtime. The `v-model:value` would be broken.
+
 If you have any problem, feel free to create a PR or issue on GitHub.
diff --git a/demo/pages/docs/common-issues/zhCN/index.md b/demo/pages/docs/common-issues/zhCN/index.md
index ed22dec9c..94a94eedb 100644
--- a/demo/pages/docs/common-issues/zhCN/index.md
+++ b/demo/pages/docs/common-issues/zhCN/index.md
@@ -2,7 +2,9 @@
 
 ## 1. @update:xxx 和 on-update:xxx 的区别
 
-`@update:xxx` 和 `on-update:xxx` 在模版中使用时没有任何区别。
+### 情况 1
+
+如果你没有在同一个组件上同时使用 `v-model:xxx` 和 `on-update:xxx`，`@update:xxx` 和 `on-update:xxx` 在模版中使用时没有任何区别。
 
 在 Naive UI 中，全部的 API 文档使用 `on-update:xxx` 格式，因为 `@` 只是 Vue 提供的一种简写。
 
@@ -10,4 +12,16 @@
 
 如果你在使用 JSX，可以使用 `onUpdateXxx`（所有的 `onUpdate:xxx` 都有一个 `onUpdateXxx` 的对等实现）。
 
+### 情况 2
+
+如果你在一个组件上使用了 `v-model:xxx`，你应该使用 `@update:xxx`。
+
+✅ 例子 `<n-input v-model:value="xxx" @update:value="yyy" />`。
+
+❌ 例子 `<n-input v-model:value="xxx" :on-update:value="yyy" />`。
+
+这是因为 `v-model:value="xxx"` 会被转化为 `:onUpdate:value="xxx"`。如果你同时使用了 `@update:value="yyy"`，他们会被转化为 `:onUpdate:value="[xxx, yyy]"`，然后 Naive UI 会来处理这种情况。
+
+然是如果你使用了 `on-update:value="yyy"`，Vue 会生成类似于 `:onUpdate:value="xxx" :on-update-value="yyy"` 的代码，然后第二个属性会在运行时覆盖掉第一个，`v-model:value` 会崩掉。
+
 如果你发现任何问题，欢迎在 GitHub 上提交 issue 和 PR。