uniapp+vue3虽然有很多适配兼容方面的问题，但是优点也是很多，并且UniApp官方也推荐新项目使用Vue3，未来生态将更多聚焦Vue3。
开发中高频出现的报错场景、原因及对应解决方案，覆盖语法、配置、组件、运行环境等维度：
| 报错类型 | 具体报错信息 / 场景 | 报错原因 | 解决方法 |
|---|---|---|---|
| 语法兼容报错 | Uncaught TypeError: Cannot read properties of undefined (reading 'xxx')（组合式 API） |
1. setup 中未正确返回变量 / 方法；2. 解构响应式数据时丢失响应式；3. 异步数据未判空 | 1. 确保 setup 中 return 暴露需在模板使用的变量 / 方法；2. 解构响应式数据用 toRefs/toRef；3. 模板中加判空（如 {``{ xxx?.name }}）；4. 异步数据初始化赋值空对象 / 数组（如 const list = ref([])） |
'defineProps' is not defined |
Vue3 中 defineProps/defineEmits 是编译器宏，未配置 eslint 忽略 |
1. package.json 中 eslint 配置添加："globals": { "defineProps": "readonly", "defineEmits": "readonly" }；2. 或在代码顶部加 /* eslint-disable no-undef */ |
|
| 配置类报错 | 运行小程序提示 未找到入口文件 pages.json 配置异常 |
1. pages.json 路径错误 / 语法错误（如逗号缺失）；2. Vue3 版 uni-app 配置格式不兼容 | 1. 检查 pages.json 语法（JSON 不允许注释、尾逗号）；2. 确保 pages.json 中页面路径与实际文件路径一致；3. 升级 HBuilderX 至支持 Vue3 的版本（≥3.2.0） |
打包 H5 提示 module not found: Error: Can't resolve 'vue' |
1. 依赖包版本不兼容；2. npm 依赖未安装 / 安装失败 | 1. 检查 package.json 中 vue 版本（需与 uni-app 要求匹配，如 uni-app 3.x 适配 vue 3.2+）；2. 执行 npm install 重装依赖，或删除 node_modules 后重新安装 |
|
| 组件相关报错 | 自定义组件报错 Failed to mount component: template or render function not defined |
1. 组件未正确注册；2. Vue3 中组件不再支持 export default { components: {} } 局部注册的旧写法；3. 组件文件路径错误 |
1. 全局注册：在 main.js 中 app.component('组件名', 组件)；2. 局部注册：在 setup 同级用 import 组件 from '路径'，模板直接使用（Vue3 自动识别）；3. 检查组件引入路径（避免相对路径层级错误） |
内置组件报错 uni-list 未找到（uView Plus/Vant Uni） |
1. UI 组件库未适配 Vue3；2. 组件库未正确注册 | 1. 替换为 Vue3 版 UI 库（如 uView Plus、Vant Uni）；2. 按组件库文档完成全局注册（如 Vant Uni 需 import { createVantUni } from 'vant-uni'; app.use(createVantUni())） |
|
| 响应式相关报错 | ref 定义的变量修改后模板不更新 |
1. 直接修改 ref 原始值（如 list = [] 而非 list.value = []）；2. 复杂对象嵌套修改未触发响应式 |
1. 始终通过 .value 修改 ref 变量（setup 内部）；2. 复杂对象嵌套修改用 reactive，或 ref 配合 Object.assign（如 list.value = Object.assign({}, list.value, newData)） |
computed 计算属性不生效 |
1. computed 未返回值；2. 依赖的响应式数据未正确定义 | 1. 确保 computed 回调返回计算结果（如 const fullName = computed(() => {firstName.value} {lastName.value})）；2. 检查依赖的变量是否为 ref/reactive 定义 |
|
| 运行环境报错 | 小程序端提示 TypeError: xxx is not a function（如 uni.request） |
1. Vue3 版 uni-app 部分 API 调整；2. 小程序基础库版本过低 | 1. 确认 API 兼容性（如 uni-app 3.x 中 uni.request 用法不变，若自定义封装需检查参数）；2. 升级小程序基础库（微信小程序≥2.30.0）；3. 重启小程序开发者工具，清除缓存 |
H5 端报错 Uncaught ReferenceError: uni is not defined |
1. H5 打包配置未启用 uni 全局对象；2. 异步加载导致 uni 未初始化 | 1. 在 manifest.json -> h5 -> config 中添加："globalObject": "window"；2. 确保代码在 onLaunch/onMounted 后执行，或加判断 if (uni) { ... } |
|
| 生命周期报错 | onLoad/onShow 等小程序生命周期不执行 |
1. Vue3 中页面生命周期与小程序生命周期混用错误；2. setup 中未正确注册 | 1. 页面级生命周期：在 setup 中通过 uni.onLoad 注册（如 uni.onLoad((options) => { console.log(options) })）；2. 组件级生命周期用 Vue3 原生（如 onMounted），小程序生命周期仅在页面文件中使用 |
| 样式兼容报错 | H5 端样式正常，小程序端样式失效 | 1. Vue3 中 scoped 样式穿透语法变化；2. rpx 单位兼容问题 | 1. 样式穿透用 :deep() 替代 ::v-deep（Vue3 标准）；2. 检查小程序端是否开启 rpx 适配（pages.json 中 "rpxCalcEnable": true）；3. 避免使用小程序不支持的 CSS 属性（如 gap 需降级） |