★ FEATURED ARTICLE 前几天有个后端转前端的朋友问我“现在搞 Vue3 是不是必须用 TypeScript” 我反问他“你写 Java 的时候会故意不写类型吗” 他笑了笑。实际开发里TypeScript 确实不是 Vue3 的强制选项但只要你打开 Vue3 官方文档看几页所有示例几乎默认都是script setup langts只要你维护一个超过二十个组件的后台管理系统类型就能像地图一样指路。我从 2021 年开始把公司项目从 Vue2 JS 迁到 Vue3 TS踩过的坑不算少但整体收益远大于成本。这篇博文不打算讲基础语法而是把 TypeScript 在 Vue3 应用里的项目级经验拆开围绕搭建、类型设计、组件通信、后台管理系统、声明文件、JSX 这些真实场景展开适合准备把项目迁到 TS 的团队也适合要应付 TypeScript 面试的人系统过一遍。1. Vue3 与 TypeScript 的化学反应藏在三个细节里1.1 Vue3 源码就带着 TS 的基因Vue3 的内部实现本身就是用 TypeScript 写的类型定义散落在源码的各个包中而不是像 Vue2 那样靠vue-class-component这类第三方库强行补充。这一点决定了整个生态的类型基调Pinia、Vue Router、Element Plus 这些配套库基本都有完整的.d.ts文件你拿到手就是类型齐全的。组合式 API 把状态和逻辑放进setup作用域后TypeScript 的上下文类型推断能力被彻底激活。举个例子const count ref(0) const state reactive({ name: 张三, age: 30 }) console.log(count.value) // number console.log(state.name) // stringref(0)会自动推导成Refnumberreactive({ name: 张三, age: 30 })会自动推导成{ name: string; age: number }。如果哪一行不小心给count.value赋了个字符串编辑器立刻标红不用等运行到那一行才崩溃。这个体验比 Vue2 时代this.foo被当成any的时代舒服太多了。computed和watch也一样。computed(() props.count 1)返回的是ComputedRefnumberwatch(source, (newVal, oldVal) {})的两个回调参数会自动跟着source的类型走。这些看起来不起眼的推导恰恰是减少“低级报错”最有效的武器。1.2 响应式 API 的类型推导差异ref和reactive是白天黑夜的关系类型上也有明显区别。我见过很多刚开始用 TS 的朋友在两个 API 之间反复横跳结果把代码写得很拧巴。两者在类型上的关键差异可以列个表场景refreactive支持原始值支持不支持TS 类型RefTT本身模板中访问自动解包.xxx直接访问JS 中访问ref.valueobj.xxx整体替换ref.value newObj不能直接替换只能Object.assign或重建解构每个属性带.value但可toRefs直接解构会丢失响应性需toRefsreactive的返回类型是UnwrapNestedRefsT也就是说它会把嵌套的ref解包成原始类型。知道这个原理后遇到“为什么reactive里放了ref访问时不用.value”就不会懵了。但我在实际项目里更推荐这样一个原则页面业务状态优先用ref对象形态的全局状态优先用reactive配合toRefs。原因是ref在类型上更简单替换状态的时候不会遇到reactive不能直接赋新对象的问题。你写const user refUser | null(null)后面拿到接口数据直接user.value res.data整个过程类型清晰逻辑也顺。1.3 面试里围绕“TS Vue3”的高频考点准备面试的时候光会写代码不够得能解释清楚背后的类型设计。几个我真实遇到过的题ref和reactive在类型推导上有什么区别为什么reactive不能接收原始值RefT和UnwrapNestedRefsT有什么关联withDefaults(definePropsT(), ...)背后是怎么把运行时默认值和类型声明合并的一个组合式函数返回多个响应式变量时怎么让调用方拿到精确类型而不是any这些问题的答案其实都在 Vue3 的类型源码里。面试官不要求你背源码但至少要知道ref有解包reactive会递归处理UnwrapNestedRefs是为了让模板和 JS 里的访问体验一致。把这一层想明白项目里的类型问题会少一半。2. 搭建 TS 版 Vue3 项目的关键决策别等写了一半才回头改2.1 用 Vite 脚手架还是手动搭现在新建 Vue3 TS 项目我基本是无脑选 Vite。创建命令很简单npm create vuelatest交互式选项里选择TypeScript会同时生成tsconfig.app.json、tsconfig.node.json、env.d.ts这些基础设施。vue-tsc也会被加进package.json的build脚本里。这一步能帮你省掉后续很多手动配置工作。如果你团队还在用 Vue CLI也不是不行但要注意 Vue CLI 的 Webpack 链路和 TS 的moduleResolution默认值不一样容易出现“编辑器不报错vue-tsc疯狂报错”的分裂现象。新项目老老实实用 Vite 是当下最稳的选择。2.2 tsconfig 里这些开关决定了体验tsconfig.app.json里有几个字段值得重点关注strict: true必开。strictNullChecks、noImplicitAny等全开才能把类型安全落到实处。moduleResolution: bundlerVite 项目推荐这个兼容import的很多新写法。baseUrl和paths用来配置/别名避免组件里到处都是../../../../types。jsx: preserve如果你准备用 JSX。types: []数组里写什么决定了哪些全局类型包会被加载。paths配别名之后记得tsconfig.app.json和 Vite 的resolve.alias要同步。我见过不少项目因为两边不一致IDE 里所有/开头都标红实际上运行是好的体验极差。2.3 types 文件夹和 .d.ts 声明文件到底怎么用很多刚接触 TS 的人对“types 文件夹”有误解以为只要建个文件夹放.d.ts就自动生效。实际上.d.ts文件的加载取决于 tsconfig 的include和文件的模块形态。通常项目里会有两种需求一是声明全局类型比如window上的自定义字段// src/types/global.d.ts export {} declare global { interface Window { trackingId?: string } }因为文件里有export {}它变成了一个模块所以declare global才有意义如果文件里没有任何import/export那写declare interface就默认是全局的。二是声明模块类型比如给某个没有类型的库补类型declare module offline-map { export function createMap(el: HTMLElement): void export interface MapOptions { center: [number, number] zoom: number } }这两种声明在后台管理系统里非常常见尤其是当你把全局用户信息、权限点、字典数据挂到window或全局自定义属性上时。2.4 interface 继承、type 组合与最佳实践“TypeScript interface 怎么继承”是搜索热词也是项目里不可避免的操作。其实非常简单interface BaseModel { id: string createdAt: string } interface User extends BaseModel { name: string email?: string } interface Admin extends User { role: admin permissions: string[] }interface可以多继承比如interface A extends B, C {}。而type没有extends关键字但它可以用交叉类型模拟type Product BaseModel { price: number }我的经验是数据模型、组件 props、接口返回结构这类对象结构优先用interface因为后续可以被扩展、被继承联合类型、条件类型、工具类型这种类型计算用type。两者能解决的问题有重合但背后理念不同。硬记一个规则能interface就interface需要联合/交叉再换type。3. 组件类型化的“三板斧”props、事件与插槽3.1 defineProps 类型声明与默认值Vue3.3 以后defineProps支持完全用类型声明来定义 props代码会干净很多script setup langts interface CardProps { title: string count?: number tags: string[] } const props withDefaults(definePropsCardProps(), { count: 0, tags: () [] }) /script这里有两个坑withDefaults给引用类型默认值时必须用函数返回否则多个组件实例会共享同一个数组改了一个全变了。如果只为了在模板里使用props其实不需要把返回值赋给变量但如果要在script setup里引用就必须const props ...。有人习惯用运行时声明defineProps({ title: { type: String, required: true } })也能跑但类型推导不如类型声明细腻。比如tags作为数组运行时声明只能限定它是Array没法限定数组里每个元素是 string。类型声明可以直接tags: string[]把粒度做得更细。3.2 defineEmits 让事件参数不再裸奔子组件向外抛事件最容易出现“名字拼错但没人提醒”的问题。defineEmits加类型后父组件监听时参数也能自动对齐const emit defineEmits{ update:page: [page: number] change: [value: string, old?: string] }() emit(update:page, 1) // 类型正确 emit(update:page, 1) // TS 报错number 不能给 stringVue3.3 之后的新语法更直观事件名写在 key 上参数列表写在 tuple 里。这样实现v-model:page之类的自定义事件时父组件模板里写update:pagehandlerhandler的第一个参数会自动识别成number不用再翻代码看子组件到底发射的是什么。3.3 模板 ref 与组件实例类型父组件想调用子组件方法要用ref拿到子组件实例。类型上最标准的写法是script setup langts import { ref } from vue import ChildComp from ./ChildComp.vue const childRef refInstanceTypetypeof ChildComp | null(null) const callChild () { childRef.value?.sayHello() } /script template ChildComp refchildRef / /templateInstanceTypetypeof ChildComp会推导成子组件通过defineExpose暴露出的公开类型。在子组件里defineExpose{ sayHello: () void }({ sayHello: () console.log(hello) })注意script setup本质上是闭包组件实例默认不开放内部方法必须defineExpose主动暴露。类型和运行时行为是一致的不存在“类型说能调但实际没暴露”的偏差。3.4 插槽作用域的类型写法插槽的类型一直被人忽略但遇到复杂列表组件时特别有用。Vue3.3 提供defineSlotsdefineSlots{ default: (props: { item: User; index: number }) any }()父组件写作用域插槽时v-slot{ item, index }里的item会被推导成User不需要在父组件里再声明一次类型。这对维护大型后台系统的“列表筛选插槽”模式帮助不小。4. 后台管理系统里TS 最能体现价值的地方4.1 把 API 返回的数据模型“钉死”后台管理系统最怕的就是接口数据结构变了页面多个地方没同步改。用 TS 先把每个接口的入参和出参定义出来能提前拦住大部分问题。我的习惯是在src/api目录下按业务模块维护类型// src/api/user.ts export interface PageResultT { list: T[] total: number } export interface User { userId: string name: string deptId?: string status: 0 | 1 } export function fetchUserList(params: { page: number; size: number }): PromisePageResultUser { return http.get(/api/user/list, { params }) }status: 0 | 1比number精确得多接口文档里写“0 正常 1 停用”代码里直接就能表达。如果再配合后端联调时的 JSON Schema 生成工具类型和接口字段几乎零成本对齐。4.2 扩展路由 meta 类型后台系统几乎都要在路由的meta上挂标题、图标、权限码、KeepAlive 这些字段。但 Vue Router 默认的RouteMeta是空对象直接写meta.keepAlive会报“属性不存在”。解决方式就是模块扩展// src/types/router.d.ts import vue-router declare module vue-router { interface RouteMeta { title?: string icon?: string keepAlive?: boolean permission?: string } }这个文件只要被 tsconfiginclude所有route.meta.xxx都能获得类型提示。若依这类开源后台模板里经常报的Property meta does not exist on type ...八成就是缺少这个扩展。4.3 Pinia store 的类型化写法Pinia 的类型推导很聪明但新手会在state初始值这里翻车。比如 token 初始值是null如果不给类型this.token xxx的时候可能被推断成null。正确写法是这样import { defineStore } from pinia interface UserInfo { id: string name: string avatar: string } export const useUserStore defineStore(user, { state: () ({ token: null as string | null, userInfo: null as UserInfo | null, }), actions: { async login(params: { username: string; password: string }) { // 这里 this.token 会被推导为 string | null }, }, })关键点在于null as string | null这种显式标注。如果你只写token: nullTS 会认为它永远是null后续赋值全部报错。4.4 动态增删表单行的类型设计后台系统经常有“动态添加删除表单一行数据”的需求也就是搜索热词里那个场景。没有类型的时候reactive([])可能被推导成never[]导致 push 任何对象都报错。正确做法是定义一个行模型interface CartItem { key: string name: string price: number } const formItems refCartItem[]([]) const addRow () { formItems.value.push({ key: crypto.randomUUID(), name: , price: 0, }) } const removeRow (key: string) { formItems.value formItems.value.filter(item item.key ! key) }给refCartItem[]加上泛型后v-modelitem.name才能正确识别出name是 string。别看这个点简单项目里大量“no implicit any”错误就是从这里冒出来的。4.5 若依 Vue3 项目常见 TS 报错定位若依的前端工程是基于 Vue3 TS Vite 的重型模板很多人会直接拉下来用然后遇到一堆 TS 报错。我见过的高频错误有三类Cannot use namespace X as a type多半是import { X } from ...把值和类型混在一起改成import type { X }就行。Binding element xxx implicitly has an any type解构出来的变量没有类型。严格模式下noImplicitAny会直接报错解决办法要么给函数参数加类型要么用泛型约束。Cannot find module /api/xxxtsconfig 的paths没配或者没重启 TS Server检查paths是否对应别名。排查链路一般是先看 Vite 或 IDE 终端里的完整错误信息再定位到具体文件如果是模块解析类错误先看 tsconfig如果是类型不匹配优先查接口类型定义。不要看到报错就: any糊过去不然类型系统最终会失去资金。5. 进阶声明文件、JSX 与泛型在业务中的实战5.1 手写 .d.ts 的规范很多人搜索“TypeScript 类型声明文件怎么编写”说明这确实是实际需求。.d.ts的核心作用有两个描述已有 JS 模块的对外类型以及补充全局环境类型。给第三方库补模块类型declare module some-lib { export function run(options: { mode?: dev | prod }): void }给全局变量补类型declare const __BUILD_TIME__: string如果要给window挂自定义属性但文件里又有import/export就必须用declare global包裹否则声明不会生效。这是最容易踩的坑。5.2 第三方库没有类型时怎么“补课”比如项目里接离线地图打点用的库只有 JS 版本没有类型文件。这时候不要写export default any糊弄因为那等于放弃类型检查。诚实地按库的文档写一份最小声明declare module offline-map-lib { export interface MapInstance { destroy(): void setCenter(lng: number, lat: number): void } export function initMap(el: HTMLElement, options: { center: [number, number]; zoom: number }): MapInstance }这样补出来的类型虽然不全但后续调用map.destroy()这类方法时至少有自动补全和参数检查比any有用得多。5.3 Vue3 中使用 JSX 的类型配置不是所有场景都用 SFC偶尔会遇到需要写.tsx的情况。Vue3 的 JSX 转换依赖vitejs/plugin-vue-jsxtsconfig 里需要把jsx设为preserve再配合 TS 类型推导import { defineComponent, ref } from vue export default defineComponent({ setup() { const count ref(0) return () ( button onClick{() count.value}{count.value}/button ) }, })注意在 JSX 里响应式变量必须写.value模板语法会自动解包但 JSX 本质是 render 函数不会给你解包。类型上count.value是 number页面也就能正确渲染。5.4 泛型和条件类型在业务里的一个真实用例很多人对泛型停留在“定义函数时用 T”但业务里最有价值的两个场景是Promise 包装和嵌套类型提取。比如封装请求方法时我希望传入的是一个类型返回的是解包后的数据类型type UnwrapT T extends Promiseinfer U ? U : T async function requestT(url: string): PromiseT { const res await http.get(url) return res.data as T } type UserPromise ReturnTypetypeof requestUser type UserResult UnwrapUserPromise // Userinfer U的意思是“我在这里占个位置等 TS 从PromiseUser里把User推导出来”。这个技巧在写通用表格组件、通用弹窗组件时特别常见。面试时能讲清楚infer基本就是中级以上的 TS 水准。6. 类型检查解决不了的那些坑兼容性、性能与边界情况6.1 一个被误认为 TS 问题的浏览器兼容案例热搜里有条提到“Vue3 项目在 Edge 浏览器中有时候无法关闭浏览器右上角的最小化按钮”。我当时第一反应是类型或布局 bug结果排查了大半天最后发现是浏览器开发者工具扩展拦截了快捷键跟 Vue3、TS 毫无关系。这个案例给我的教训是不是所有运行时报错都能靠类型系统兜住但类型系统至少能把“代码本身的问题”和“外部环境的问题”快速分开。如果在 Edge 里遇到页面表现异常先看控制台有没有明确的 JS 报错再试无痕模式排除扩展最后才是检查代码逻辑。团队里有人习惯一出问题就甩锅框架其实环境因素占比不低。6.2 vue-tsc 类型检查与构建性能的取舍vue-tsc做类型检查很强大但项目大了之后每次npm run build都先跑一遍vue-tsc --noEmit会很耗时。我的做法是本地开发用vite-plugin-checker异步检查CI 里再跑完整的vue-tsc --noEmit拦截错误。import checker from vite-plugin-checker export default defineConfig({ plugins: [ checker({ vueTsc: true }), ], })不过这个插件默认会吃不少内存如果开发机内存不大建议只在函数里搭一个手动触发的npm run type:check而不是一直跑在后台。类型检查是给发布质量兜底的不是为了天天打断你写代码。6.3 2026 年新建 Vue3 项目的选型建议如果现在要开一个全新后台管理项目我的默认组合是Vue3 Vite TS Pinia Vue Router Element Plus构建脚本里加上type:checktsconfig 全开 strict。自动导入插件能省事但一定要让它们生成对应的.d.ts文件否则模板里看起来没 import 的组件类型会变成any等于白开 TS。另外如果项目会用到离线地图、OFD 查看这类更偏边缘的功能先把第三方库的类型声明文件写好再动业务。否则后续每个人都可能在“这个库到底有没有这个方法”上反复翻源码。如果让我从零开始搭一个 Vue3 项目我会把类型设计放在功能开发之前尤其是types目录和 API 数据定义。这条习惯我在几个后台管理系统里反复验证过——前两周多花半天写类型后面每个迭代能省下好几个小时。TypeScript 给你带来的不是“不能写错”的束缚而是把错误提前到编译期的安全感。你在实际项目里遇到的报错九成都能在 tsconfig 或.d.ts里找到答案。
阅读完成 · 觉得有帮助？
