> ## Content Index > Fetch the complete content index at: https://blog.vercanti.com/llms.txt > Use this file to discover other available public pages before exploring further. # Vue 3 + TypeScript 完全指南 - URL: https://blog.vercanti.com/vue-3-typescript-wan-quan-zhi-nan/ - Published: 2026-08-28T14:35:27.000Z - Updated: 2026-08-28T14:58:50.000Z - Description: 相关文档：Vue3入门(/vue-3-ru-men-zhi-nan/) | TypeScript完全指南(/typescript-wan-quan-zhi-nan/) | TypeScript最佳实践(/typescript-zui-jia-shi-jian/) | Pinia完全指南(/pinia-wan-quan-zhi-nan/) | Vue Router完全指南(/vue-router-wan-quan-zhi-nan/) 1. 概述(#%E6%A6%82%E8%BF%B0) 2. 项目搭建与工具链(#%E4%B8%80%E3%80%81%E9% - Author: yellowdog - Tags: 前端开发, Vue生态 > 官方文档： > Composition API 类型化： > SFC ` ``` #### `withDefaults` 设默认值 ```vue ``` **为什么数组对象要工厂函数：** 防止所有实例共享同一引用（与 Vue 2 同理）。 #### 响应式 Props 解构（Vue 3.5+ 稳定） 3.5 之前解构 props 会丢失响应式，3.5 起编译器自动处理： ```vue ``` **警告：** 不能在 `setTimeout` / `setInterval` 等异步回调中直接使用解构后的 prop——会读到旧值。需要传入 getter 或在使用时引用。 #### 参数表 | 参数（类型声明位置） | 类型 | 说明 | | | | ------------------ | ---------------- | -------------------------- | --- | -------- | | 类型字面量字段 | string \| number | boolean | ... | 任意 TS 类型 | | 字段加 ? | 任意 | 标记可选，组件内类型为 T \| undefined | | | | withDefaults 第二参字段 | 对应类型或工厂函数 | 字面量默认；对象/数组必须工厂函数返回 | | | #### 反例：常见错误 ```vue ``` ### 2.2 `defineEmits` 声明组件可触发的事件。 #### 四种声明方式 ```vue ``` **命名元组的优势：** 更短、更易读、IDE 提示更好。 #### 触发与父组件接收 ```vue ``` ### 2.3 `defineModel`（Vue 3.4+）为组件提供 `v-model` 双向绑定，省去手写 prop + emit 的样板。 #### 基础用法 ```vue ``` #### 命名 v-model ```vue ``` #### 修饰符（modifier transformer） ```vue ``` #### 参数表 | 参数 | 类型 | 默认值 | 说明 | | ----------------- | ------------------------------ | ------------ | -------------------------------------- | | name（第 1 参） | string | "modelValue" | v-model 的名字，决定 emit 事件名（update:） | | options.default | 同泛型 T | 无 | 父组件未提供时的默认值 | | options.required | boolean | false | 是否必传 | | options.type | Constructor \| Constructor\[\] | 无 | 运行时校验（与类型参数互斥） | | options.validator | (v) => boolean | 无 | 校验函数 | | options.set | (v) => v | 无 | 写入前的转换器（可访问 modifiers） | | options.get | (v) => v | 无 | 读取时的转换器 | #### 触发条件 `model.value = x` → emit `update:` → 父组件 v-model 绑定值更新。 ### 2.4 `defineSlots`（Vue 3.3+）为插槽提供类型签名，给父组件用 slot 时带类型提示。 ```vue ``` **参数表：** | 类型字段 | 含义 | | -------------------------- | -------------------------- | | (props: T): any | 必选 slot | | ?(props: T): any | 可选 slot | | 返回类型 any | 固定写 any（Vue 内部约定，没有更精确的类型） | ### 2.5 `defineExpose` ` ``` ### 2.6 `defineOptions`（Vue 3.3+）在 ` ``` **常用选项：** | 选项 | 类型 | 说明 | | ------------ | ------- | ---------------------------- | | name | string | 组件名（DevTools、KeepAlive、递归调用） | | inheritAttrs | boolean | 是否自动继承非 prop attribute | | compatConfig | object | Vue 2 → 3 兼容模式配置 | **限制：** 不能引用 ` ``` 按团队偏好选一种风格保持一致。 ### 2.8 `useTemplateRef`（Vue 3.5+）取代旧的"在 setup 中定义同名 ref"模式，类型推断更准确。 #### 基础用法 ```vue ``` #### 引用组件实例 ```vue ``` #### 引用泛型组件 ```vue ``` #### 旧用法（Vue 3.4 及以下） ```vue ``` **对比：** `useTemplateRef` 通过字符串名而非变量名引用，避免变量名/属性名耦合，对动态 ref 列表（`v-for` 中）也有更好支持。 #### 参数表 | 参数 | 类型 | 默认值 | 说明 | | ---------- | ------ | ------------- | --------------------- | | key（第 1 参） | string | 无 | 对应模板中 ref="key" 的字符串名 | | 泛型 T | 任意 | 自动推断或 unknown | 元素/实例类型 | 返回：`Readonly>`——初始为 `null`，组件挂载后赋值。 --- ## 三、响应式 API 与类型 ### 3.1 `ref` / `shallowRef` ```ts import { ref, shallowRef } from "vue"; import type { Ref, ShallowRef } from "vue"; // 类型推断 const count = ref(0); // Ref const name = ref(""); // Ref // 显式类型 const user = ref(null); // Ref const list = ref([]); // Ref // 不带初值时为 Ref const x = ref(); // Ref // shallowRef：不深度响应，仅 .value 替换时触发 const big = shallowRef({ /* ... */ }); big.value.x = 1; // 不触发 big.value = { ...big.value, x: 1 }; // 触发 ``` **何时用 `shallowRef`：** 大对象（>1000 字段或多层嵌套）、第三方实例（如 ECharts、Leaflet Map）、只整体替换不深度变更的状态。 ### 3.2 `reactive` / `shallowReactive` ```ts import { reactive } from "vue"; interface AppState { users: User[]; loading: boolean; page: number; } // 显式类型（推荐） const state = reactive({ users: [], loading: false, page: 1, }); // 类型推断（数组初值需要断言） const s = reactive({ users: [] as User[], loading: false, }); ``` **注意：** `reactive` 返回的是 `Reactive`，与 `T` 等价但传递时会触发 Proxy 跟踪。不能用 `const newState = state` 后赋值给非响应式变量——会断开响应链。 ### 3.3 `computed` ```ts import { computed } from "vue"; import type { ComputedRef } from "vue"; // 类型推断 const double = computed(() => count.value * 2); // ComputedRef // 显式类型（少用） const total = computed(() => items.value.reduce((s, x) => s + x, 0)); // 可写 computed const fullName = computed({ get: () => `${firstName.value} ${lastName.value}`, set: (v) => { const [f, l] = v.split(" "); firstName.value = f; lastName.value = l; }, }); ``` ### 3.4 `watch` / `watchEffect` ```ts import { watch, watchEffect } from "vue"; import type { WatchStopHandle } from "vue"; // 监听 ref watch(count, (newVal: number, oldVal: number) => { console.log(`${oldVal} → ${newVal}`); }); // 监听 getter（监听 reactive 属性必须用 getter） watch( () => state.page, (newPage) => fetchUsers(newPage), ); // 监听多个源 watch([count, name], ([c, n], [oc, on]) => {}); // 选项 watch(source, cb, { immediate: true, // 创建时立即触发 deep: true, // 深度监听对象 flush: "post", // 在 DOM 更新后触发（默认 "pre"） once: true, // 仅触发一次（3.4+） }); // 停止监听 const stop: WatchStopHandle = watch(...); stop(); // watchEffect：自动追踪依赖 watchEffect(() => { document.title = `${name.value} (${count.value})`; }); ``` #### 完整参数表（`watch`） | 参数 | 类型 | 默认值 | 说明 | | | | --------------------------- | ------------------------------- | ------- | -------------- | ----------------- | --- | | source | Ref \| Reactive | () => T | Array<...> | 必填 | 监听源 | | callback | (newV, oldV, onCleanup) => void | 必填 | 变化回调 | | | | options.immediate | boolean | false | 创建时立即用初值触发一次 | | | | options.deep | boolean | false | 深度监听（对象/数组） | | | | options.flush | "pre" \| "post" | "sync" | "pre" | 触发时机：DOM 更新前/后/同步 | | | options.once | boolean（3.4+） | false | 仅触发一次后自动停止 | | | | options.onTrack / onTrigger | (event) => void | 无 | 调试用，开发环境观察依赖追踪 | | | ### 3.5 `toRef` / `toRefs` ```ts import { toRef, toRefs } from "vue"; const state = reactive({ x: 1, y: 2 }); // toRef：把单个字段变成 ref，保持响应式连接 const x = toRef(state, "x"); x.value = 10; console.log(state.x); // 10 // toRefs：把整个 reactive 对象拆解为 ref const { x: xr, y: yr } = toRefs(state); xr.value = 100; console.log(state.x); // 100 // 常见用途：在 composable 中返回 reactive，让调用方能解构 function useCounter() { const state = reactive({ count: 0 }); return toRefs(state); } const { count } = useCounter(); // count 仍是 ref ``` --- ## 四、泛型组件写复杂表格、列表、表单时，子组件需要根据传入数据类型推断回调参数类型。Vue 3.3+ 支持 ` ``` #### 父组件使用 ```vue ``` ### 4.2 多泛型参数与约束 ```vue ``` **支持的语法：** - 多个泛型用逗号分隔：`generic="T, U"` - 约束用 `extends`：`generic="T extends Item"` - 引用外部类型需在 ` ``` ### 4.3 限制 - 不能在 `generic` 中用别名（必须就地写 `extends ...`） - 不能用 `default = SomeType`（无泛型默认值） - 仅 ` ``` #### Consumer ```vue ``` ### 6.2 引用普通子组件 ```vue ``` **`InstanceType`** 解析为该组件的实例类型，包含 `defineExpose` 暴露的所有字段。 ### 6.3 引用泛型组件 `InstanceType` 在泛型组件上需要具体化泛型参数： ```vue ``` 需要安装 `vue-component-type-helpers`（`pnpm add -D vue-component-type-helpers`）。 ### 6.4 `v-for` 中的 ref 列表 ```vue ``` `useTemplateRef` 在 v-for 中自动收集为数组。 --- ## 七、Composables 类型设计 Composable（组合式函数）是 Vue 3 复用逻辑的核心单元，等价于 React Hooks。命名以 `use` 开头。 ### 7.1 标准返回签名 ```ts // composables/useUser.ts import { ref, computed, readonly } from "vue"; import type { Ref, ComputedRef, DeepReadonly } from "vue"; interface UseUserReturn { user: DeepReadonly>; loading: Readonly>; error: Readonly>; isLoggedIn: ComputedRef; fetchUser: (id: number) => Promise; logout: () => void; } export function useUser(): UseUserReturn { const user = ref(null); const loading = ref(false); const error = ref(null); const isLoggedIn = computed(() => user.value !== null); async function fetchUser(id: number): Promise { loading.value = true; error.value = null; try { const r = await fetch(`/api/users/${id}`); if (!r.ok) throw new Error(`HTTP ${r.status}`); user.value = await r.json(); } catch (e) { error.value = e instanceof Error ? e.message : "Unknown"; } finally { loading.value = false; } } function logout(): void { user.value = null; } return { user: readonly(user), loading: readonly(loading), error: readonly(error), isLoggedIn, fetchUser, logout, }; } ``` **设计要点：** - 显式声明 `UseUserReturn`，防止内部重构改变签名 - 内部状态用 `readonly()` 包裹后返回，避免调用方直接 mutate - 修改状态通过返回的函数，单向数据流 ### 7.2 接受 options 与 AbortSignal ```ts interface UseFetchOptions { immediate?: boolean; signal?: AbortSignal; } export function useFetch(url: MaybeRefOrGetter, opts: UseFetchOptions = {}) { const data = ref(null); const error = ref(null); const loading = ref(false); async function execute() { loading.value = true; try { const r = await fetch(toValue(url), { signal: opts.signal }); data.value = await r.json(); } catch (e) { if ((e as Error).name === "AbortError") return; error.value = e as Error; } finally { loading.value = false; } } if (opts.immediate) execute(); return { data, error, loading, execute }; } ``` 参考 [TypeScript最佳实践 · 3.5 异步函数接受 AbortSignal 实现可取消](https://blog.vercanti.com/typescript-zui-jia-shi-jian/#3.5-%E5%BC%82%E6%AD%A5%E5%87%BD%E6%95%B0%E6%8E%A5%E5%8F%97-abortsignal-%E5%AE%9E%E7%8E%B0%E5%8F%AF%E5%8F%96%E6%B6%88)。 ### 7.3 `MaybeRefOrGetter` 兼容三种入参 ```ts import { toValue } from "vue"; import type { MaybeRefOrGetter } from "vue"; // 同时支持 ref / getter / 原始值 function useDouble(source: MaybeRefOrGetter) { return computed(() => toValue(source) * 2); } useDouble(10); // 原始值 useDouble(ref(10)); // ref useDouble(() => state.x); // getter ``` VueUse 库的大量 composable 都遵循此约定。 --- ## 八、Pinia + TypeScript Pinia 是 Vue 3 推荐的状态管理库，类型推断设计为零配置。 ### 8.1 Setup Store 风格（推荐） ```ts // stores/user.ts import { defineStore } from "pinia"; import { ref, computed } from "vue"; interface User { id: number; name: string; role: "admin" | "user"; } export const useUserStore = defineStore("user", () => { // state const user = ref(null); const loading = ref(false); // getters const isAdmin = computed(() => user.value?.role === "admin"); // actions async function login(email: string, pass: string): Promise { loading.value = true; try { const r = await fetch("/api/login", { method: "POST", body: JSON.stringify({ email, pass }), }); user.value = await r.json(); } finally { loading.value = false; } } function logout(): void { user.value = null; } return { user, loading, isAdmin, login, logout }; }); ``` #### 在组件中 ```vue ``` ### 8.2 Options Store 风格 ```ts export const useCounterStore = defineStore("counter", { state: (): { count: number; history: number[] } => ({ count: 0, history: [], }), getters: { double: (state): number => state.count * 2, // 引用其他 getter 需要标注 this quadruple(): number { return this.double * 2; }, }, actions: { increment(n: number = 1): void { this.count += n; this.history.push(this.count); }, }, }); ``` **Setup 风格 vs Options 风格：** Setup 类型推断更精准（特别是返回类型）、与 composable 形式一致；Options 风格更接近 Vuex 习惯。**新项目用 Setup 风格。** ### 8.3 跨 store 类型引用 ```ts import { useUserStore } from "./user"; export const useOrderStore = defineStore("order", () => { const userStore = useUserStore(); const orders = ref([]); async function loadMyOrders() { if (!userStore.user) return; orders.value = await fetch(`/api/orders?user=${userStore.user.id}`).then(r => r.json()); } return { orders, loadMyOrders }; }); ``` 类型自动推断，无需手动声明。 ### 8.4 Pinia 插件全局类型扩展 ```ts // stores/persistent.d.ts import "pinia"; declare module "pinia" { export interface DefineStoreOptionsBase { persist?: boolean | { paths?: string[] }; } } ``` 之后所有 `defineStore` 都能识别 `persist` 选项。参见 [Pinia完全指南](https://blog.vercanti.com/pinia-wan-quan-zhi-nan/)。 --- ## 九、Vue Router + TypeScript ### 9.1 基础路由类型 ```ts // router/index.ts import { createRouter, createWebHistory } from "vue-router"; import type { RouteRecordRaw } from "vue-router"; const routes: RouteRecordRaw[] = [ { path: "/", name: "home", component: () => import("@/pages/Home.vue") }, { path: "/user/:id", name: "user", component: () => import("@/pages/User.vue"), props: true, meta: { requiresAuth: true, title: "用户" }, }, ]; export const router = createRouter({ history: createWebHistory(), routes, }); ``` ### 9.2 扩展 `RouteMeta` 类型 ```ts // router/types.d.ts import "vue-router"; declare module "vue-router" { interface RouteMeta { requiresAuth?: boolean; title?: string; roles?: Array<"admin" | "user" | "guest">; keepAlive?: boolean; } } ``` 全局有效——所有 `to.meta.requiresAuth` 都有类型提示。 ### 9.3 路由守卫类型 ```ts import type { NavigationGuardWithThis } from "vue-router"; const beforeAuth: NavigationGuardWithThis = (to, from) => { if (to.meta.requiresAuth && !isLoggedIn()) { return { name: "login", query: { redirect: to.fullPath } }; } // 不返回值或返回 true → 放行 }; router.beforeEach(beforeAuth); ``` ### 9.4 路由参数类型 `route.params` / `route.query` 默认值为 `string | string[]`。需要类型时显式断言或封装： ```ts import { useRoute } from "vue-router"; const route = useRoute(); const id = String(route.params.id); // 总是 string const tags = ([] as string[]).concat(route.query.tags ?? []); ``` **端到端类型安全：** unplugin-vue-router 或 vue-router 的 typed routes（v4.5+ 实验性）能生成全类型化的 `router.push({ name: "user", params: { id: "1" } })`。参见 [Vue Router完全指南](https://blog.vercanti.com/vue-router-wan-quan-zhi-nan/)。 --- ## 十、自定义指令、插件与全局类型扩展 ### 10.1 自定义指令的类型 ```ts // directives/v-focus.ts import type { Directive, DirectiveBinding } from "vue"; interface FocusValue { delay?: number; select?: boolean; } export const vFocus: Directive = { mounted(el, binding) { // binding.value 类型为 FocusValue const { delay = 0, select = false } = binding.value ?? {}; setTimeout(() => { el.focus(); if (select) el.select(); }, delay); }, }; ``` #### 使用 ```vue ``` #### `Directive` 与 `ObjectDirective` 完整钩子 | 钩子 | 触发时机 | | -------------------------------------- | -------------------- | | created(el, binding, vnode, prevVnode) | 元素 vnode 创建后（DOM 之前） | | beforeMount(el, ...) | 挂载前 | | mounted(el, ...) | 挂载后 | | beforeUpdate(el, ...) | 包含组件更新前 | | updated(el, ...) | 更新后 | | beforeUnmount(el, ...) | 卸载前 | | unmounted(el, ...) | 卸载后 | ### 10.2 插件类型 ```ts // plugins/i18n.ts import type { App, Plugin } from "vue"; interface I18nOptions { locale: string; messages: Record>; } const i18n: Plugin<[I18nOptions]> = { install(app: App, options: I18nOptions) { const t = (key: string) => options.messages[options.locale]?.[key] ?? key; app.config.globalProperties.$t = t; app.provide("i18n", { t, locale: options.locale }); }, }; export default i18n; // main.ts import i18n from "./plugins/i18n"; app.use(i18n, { locale: "zh", messages: { zh: { hello: "你好" } } }); ``` ### 10.3 扩展 `ComponentCustomProperties`（this.$xxx） ```ts // plugins/i18n.d.ts import "vue"; declare module "vue" { interface ComponentCustomProperties { $t: (key: string) => string; } } ``` 模板与 Options API 中 `$t("hello")` 类型安全。 ### 10.4 扩展全局组件类型 ```ts // global-components.d.ts import "vue"; import MyButton from "@/components/MyButton.vue"; declare module "vue" { interface GlobalComponents { MyButton: typeof MyButton; } } ``` 全局注册的组件在模板中有类型提示。 --- ## 十一、模板内的类型推断 Vue 模板由 vue-tsc 编译时检查类型，规则与 JS 略有差异。 ### 11.1 模板中的表达式 ```vue ``` ### 11.2 `v-for` 类型推断 ```vue ``` ### 11.3 事件处理器参数类型 ```vue ``` ### 11.4 slot props 推断 ```vue ``` --- ## 十二、最佳实践 **1\. ` ``` **2\. `defineModel` 替代手写 prop + emit。** 3.4+ 的 `defineModel` 让 v-model 组件实现从 20 行降到 1 行，且类型完全推断。 **3\. Composable 显式声明返回类型。** 防止内部重构悄悄破坏调用方的解构与类型提示。 ```ts // 正确 export function useUser(): UseUserReturn { /* ... */ } // 错误：类型靠推断，重构时调用方先报错才发现 export function useUser() { /* ... */ } ``` **4\. 跨组件共享数据用 `InjectionKey` \+ `useXxx` 包装。** 不要在组件中直接 `inject("string-key")`——类型为 `unknown` 且没有 IDE 提示。 **5\. 模板 ref 优先用 `useTemplateRef`（3.5+）。** 旧的同名 ref 模式仍可用，但 `useTemplateRef` 在 v-for、动态 key、TypeScript 推断上更稳定。 **6\. Pinia 用 Setup Store 风格。** 类型推断最准；与 composable 形式一致；不需要为 `this` 写复杂的类型注解。 **7\. `RouteMeta` / `ComponentCustomProperties` 在 d.ts 中扩展。** 避免散落的 `(route.meta as any).requiresAuth`。 **8\. 公共组件库必须用泛型组件 + `defineSlots`。** 让消费者能拿到完整类型推断。否则用户每次都要手动 cast。 **9\. shallow 系列 API 用于大对象或第三方实例。** ECharts、Three.js、地图实例等——`shallowRef` 避免 Proxy 包裹导致的性能损耗。 **10\. `vue-tsc --build` 在 CI 中跑严格类型检查。** Vite 开发模式不做完整类型检查（只走 esbuild 转译），必须靠 vue-tsc 兜底。 --- ## 十三、常见陷阱 ### 陷阱 1：解构 props 后丢失响应式（Vue 3.5 之前） **现象：** 在 ` ``` ### 陷阱 2：忘记 `storeToRefs` 解构 Pinia store **现象：** `const { count } = useCounterStore()` 后 `count` 不响应。 **原因：** Pinia store 返回的对象的 state 与 getters 是响应式的，但**普通解构会破坏这种响应式**。`storeToRefs` 把它们转成 `Ref` 后再解构。 **解决：** state 与 getter 用 `storeToRefs`，actions 直接解构。 ```ts // 错误 const { count, double, increment } = useCounterStore(); // count、double 不响应 // 正确 const store = useCounterStore(); const { count, double } = storeToRefs(store); const { increment } = store; ``` ### 陷阱 3：`reactive` 整体替换断开响应 **现象：** 用 `state = newObj` 替换整个 reactive 对象后，组件不更新。 **原因：** `reactive` 的响应式追踪绑定在原始 Proxy 上，整个变量重新赋值丢失追踪。 **解决：** 用 `Object.assign` 合并字段，或改用 `ref` \+ `.value` 替换。 ```ts // 错误 let state = reactive({ x: 1, y: 2 }); state = reactive({ x: 10, y: 20 }); // 模板不更新 // 正确（reactive） Object.assign(state, { x: 10, y: 20 }); // 正确（ref） const state = ref({ x: 1, y: 2 }); state.value = { x: 10, y: 20 }; ``` ### 陷阱 4：`InstanceType` 用于泛型组件失效 **现象：** `useTemplateRef>("list")` 类型推断不出 `defineExpose` 的字段。 **原因：** `InstanceType` 提取类的实例类型，但泛型组件的实例签名不带具体泛型，导致 expose 内容是 `unknown`。 **解决：** 用 `ComponentExposed`（`vue-component-type-helpers` 包）。 ```vue ``` ### 陷阱 5：宏在变量中传递 **现象：** `const opts = { foo: String }; defineProps(opts);` 编译报错。 **原因：** `defineProps` / `defineEmits` 是编译期宏，参数必须是字面量；编译器静态分析需要看到完整声明。 **解决：** 直接传字面量；如果要复用，把整个组件抽成函数返回。 ```vue ``` ### 陷阱 6：`provide` / `inject` 在 setup 之外调用 **现象：** 在异步回调或事件处理器中调用 `inject`，返回 `undefined`。 **原因：** `inject` 必须在 setup 同步阶段调用——它依赖当前激活的组件实例上下文。 **解决：** 在 setup 顶层 inject 一次，后续使用结果。 ```ts // 错误 async function load() { const ctx = inject(key); // undefined } // 正确 const ctx = inject(key); async function load() { ctx?.doSomething(); } ``` ### 陷阱 7：`watch` 监听 reactive 属性丢失响应 **现象：** `watch(state.x, cb)` 不触发。 **原因：** 监听源必须是 ref、reactive 对象、getter 函数或它们的数组。直接传 `state.x`（值）等价于传一个普通数字。 **解决：** 用 getter 包裹。 ```ts // 错误 watch(state.x, cb); // 正确 watch(() => state.x, cb); // reactive 整体监听（自动 deep） watch(state, cb, { deep: true }); ``` ### 陷阱 8：导入 `.vue` 文件无类型 **现象：** `import Comp from "./Comp.vue"` 报错或类型为 `any`。 **原因：** TS 默认不识别 `.vue` 扩展。 **解决：** 确保 `env.d.ts`（或同等文件）声明了 `.vue` 模块。 ```ts declare module "*.vue" { import type { DefineComponent } from "vue"; const c: DefineComponent<{}, {}, any>; export default c; } ``` 并确认 `tsconfig.json` 的 `include` 包含该 d.ts 文件。 ### 陷阱 9：组件 emit 事件名大小写不一致 **现象：** 子组件 emit 的事件父组件接收不到。 **原因：** 模板中事件名用 kebab-case（`@user-update`），JS 中用 camelCase（`emit("userUpdate")`），Vue 会自动转换——但 `defineEmits` 类型字段要与 emit 调用一致。 **解决：** `defineEmits` 类型字段用 camelCase，模板用 kebab-case。 ```vue ``` ### 陷阱 10：`defineModel` 修饰符解构后类型为 `unknown` **现象：** `const [model, mods] = defineModel(); mods.trim` 报错。 **原因：** `mods` 默认类型是 `Record`，不限制具体修饰符名。 **解决：** 用第二个泛型参数声明可识别的修饰符。 ```vue ``` --- ## 参见 - [Vue3入门](https://blog.vercanti.com/vue-3-ru-men-zhi-nan/) — Vue 3 基础（JS 风格，本文的前置） - [TypeScript完全指南](https://blog.vercanti.com/typescript-wan-quan-zhi-nan/) — TS 语法手册，含 Vue 集成速览 - [TypeScript最佳实践](https://blog.vercanti.com/typescript-zui-jia-shi-jian/) — TS 通用最佳实践（严格配置、类型设计、AbortSignal、Zod、类型测试） - [Pinia完全指南](https://blog.vercanti.com/pinia-wan-quan-zhi-nan/) — Pinia 状态管理完整 API - [Vue Router完全指南](https://blog.vercanti.com/vue-router-wan-quan-zhi-nan/) — 路由配置、守卫、动态路由 - [Nuxt3完全指南](https://blog.vercanti.com/nuxt-3-wan-quan-zhi-nan/) — Vue 全栈框架（自带 TS 配置与类型化） - [PrimeVue完全指南](https://blog.vercanti.com/primevue-wan-quan-zhi-nan/) — Vue 组件库（与 TS 集成示例） - [Vite初级指南](https://blog.vercanti.com/vite-chu-ji-zhi-nan/) — Vue + TS 项目的默认构建工具 - [JavaScript Promise 完全指南](https://blog.vercanti.com/javascript-promise-wan-quan-zhi-nan/) — async/await 与错误处理基础

用户列表