TL;DR

Vue 3 是一个渐进式 JavaScript 框架，专注于可增量采用。其 Composition API（替代 Options API）实现了更好的 TypeScript 集成、通过组合式函数复用逻辑以及细粒度响应性。Vue 3 比 Vue 2 小 41%，支持 tree-shaking，并包含 Teleport、Suspense 和 defineAsyncComponent 等强大新特性。script setup 语法大幅减少了样板代码。Pinia 已取代 Vuex 成为官方状态管理方案。如果你在构建新项目，请使用 Vue 3 + script setup + TypeScript + Pinia + Vue Router 4。

核心要点

• Composition API 是编写 Vue 3 组件的推荐方式——它按功能而非生命周期钩子组织逻辑，使大型组件更易于维护和测试。
• script setup 是 Composition API 的语法糖，消除了样板代码：无需显式返回值，defineProps/defineEmits 替代选项对象，TypeScript 类型推断自动工作。
• Pinia 是官方 Vue 状态管理库——使用 Composition API，完全 TypeScript 类型化，支持 Vue DevTools，比 Vuex 更简单，没有 mutations。
• 组合式函数（useXxx 函数）是 Vue 3 中可复用有状态逻辑的模式——它们替代了 mixins，在大多数用例中提供完整的 TypeScript 类型支持。
• Vue 3 比 Vue 2 小 41%，完全支持 tree-shaking，意味着未使用的特性不会包含在生产包中。
• Vue Router 4 专为 Vue 3 设计，提供一流的 TypeScript 支持、Composition API 集成（useRoute、useRouter）和改进的导航守卫。

// ref() for primitives
import { ref, reactive, computed, watch, watchEffect } from 'vue';

const count = ref(0);
const message = ref('Hello Vue 3');

// Access via .value in <script>
count.value++; // 1
console.log(count.value); // 1

// In template, Vue auto-unwraps: {{ count }} not {{ count.value }}

// reactive() for objects
const user = reactive({
  name: 'Alice',
  age: 30,
  address: { city: 'Paris' },
});

// Mutate directly (no .value needed)
user.name = 'Bob';
user.address.city = 'London'; // deep reactivity works

// WRONG: breaking reactivity by destructuring
// const { name } = user; // name is no longer reactive!

// CORRECT: use toRefs to maintain reactivity
import { toRefs } from 'vue';
const { name, age } = toRefs(user); // still reactive

import { ref, computed, watch, watchEffect } from 'vue';

const firstName = ref('Evan');
const lastName = ref('You');

// computed: auto-tracks dependencies, memoized
const fullName = computed(() => firstName.value + ' ' + lastName.value);
console.log(fullName.value); // "Evan You"

// Writable computed
const reversedName = computed({
  get: () => firstName.value.split('').reverse().join(''),
  set: (val: string) => { firstName.value = val.split('').reverse().join(''); },
});

// watch: explicit deps, receives old + new value
watch(firstName, (newVal, oldVal) => {
  console.log('firstName changed from ' + oldVal + ' to ' + newVal);
});

// watch multiple sources
watch([firstName, lastName], ([newFirst, newLast], [oldFirst, oldLast]) => {
  console.log('Name changed');
});

// watch with immediate: true
watch(firstName, (val) => { document.title = val; }, { immediate: true });

// watchEffect: auto-tracks, runs immediately
watchEffect(() => {
  console.log('firstName is now:', firstName.value); // runs on mount + changes
  console.log('lastName is now:', lastName.value);
});

<!-- UserCard.vue -->
<script setup lang="ts">
import { ref, computed } from 'vue';

// Props with TypeScript generics — no import needed for defineProps
const props = defineProps<{
  name: string;
  age: number;
  role?: string; // optional prop
}>();

// Default values with withDefaults
const propsWithDefaults = withDefaults(defineProps<{ role?: string }>(), {
  role: 'viewer',
});

