Vue 3 组合式 API 模式

Q: 什么是Vue 3 组合式 API 模式？适合做什么项目？

Vue 3 搭配组合式 API、Pinia 状态、VueUse 组合式函数和 Vite 构建现代响应式应用。 它通过分层组合提供端到端类型安全与开箱即用的部署体验，适合从 MVP 到生产 SaaS 的快速迭代。

Q: Vue 3 组合式 API 模式 的最佳实践有哪些？

Vue 3 组合式 API 模式 的最佳实践包括：用 — 样板少 30%，更好摇树，TS 推断；组合式函数优于 mixin — 命名导入、无属性冲突、可摇树；Pinia setup store — 函数语法、完整 TS、getters 用 computed。其中首条「用 — 样板少 30%，更好摇树，TS 推断」应在项目初始化时就落地，避免后期返工。

Vue 3 搭配组合式 API、Pinia 状态、VueUse 组合式函数和 Vite 构建现代响应式应用。

全栈中等

技术栈组成

FrameworkVue 3.5

StatePinia 2

ComposablesVueUse

RouterVue Router 4

BuildVite 6

TestingVitest + Vue Test Utils

为什么

组合式 API 支持逻辑复用且无 mixin 命名冲突。Pinia 仅 1KB、类型安全、集成 DevTools。

VueUse 提供 200+ 测试过的组合式函数（useFetch、useStorage、useIntersectionObserver）。Vue 3.5 响应式 props 解构零成本。

何时使用

选择 Vue 3 用于渐进增强、团队熟悉它和需要细粒度响应式的应用。团队仅会 React 或 SSR 密集应用避免（Nuxt 比 Next.js 复杂）。

如何做

1. 脚手架 — npm create vue@latest，选 TypeScript + Pinia + Router 2. setup 语法 — <script setup lang="ts">，无样板 return 语句 3. 组合式函数 — 提取逻辑到 useX.ts，返回 ref + 函数 4. Pinia store — defineStore 含 state、getters、actions；组件中使用 5. VueUse — npm i @vueuse/core，用 useFetch、useDark、useLocalStorage 6. 响应式 — ref() 基础类型，reactive() 对象，computed() 派生 7. 测试 — Vitest + @vue/test-utils，挂载组件，断言 emitted 事件 8. 部署 — npm run build，dist/ 部署到任意静态主机或 Nuxt 做 SSR

示例

// stores/user.ts — Pinia store 带 TypeScript import { defineStore } from "pinia"; import { ref, computed } from "vue"; export const useUserStore = defineStore("user", () => { const users = ref<User[]>([]); const count = computed(() => users.value.length); const activeUsers = computed(() => users.value.filter((u) => u.active)); async function fetchUsers() { users.value = await fetch("/api/users").then((r) => r.json()); } return { users, count, activeUsers, fetchUsers }; }); // composables/useDebounce.ts — 可复用逻辑 import { ref, watch } from "vue"; export function useDebounce<T>(source: Ref<T>, delay = 300): Ref<T> { const debounced = ref(source.value) as Ref<T>; let timer: ReturnType<typeof setTimeout>; watch(source, (val) => { clearTimeout(timer); timer = setTimeout(() => (debounced.value = val), delay); }); return debounced; } // UserList.vue — setup 语法 + Pinia + VueUse <script setup lang="ts"> import { useUserStore } from "@/stores/user"; import { useDebounce } from "@/composables/useDebounce"; import { useIntersectionObserver } from "@vueuse/core"; const store = useUserStore(); const search = ref(""); const debouncedSearch = useDebounce(search, 300); const target = ref<HTMLElement | null>(null); const { isActive } = useIntersectionObserver(target, ([{ isIntersecting }]) => { if (isIntersecting) store.fetchUsers(); }); </script> <template> <input v-model="search" placeholder="搜索..." /> <div ref="target" v-if="isActive">加载中...</div> <ul v-else> <li v-for="u in store.activeUsers" :key="u.id">{{ u.name }}</li> </ul> </template>

常见问题

⚠解构响应式对象丢失响应性 — 用 toRefs() 或 Pinia 的 storeToRefs()
⚠watch 与 watchEffect 混淆 — watch 需显式源，watchEffect 自动追踪
⚠v-for 无 :key — DOM 更新破坏，始终用唯一项 ID
⚠修改 props — Vue 警告，父组件状态用 v-model 或 emit 事件

最佳实践

✓用 <script setup> — 样板少 30%，更好摇树，TS 推断
✓组合式函数优于 mixin — 命名导入、无属性冲突、可摇树
✓Pinia setup store — 函数语法、完整 TS、getters 用 computed
✓先 VueUse 再自定义 — 200+ 测试过的组合式函数，别重造

常见问题解答

什么是Vue 3 组合式 API 模式？适合做什么项目？

Vue 3 搭配组合式 API、Pinia 状态、VueUse 组合式函数和 Vite 构建现代响应式应用。它通过分层组合提供端到端类型安全与开箱即用的部署体验，适合从 MVP 到生产 SaaS 的快速迭代。

如何用Vue 3 组合式 API 模式在 10 分钟内跑通一个 demo？

两步起步：① 脚手架 — npm create vue@latest，选 TypeScript + Pinia + Router；② setup 语法 — <script setup lang="ts">，无样板 return 语句。先跑通本地 dev server，再接一个真实数据源验证端到端链路。