Vue3 + TypeScript 20 个常见报错

1. Cannot find module 'xxx.vue'

原因: TypeScript 不知道 .vue 文件是什么模块。

改法: 项目根目录加 env.d.ts(或 vite-env.d.ts),并声明:

ts 复制代码
/// <reference types="vite/client" />

若仍报错,检查 tsconfig.json 的 include 是否包含该声明文件。


2. Property 'xxx' does not exist on type

原因: 模板里用的属性 / 方法在组件里没声明,或类型推断不到。

改法: 在 defineProps / defineEmits 里写类型;ref 用泛型 ref<T>();必要时给 defineExpose 或接口补全类型。


3. ref 取值仍是 undefined 或类型不对

原因: 模板里自动解包,脚本里要用 .value。

改法: 脚本中访问 ref 一律 xxx.value;watch 监听 ref 时可直接写 () => xxx.value 或 xxx(视写法而定)。


4. Type 'string | undefined' is not assignable to type 'string'

原因: 可选链、可选属性、接口字段带 ?,导致可能是 undefined。

改法: 默认值:x ?? '';断言(确定有值时):as string;或把目标类型改成 string | undefined。


5. Argument of type 'X' is not assignable to parameter of type 'Y'

原因: 函数参数、事件回调、子组件 emit 的类型和实际传入不一致。

改法: 对齐两边类型;用联合类型;对 unknown 先收窄(typeof / 类型守卫)再使用。


6. Object is possibly 'null' / 'undefined'

原因: 严格空值检查下,编译器认为可能为空。

改法: 可选链 ?.、空值合并 ??;或 if (x != null) 收窄后再用。


7. 模板里组件报红:Component is not resolved

原因: 组件未导入、未全局注册,或名称与标签不一致。

改法: <script setup> 中 import 后直接使用;或检查 components: { ... } 与模板标签名是否一致。


8. defineProps / defineEmits 只能在 <script setup> 顶层使用

原因: 宏只能在编译期、顶层调用,不能放在函数或条件里。

改法: 把 defineProps、defineEmits 挪到 <script setup> 最外层。


9. withDefaults(defineProps<...>(), { ... }) 默认值类型报错

原因: 泛型里必填属性与 withDefaults 里"有默认值"冲突,或类型写法不兼容。

改法: 把有默认值的属性在接口里标成可选 ?;或分开写 Props 与默认值对象,保证类型一致。


10. emit 事件名与类型不匹配

原因: defineEmits 的类型字面量和实际 emit('name', payload) 不一致。

改法: 使用元组形式写 payload,例如:

ts 复制代码
const emit = defineEmits<{
  change: [id: number]
  close: []
}>()

11. v-model 与 modelValue / update:modelValue 对不上

原因: Vue 3 默认 v-model 对应 modelValue 和 update:modelValue;自定义名字要用 v-model:xxx。

改法: 子组件 defineProps 里声明 modelValue,emit('update:modelValue', val);具名则 foo + update:foo。


12. useRouter / useRoute 在错误位置调用

原因: 组合式 API 必须在 setup 或 <script setup> 同步执行阶段调用(或符合插件要求的上下文)。

改法: 不要在异步回调里首次调用 useRouter;应先在 setup 里取出 router / route 再传入。


13. Pinia:storeToRefs 解构后失去响应式

原因: 直接解构 store 会丢掉响应式。

改法: 状态用 storeToRefs(store),方法仍从 store 上取。


14. import.meta.env 报类型错误

原因: 未扩展 ImportMetaEnv 接口。

改法: 在 env.d.ts 里 interface ImportMetaEnv { readonly VITE_XXX: string },并扩展 ImportMeta。


15. 第三方库没有类型:Could not find a declaration file

原因: 包未自带 @types/xxx。

改法: 安装 @types/包名;或自建 xxx.d.ts:declare module '包名';最差用 // @ts-expect-error 并注明原因。


16. this 相关报错(在 <script setup> 里)

原因: 组合式 API 里没有选项式里的 this。

改法: 用 ref / computed / 函数闭包代替 this.xxx;需要实例时用 getCurrentInstance()(尽量少用,优先显式传参)。


17. 异步组件 / defineAsyncComponent 类型推断差

原因: 动态 import 返回类型较宽。

改法: 给变量显式标注组件类型,或对 resolve 结果 as DefineComponent<...>(按项目规范取舍)。


18. Readonly<Array> 不能赋给 Mutable 数组

原因: props 在运行时只读,类型上常推断为 readonly。

改法: 不要原地改 props;需要副本时用 [...arr] 或 arr.slice() 再改。


19. 模板 ref 与脚本 ref 重名或拿不到 DOM

原因: 模板 ref 与变量名冲突,或 DOM 尚未挂载就读取。

改法: 改名区分;在 onMounted 或使用 nextTick 后再访问模板 ref。


20. 构建通过但 IDE 仍红线(或相反)

原因: IDE 用的 TypeScript 版本与 vue-tsc / Vite 不一致;或只检查了部分目录。

改法: 工作区选用项目内的 TypeScript;统一 tsconfig 的 include / references;Vue 文件用 Volar(Vue - Official)并禁用旧 Vetur。


小结

方向 建议
类型 props / emit 用泛型写全;少用 any,必要时再收窄
响应式 脚本里记牢 .value;Pinia 用 storeToRefs
工程 env.d.ts + tsconfig 包含范围 + 与构建工具一致

有新报错时,优先看完整 TS 报错栈和行号,再对照上表关键词检索即可。

  • 想学完整的后台管理系统实战?点击订阅我的专栏
相关推荐
泯泷2 小时前
Vercel AI SDK 6 完整教程系列 - 第一部分:基础入门篇
前端·javascript
程序员大阳3 小时前
副队长Vue3教程(5)--事件绑定 v-on
前端·javascript·vue.js·vue3·事件绑定·v-on
泯泷4 小时前
Vercel AI SDK 6 完整教程系列 - 第二部分:结构化数据与工具调用
前端·javascript
云起SAAS6 小时前
手机靓号选号商城H5源码 完整前后台可直接运行
前端·javascript·后端
code2cat6 小时前
JavaScript编程篇之异步请求:切换到待办,为什么又显示了全部任务
前端·javascript
1-1=06 小时前
Vue 条件渲染和列表渲染
前端·javascript·vue.js
用户298698530146 小时前
React 前端实现 Word 与 OpenXML 双向转换的完整实践
javascript·react.js
Highcharts.js7 小时前
Workbuddy + Highcharts Orbit:工作区数据自动建模与可视化分析实践
前端·javascript·信息可视化·数据可视化·highcharts·可视化图表·workbuddy
程序员大阳18 小时前
副队长Vue3教程(2)--Vite 搭建 Vue 项目,认识目录结构
前端·javascript·vue.js·vite·创建项目·目录结构·项目结构
濮水大叔18 小时前
Cabloy/Zova 与 Next.js 的 SSR 水合差异
前端·typescript·next.js