// Emits with TypeScript
const emit = defineEmits<{
  select: [userId: number];    // named tuple syntax
  update: [name: string, age: number];
  close: [];                    // no payload
}>();

const isExpanded = ref(false);
const initials = computed(() =>
  props.name.split(' ').map(n => n[0]).join('')
);

function handleSelect() {
  emit('select', 42);
}

// defineExpose: make internal state accessible via template ref
defineExpose({ isExpanded, initials });
</script>

<template>
  <div @click="handleSelect">
    <span>{{ initials }}</span>
    <p>{{ props.name }}, {{ props.age }}</p>
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef, onMounted, ref } from 'vue';

// Vue 3.5+ approach
const inputEl = useTemplateRef<HTMLInputElement>('myInput');

// Pre-3.5 approach (still works)
const legacyInputEl = ref<HTMLInputElement | null>(null);

onMounted(() => {
  // Populated after mount
  inputEl.value?.focus();
  legacyInputEl.value?.select();
});
</script>

<template>
  <!-- ref attribute matches the string in useTemplateRef() -->
  <input ref="myInput" type="text" placeholder="Auto-focused on mount" />
  <input ref="legacyInputEl" type="text" placeholder="Legacy approach" />
</template>

// src/router/index.ts
import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'home',
    component: () => import('../views/HomeView.vue'), // lazy-loaded
  },
  {
    path: '/users',
    component: () => import('../views/UsersLayout.vue'),
    children: [
      { path: '', name: 'user-list', component: () => import('../views/UserList.vue') },
      { path: ':id', name: 'user-detail', component: () => import('../views/UserDetail.vue') },
    ],
  },
  {
    path: '/admin',
    component: () => import('../views/AdminView.vue'),
    meta: { requiresAuth: true, requiresAdmin: true },
  },
  { path: '/:pathMatch(.*)*', name: 'not-found', component: () => import('../views/NotFound.vue') },
];

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) return savedPosition;
    return { top: 0 };
  },
});

export default router;

// Global navigation guard — authentication check
router.beforeEach(async (to, from) => {
  const authStore = useAuthStore();
  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
    return { name: 'login', query: { redirect: to.fullPath } };
  }
  if (to.meta.requiresAdmin && !authStore.isAdmin) {
    return { name: 'forbidden' };
  }
  // return undefined or true to proceed
});

// In-component guards (Composition API)
<script setup lang="ts">
import { onBeforeRouteLeave, onBeforeRouteUpdate, useRoute, useRouter } from 'vue-router';

const route = useRoute();   // reactive current route
const router = useRouter(); // router instance for programmatic navigation

console.log(route.params.id);  // current :id param
console.log(route.query.page); // ?page= query param
console.log(route.meta);       // typed route meta

onBeforeRouteLeave((to, from) => {
  if (hasUnsavedChanges.value) {
    return confirm('You have unsaved changes. Leave?');
  }
});

onBeforeRouteUpdate((to, from) => {
  // fires when same component used for different params
  fetchUser(to.params.id as string);
});

// Programmatic navigation
router.push({ name: 'user-detail', params: { id: 42 } });
router.replace('/dashboard');
router.go(-1); // go back
</script>

// src/stores/counter.ts — Setup Store (preferred)
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';

export const useCounterStore = defineStore('counter', () => {
  // state
  const count = ref(0);
  const history = ref<number[]>([]);

  // getters (computed)
  const doubleCount = computed(() => count.value * 2);
  const isPositive = computed(() => count.value > 0);

  // actions
  function increment() {
    history.value.push(count.value);
    count.value++;
  }

  async function fetchAndSet(id: number) {
    const data = await fetch('/api/counts/' + id).then(r => r.json());
    count.value = data.value;
  }

  function $reset() { count.value = 0; history.value = []; }

  return { count, history, doubleCount, isPositive, increment, fetchAndSet, $reset };
});

