Vue3 + Element-Plus 项目避坑指南：从报错到解决，这些易错点一定要注意！

Z2902485029

326人浏览 · 2026-05-24 11:07:17

Z2902485029 · 2026-05-24 11:07:17 发布

大家好，我是正在做 Vue3 大事件项目，最近在实现文章管理模块时踩了一堆坑，从页面白屏到功能失效，几乎把常见的 Vue3 开发错误都踩了一遍。今天把这些错误和解决方案整理出来，给正在做同类项目的小伙伴避避坑，希望能帮你少走弯路！

一、组件通信与 Ref 调用错误：弹窗打不开的元凶

错误现象

点击 “添加文章 / 编辑” 按钮无反应，控制台报错 articleEditRef.value.open is not a function，页面白屏或按钮点击无响应。

错误原因

script setup 组件默认不暴露方法：Vue3 的 <script setup> 中，子组件的方法默认是私有属性，父组件通过 ref 无法直接调用，必须手动暴露。
ref 绑定不一致：父组件模板中的 ref 属性名，必须和 script 中声明的 ref 变量名完全一致，拼写错误会导致 ref.value 为 null。
组件标签未大写：子组件标签使用小写（如 <article-edit>），部分场景下会导致 ref 绑定不稳定，Vue 推荐组件名使用大驼峰。

解决方案

子组件暴露方法：在弹窗组件中，使用 defineExpose 暴露 open 方法：

<script setup>
const dialogVisible = ref(false)
const open = (row = {}) => {
  dialogVisible.value = true
  // 处理表单数据
}
// 关键：暴露方法给父组件
defineExpose({ open })
</script>

父组件正确绑定 ref：

<script setup>
const articleEditRef = ref(null)
const onAddArticle = () => {
  // 可选：增加判断避免报错
  if (articleEditRef.value) {
    articleEditRef.value.open({})
  }
}
</script>
<template>
  <!-- 组件名大写，ref 和变量名一致 -->
  <ArticleEdit ref="articleEditRef" />
</template>

二、接口数据处理错误：列表为空、分页失效

错误现象

表格一直显示 “暂无数据”，分页组件不生效，删除功能也跟着失效。

错误原因

接口数据层级理解错误：很多后端接口返回格式为 { code: 200, data: { list: [], total: 10 } }，但很多新手直接取 res.data，导致列表和总数都拿错了层级。
变量名拼写错误：比如把 articleList 写成 articelList，模板中 :data 绑定和变量名不一致，导致表格无法渲染数据。
total 初始值类型错误：el-pagination 的 total 必须是数字类型，写成数组 ref([0]) 会直接导致分页组件报错，甚至页面崩溃。

解决方案

正确处理接口数据：先打印接口返回值，确认数据结构后再赋值：

const getArticleList = async () => {
  loading.value = true
  const res = await artGetListService(params.value)
  console.log('接口返回数据：', res) // 先打印看结构
  // 修正层级：res.data.data 才是列表，res.data.total 是总数
  articleList.value = res.data.data
  total.value = res.data.total
  loading.value = false
}

修正变量名和类型：

// 正确变量名 + 数字类型初始值
const articleList = ref([])
const total = ref(0)

<!-- 模板中绑定正确变量名 -->
<el-table :data="articleList" />

三、第三方依赖安装与导入错误：富文本编辑器无法使用

错误现象

项目中使用 @vueup/vue-quill 富文本编辑器时，控制台报错 Failed to resolve import "@vueup/vue-quill"，页面 500 报错无法加载。

错误原因

依赖未安装或安装失败：很多时候依赖安装中途报错，导致 node_modules 中没有对应的包，package.json 也未记录依赖。
版本不兼容：高版本 @vueup/vue-quill 可能和 Vue3 项目存在兼容性问题，黑马项目推荐使用 1.2.0 稳定版。
导入路径错误：样式文件路径写错，或导入语句有拼写错误。

解决方案

卸载并安装指定版本：

# 先卸载旧版本（如果有）
pnpm remove @vueup/vue-quill
# 安装稳定版
pnpm add @vueup/vue-quill@1.2.0

正确导入组件和样式：

import { QuillEditor } from '@vueup/vue-quill'
import '@vueup/vue-quill/dist/vue-quill.snow.css'

重启服务和编辑器：安装依赖后必须重启 npm run dev，让项目重新读取 node_modules。

四、组件结构错误：单个 `.vue` 文件多 `<script setup>` 标签

错误现象

控制台报错 Single file component can contain only one <script setup> element，页面 500 无法加载，路由跳转失败。

错误原因

在复制代码时，不小心在同一个 .vue 文件中粘贴了两个 <script setup> 标签，Vue 规定单文件组件只能有一个脚本标签。

解决方案

打开报错的文件（如 PageContainer.vue），删除多余的 <script setup> 标签，将两段脚本的代码合并到同一个标签中：

<!-- 错误写法 -->
<script setup>
  // 第一段代码
</script>
<script setup>
  // 第二段代码
</script>

<!-- 正确写法 -->
<script setup>
  // 合并后的所有代码
  import { ref } from 'vue'
  // ... 其他逻辑
</script>

五、Element-Plus 组件使用错误：弹窗 / 消息提示无响应

错误现象

点击删除按钮，确认弹窗不出现，或删除后无成功提示，控制台报错 ElMessageBox is not defined。

错误原因

未导入 Element-Plus 组件：使用 ElMessageBox、ElMessage 等组件时，未在 script 中导入，直接使用会导致报错。
删除逻辑未捕获错误：未使用 try-catch 包裹删除请求，接口报错或用户取消时，页面会直接崩溃。

解决方案

导入所需组件：

import { ElMessageBox, ElMessage } from 'element-plus'

完善删除逻辑：

const onDeleteArticle = async (row) => {
  try {
    await ElMessageBox.confirm('确认删除该文章吗？', '提示', { type: 'warning' })
    await artDeleteService(row.id)
    ElMessage.success('删除成功')
    getArticleList() // 刷新列表
  } catch (err) {
    // 用户取消或接口报错时友好提示
    if (err !== 'cancel') {
      ElMessage.error('删除失败，请重试')
    }
  }
}

六、总结：Vue3 项目开发避坑清单

表格

易错场景	关键检查点
父组件调用子组件方法	1. 子组件是否用 `defineExpose` 暴露方法2. `ref` 变量名和模板属性是否一致3. 组件名是否使用大驼峰
接口数据渲染	1. 先打印返回值确认数据结构2. 列表和总数是否取对层级3. `total` 必须是数字类型
第三方依赖使用	1. 依赖是否安装成功，版本是否兼容2. 导入路径是否正确3. 安装后必须重启服务
单文件组件结构	1. 只能有一个 `<script setup>` 标签2. 模板中标签必须闭合3. 变量名拼写必须一致
Element-Plus 组件	1. 使用的组件是否导入2. 异步操作必须用 `try-catch` 捕获错误