// src/stores/user.ts — Options Store style
export const useUserStore = defineStore('user', {
  state: () => ({ name: '', email: '', isLoggedIn: false }),
  getters: {
    displayName: (state) => state.name || 'Guest',
  },
  actions: {
    async login(email: string, password: string) {
      const user = await authService.login(email, password);
      this.name = user.name;
      this.email = user.email;
      this.isLoggedIn = true;
    },
    logout() {
      this.$patch({ name: '', email: '', isLoggedIn: false });
    },
  },
});

<script setup lang="ts">
import { storeToRefs } from 'pinia';
import { useCounterStore } from '@/stores/counter';

const counterStore = useCounterStore();

// storeToRefs preserves reactivity for state + getters
const { count, doubleCount, isPositive } = storeToRefs(counterStore);

// Actions can be destructured directly (they are not reactive)
const { increment, fetchAndSet } = counterStore;

// Batch update with $patch
counterStore.$patch({ count: 10 });

// $patch with mutation function for complex updates
counterStore.$patch((state) => {
  state.count += 5;
  state.history.push(state.count);
});

// Subscribe to store changes
counterStore.$subscribe((mutation, state) => {
  console.log('Store mutated:', mutation.type, state.count);
  localStorage.setItem('counter', JSON.stringify(state));
});
</script>

<template>
  <p>Count: {{ count }} | Double: {{ doubleCount }}</p>
  <button @click="increment">Increment</button>
</template>

<template>
  <!-- v-if / v-else-if / v-else: element destroyed+recreated -->
  <div v-if="role === 'admin'">Admin Panel</div>
  <div v-else-if="role === 'editor'">Editor Panel</div>
  <div v-else>Viewer Panel</div>

  <!-- v-show: always rendered, toggles display:none -->
  <div v-show="isExpanded">Expandable Content</div>

  <!-- v-for with :key (use unique ID, not array index) -->
  <ul>
    <li v-for="item in items" :key="item.id">
      {{ item.name }} — ${{ item.price }}
    </li>
  </ul>

  <!-- v-for with index -->
  <ol>
    <li v-for="(item, index) in items" :key="item.id">
      {{ index + 1 }}. {{ item.name }}
    </li>
  </ol>

  <!-- v-for on a range -->
  <span v-for="n in 5" :key="n">{{ n }} </span>

  <!-- Use <template> to group without extra DOM elements -->
  <template v-for="item in items" :key="item.id">
    <dt>{{ item.term }}</dt>
    <dd>{{ item.definition }}</dd>
  </template>
</template>

<script setup lang="ts">
import { ref } from 'vue';
const inputValue = ref('');
const isChecked = ref(false);
const selected = ref('option1');
</script>

<template>
  <!-- Basic v-model on input -->
  <input v-model="inputValue" type="text" />

  <!-- v-model modifiers -->
  <input v-model.trim="inputValue" /> <!-- trims whitespace -->
  <input v-model.number="price" type="number" /> <!-- coerce to number -->
  <input v-model.lazy="search" /> <!-- sync on change, not input -->

  <!-- v-bind shorthand: -->
  <img :src="user.avatar" :alt="user.name" />
  <button :disabled="isLoading">{{ isLoading ? 'Loading...' : 'Submit' }}</button>

  <!-- Bind object of attributes -->
  <div v-bind="{ id: 'main', class: 'container', tabindex: 0 }">...</div>

  <!-- v-on shorthand @ -->
  <button @click="handleClick">Click</button>
  <form @submit.prevent="handleSubmit">...</form>
  <input @keyup.enter="search" @keyup.escape="clearSearch" />
  <div @click.self="onOverlayClick">...</div> <!-- only fires on exact element -->

  <!-- v-model on custom component (Vue 3) -->
  <!-- Expands to: :modelValue="title" @update:modelValue="title = $event" -->
  <MyInput v-model="title" />

  <!-- Multiple v-model bindings -->
  <UserForm v-model:name="user.name" v-model:email="user.email" />
</template>

// src/composables/useFetch.ts
import { ref, watchEffect, type Ref } from 'vue';

interface UseFetchReturn<T> {
  data: Ref<T | null>;
  error: Ref<Error | null>;
  isLoading: Ref<boolean>;
  refetch: () => void;
}

export function useFetch<T>(url: Ref<string> | string): UseFetchReturn<T> {
  const data = ref<T | null>(null);
  const error = ref<Error | null>(null);
  const isLoading = ref(false);
  let controller: AbortController;

  async function fetchData() {
    controller?.abort(); // cancel previous request
    controller = new AbortController();
    isLoading.value = true;
    error.value = null;
    try {
      const endpoint = typeof url === 'string' ? url : url.value;
      const res = await fetch(endpoint, { signal: controller.signal });
      if (!res.ok) throw new Error('HTTP ' + res.status);
      data.value = await res.json() as T;
    } catch (e) {
      if ((e as Error).name !== 'AbortError') error.value = e as Error;
    } finally {
      isLoading.value = false;
    }
  }

  watchEffect(() => { fetchData(); });

  return { data, error, isLoading, refetch: fetchData };
}

// Usage in component
<script setup lang="ts">
import { ref } from 'vue';
import { useFetch } from '@/composables/useFetch';

interface User { id: number; name: string; email: string; }

const userId = ref(1);
const url = computed(() => '/api/users/' + userId.value);
const { data: user, isLoading, error } = useFetch<User>(url);
</script>

<!-- Modal component using Teleport -->
<script setup lang="ts">
defineProps<{ isOpen: boolean; title: string }>();
defineEmits<{ close: [] }>();
</script>

<template>
  <!-- Renders at document.body, not in component tree -->
  <Teleport to="body">
    <div v-if="isOpen" class="modal-overlay" @click.self="$emit('close')">
      <div class="modal">
        <h2>{{ title }}</h2>
        <slot />
        <button @click="$emit('close')">Close</button>
      </div>
    </div>
  </Teleport>
</template>

<!-- Suspense + defineAsyncComponent -->
<script setup lang="ts">
import { defineAsyncComponent } from 'vue';

const HeavyChart = defineAsyncComponent({
  loader: () => import('./HeavyChart.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200,        // show loading after 200ms
  timeout: 10000,    // error after 10s
});
</script>

<template>
  <!-- Suspense with fallback slot -->
  <Suspense>
    <template #default>
      <HeavyChart :data="chartData" />
    </template>
    <template #fallback>
      <div>Loading chart...</div>
    </template>
  </Suspense>
</template>

我应该从 Vue 2 迁移到 Vue 3 吗？

是的——Vue 2 于 2023 年 12 月 31 日达到生命周期终点，意味着不再有安全补丁或 bug 修复。迁移难度取决于代码库大小。中小型项目可以使用 @vue/compat 迁移构建直接迁移，该构建启用具有 Vue 2 兼容行为的 Vue 3，并对废弃 API 提供控制台警告。大型项目应规划分阶段迁移：首先更新到 Vue 2.7（它向后移植了 Composition API），然后迁移到 Vue 3。主要破坏性变更：Options API 在 Vue 3 中仍然有效，但 filters 被删除，$on/$off/$once 被删除，一些指令语法发生了变化。

Composition API 和 Options API 有什么区别？

Options API 将组件逻辑组织到预定义的选项桶中：data、methods、computed、watch、mounted 等。这很熟悉，对简单组件有效，但随着相关逻辑散布在多个选项中，可能使大型组件难以理解。Composition API 使用 setup()（或 script setup）作为单一入口点，在那里按功能而非按选项类型组织逻辑。"用户搜索"功能的状态、计算值和 fetch 逻辑都可以放在一起。Composition API 还实现了更好的 TypeScript 推断和用于逻辑复用的组合式函数。两个 API 在 Vue 3 中都完全支持——甚至可以在同一组件中混合使用。

Vue 3 对 TypeScript 支持好吗？

Vue 3 具有出色的 TypeScript 支持。整个 Vue 3 框架用 TypeScript 编写。带有 defineProps<Props>() 的 script setup 语法为 props 提供完整的泛型类型推断。Composition API 提供自然的 TypeScript 集成——ref<string>()、computed<number>() 和类型化的响应式对象都支持完整的 IDE 自动补全。Pinia 完全是 TypeScript 原生的。Volar（官方 VSCode 扩展）提供与 Angular 类型系统相媲美的模板类型检查和自动补全。对于新项目，Vue 3 + TypeScript + Volar 提供一流的类型化开发体验。

Nuxt 3 是什么，什么时候应该使用它？

Nuxt 3 是全栈 Vue 框架，类似于 React 的 Next.js。它构建在 Vue 3、Vite 和 Nitro（通用服务器引擎）之上。Nuxt 3 提供服务器端渲染（SSR）以改善 SEO 和初始加载性能、静态站点生成（SSG）、基于文件的路由、Vue/Pinia/VueUse 组合式函数的自动导入、服务器 API 层（类似于 Next.js API 路由）以及同构数据获取（useFetch、useAsyncData）。当 SEO 重要时（营销网站、电商、博客）、当你需要与前端协同定位的后端 API 时，或当你想要内置电池的 Vue 3 体验时，使用 Nuxt 3。

Vue 3 响应性在底层是如何工作的？

Vue 3 响应性基于 ES6 Proxy。当你创建 reactive() 对象时，Vue 用带有 get/set 拦截器的 Proxy 包装它。当 computed 属性或 watch effect 访问响应式属性时（get 拦截器），Vue 将其追踪为依赖项。当你更新属性时（set 拦截器），Vue 通知所有追踪的依赖项。ref() 类似地工作——它将值包装在带有 .value getter/setter 的对象中。这种基于 Proxy 的方式消除了 Vue 2 的限制：不需要显式 Vue.set() 的深度响应性、数组索引修改有效、添加到对象的新属性是响应式的。Computed 值是记忆化惰性的：只有在依赖项变化且 computed 被访问时才计算。

Vue 3 中什么取代了 Vuex？

Pinia 是 Vue 3 中 Vuex 的官方替代品，由 Vue 核心团队推荐。它由 Eduardo San Martin Morote（Vue 核心团队成员）创建，围绕 Vue 3 Composition API 设计。与 Vuex 的主要区别：没有 mutations（只有 state、getters 和 actions）、无需复杂类型解决方案的完整 TypeScript 支持、没有嵌套模块（只是可以相互导入的独立 store）、更轻量的 API，以及原生 Vue DevTools 集成。Vuex 4 仍然适用于 Vue 3，但处于维护模式——所有新项目应使用 Pinia。

我可以在没有构建步骤的情况下使用 Vue 3 吗？

可以——Vue 3 可以作为纯 CDN 脚本使用，用于现有 HTML 页面的渐进增强，不需要构建工具。全局构建（vue.global.js）在 Vue 全局上暴露所有 API。ESM 浏览器构建（vue.esm-browser.js）可以直接在原生 ES 模块中使用。对于使用单文件组件（.vue 文件）的复杂应用，你需要构建步骤——Vite 是推荐工具，提供近乎即时的开发服务器启动、亚秒级热模块替换和优化的生产构建。Vue Playground（play.vuejs.org）让你无需任何设置即可在线试用 Vue 3。

v-if 和 v-show 有什么区别？

当条件变化时，v-if 完全渲染或销毁元素及其子元素。当为 false 时，元素不存在于 DOM 中——它运行生命周期钩子（onMounted/onUnmounted），处理子组件的创建/销毁，并具有更高的切换成本。v-show 始终渲染元素但切换 CSS display:none。它具有更低的切换成本但更高的初始渲染成本（始终渲染）。当条件很少变化或想要懒渲染重量级组件时使用 v-if。对于频繁切换的内容（标签页、手风琴），在想要避免重新渲染成本时使用 v-show。