> ## 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 入门指南 - URL: https://blog.vercanti.com/vue-3-ru-men-zhi-nan/ - Published: 2026-08-28T14:35:28.000Z - Updated: 2026-08-28T14:58:52.000Z - Description: 1. Vue 是什么(#vue-%E6%98%AF%E4%BB%80%E4%B9%88) 2. 安装与项目创建(#%E5%AE%89%E8%A3%85%E4%B8%8E%E9%A1%B9%E7%9B%AE%E5%88%9B%E5%BB%BA) 3. 项目结构(#%E9%A1%B9%E7%9B%AE%E7%BB%93%E6%9E%84) 4. .vue 文件结构(#vue-%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84) 5. 响应式基础(#%E5%93%8D%E5%BA%94%E5%BC%8F%E5%9F%BA%E7%A1%80 - Author: yellowdog - Tags: 前端开发, Vue生态 > 官方文档： > 最后更新：2026-03-05 --- ## 目录 1. [Vue 是什么](#vue-%E6%98%AF%E4%BB%80%E4%B9%88) 2. [安装与项目创建](#%E5%AE%89%E8%A3%85%E4%B8%8E%E9%A1%B9%E7%9B%AE%E5%88%9B%E5%BB%BA) 3. [项目结构](#%E9%A1%B9%E7%9B%AE%E7%BB%93%E6%9E%84) 4. [.vue 文件结构](#vue-%E6%96%87%E4%BB%B6%E7%BB%93%E6%9E%84) 5. [响应式基础](#%E5%93%8D%E5%BA%94%E5%BC%8F%E5%9F%BA%E7%A1%80) 6. [模板语法](#%E6%A8%A1%E6%9D%BF%E8%AF%AD%E6%B3%95) 7. [组件系统](#%E7%BB%84%E4%BB%B6%E7%B3%BB%E7%BB%9F) 8. [生命周期](#%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F) 9. [响应式工具函数](#%E5%93%8D%E5%BA%94%E5%BC%8F%E5%B7%A5%E5%85%B7%E5%87%BD%E6%95%B0) 10. [内置组件](#%E5%86%85%E7%BD%AE%E7%BB%84%E4%BB%B6) 11. [Vue Router 基础](#vue-router-%E5%9F%BA%E7%A1%80) 12. [Pinia 状态管理](#pinia-%E7%8A%B6%E6%80%81%E7%AE%A1%E7%90%86) 13. [综合实战：博客列表应用](#%E7%BB%BC%E5%90%88%E5%AE%9E%E6%88%98%EF%BC%9A%E5%8D%9A%E5%AE%A2%E5%88%97%E8%A1%A8%E5%BA%94%E7%94%A8) --- ## Vue 是什么 Vue 是一个用于构建用户界面的渐进式 JavaScript 框架。"渐进式"意味着你可以只用它的一小部分功能，也可以将其作为完整的前端解决方案。 ### MVVM 概念 MVVM 是一种软件架构模式，分为三层： | 层级 | 全称 | 作用 | | -- | --------------- | --------------------------- | | M | Model（模型） | 应用的数据和业务逻辑 | | V | View（视图） | 用户看到的界面（HTML/DOM） | | VM | ViewModel（视图模型） | 连接 Model 和 View，Vue 实例充当此角色 | Vue 的核心是**数据驱动视图**：你只需要修改数据，界面会自动更新，不需要手动操作 DOM。 ``` 数据（Model） <--双向绑定--> Vue 实例（ViewModel） <--自动渲染--> 界面（View） ``` ### 虚拟 DOM 虚拟 DOM（Virtual DOM）是 Vue 在内存中维护的一棵 JavaScript 对象树，用来描述真实 DOM 的结构。 工作原理： 1. 数据发生变化时，Vue 先生成新的虚拟 DOM 树 2. 与旧的虚拟 DOM 树进行对比（diff 算法） 3. 找出最小差异，只更新真实 DOM 中变化的部分 好处：避免不必要的 DOM 操作（DOM 操作开销大），提升性能。 --- ## 安装与项目创建 ### 方式一：CDN 引入（适合快速体验） ```html Vue 3 CDN 示例

{{ message }}

``` ### 方式二：create-vue 脚手架（推荐，基于 Vite） **前提条件**：已安装 Node.js（推荐 18.0 以上版本）。 ```bash # 创建项目，会交互式询问配置选项 npm create vue@latest # 进入项目目录（my-vue-app 是你填写的项目名） cd my-vue-app # 安装依赖 npm install # 启动开发服务器 npm run dev ``` 运行 `npm create vue@latest` 后，会询问以下选项： ``` 项目名称: my-vue-app 是否添加 TypeScript? No（初学者选 No） 是否添加 JSX 支持? No 是否添加 Vue Router? Yes 是否添加 Pinia? Yes 是否添加 Vitest 单元测试? No 是否添加端到端测试? No 是否添加 ESLint? Yes ``` --- ## 项目结构 ``` my-vue-app/ ├── public/ # 静态资源，直接复制到构建输出，不经过处理 │ └── favicon.ico ├── src/ # 源代码目录 │ ├── assets/ # 需要处理的静态资源（图片、字体等） │ ├── components/ # 可复用组件 │ │ └── HelloWorld.vue │ ├── router/ # Vue Router 配置 │ │ └── index.js │ ├── stores/ # Pinia 状态管理 │ │ └── counter.js │ ├── views/ # 页面级组件（与路由对应） │ │ └── HomeView.vue │ ├── App.vue # 根组件，整个应用的入口组件 │ └── main.js # 应用入口文件，创建并挂载 Vue 实例 ├── index.html # HTML 入口文件 ├── package.json # 项目依赖与脚本配置 └── vite.config.js # Vite 构建工具配置 ``` ### main.js 说明 ```javascript import { createApp } from 'vue' import { createPinia } from 'pinia' import App from './App.vue' import router from './router' // 创建 Vue 应用实例 const app = createApp(App) // 安装插件 app.use(createPinia()) // 注册 Pinia 状态管理 app.use(router) // 注册路由 // 将应用挂载到 index.html 中 id 为 app 的元素上 app.mount('#app') ``` --- ## .vue 文件结构 `.vue` 文件是 Vue 的单文件组件（Single File Component，SFC），将模板、逻辑、样式写在同一个文件中。 ```vue ``` ### Composition API vs Options API 对比 Vue 3 推荐使用 Composition API，Vue 2 使用 Options API。两者都能完成同样的工作，但 Composition API 逻辑组织更灵活，适合复杂组件。 ```vue ``` --- ## 响应式基础 ### ref() `ref()` 用于创建一个响应式的数据引用，适合基本类型（number、string、boolean）和单个值。 **参数说明：** | 参数 | 类型 | 必填 | 说明 | | ----- | --- | -- | ----------- | | value | any | 是 | 初始值，可以是任意类型 | **返回值**：一个 Ref 对象，通过 `.value` 访问和修改内部值。 ```vue ``` ### reactive() `reactive()` 用于创建一个响应式对象，适合对象和数组。 **参数说明：** | 参数 | 类型 | 必填 | 说明 | | ------ | -------------- | -- | ------------ | | object | object / array | 是 | 要变为响应式的对象或数组 | **返回值**：原始对象的响应式代理（Proxy）。 ```vue ``` **reactive() 的局限性：** ```javascript import { reactive } from 'vue' const state = reactive({ count: 0 }) // 错误：解构会失去响应性 const { count } = state // count 不再是响应式的 // 错误：直接替换整个对象，响应性断开 // state = reactive({ count: 1 }) // 这样做不行 // 正确：使用 toRefs 解构，或直接通过 state.xxx 访问 import { toRefs } from 'vue' const { count } = toRefs(state) // count 现在是 ref，保持响应性 ``` ### computed() `computed()` 用于声明派生自其他响应式数据的计算属性，具有缓存特性：只有依赖数据变化时才重新计算。 **参数说明：** | 参数 | 类型 | 必填 | 说明 | | ------- | -------------------------------- | ------- | ------------------ | | getter | Function | 是（简写形式） | 返回计算值的函数 | | options | { get: Function, set: Function } | 是（完整形式） | 包含 getter 和 setter | ```vue ``` ### watch() `watch()` 用于监听响应式数据的变化，执行副作用（如发起请求、操作 DOM）。 **参数说明：** | 参数 | 类型 | 必填 | 说明 | | -------- | --------------------------------------- | -- | ---------- | | source | Ref / reactive对象 / getter函数 / 数组 | 是 | 要监听的数据源 | | callback | (newValue, oldValue, onCleanup) => void | 是 | 数据变化时执行的回调 | | options | WatchOptions 对象 | 否 | 配置选项，见下表 | **options 配置项：** | 选项 | 类型 | 默认值 | 说明 | | --------- | ----------------------- | ----- | --------------------------- | | immediate | boolean | false | 是否在创建时立即执行一次回调 | | deep | boolean | false | 是否深度监听对象内部变化 | | flush | 'pre' / 'post' / 'sync' | 'pre' | 回调执行时机，'post' 表示在 DOM 更新后执行 | | once | boolean | false | 是否只触发一次 | ```vue ``` ### watchEffect() `watchEffect()` 自动追踪回调中用到的所有响应式数据，任意一个变化就重新执行。 **参数说明：** | 参数 | 类型 | 必填 | 说明 | | ------- | ----------------------------- | -- | ------------- | | effect | (onCleanup: Function) => void | 是 | 副作用函数，会立即执行一次 | | options | { flush, onTrack, onTrigger } | 否 | 配置选项 | ```vue ``` **watch() 与 watchEffect() 的区别：** | 对比项 | watch() | watchEffect() | | ----- | ------------------------- | ------------- | | 数据源声明 | 需要明确指定监听的数据源 | 自动追踪，无需声明 | | 初次执行 | 默认不立即执行（immediate: false） | 立即执行 | | 访问旧值 | 可以通过回调参数获取旧值 | 无法获取旧值 | | 适用场景 | 需要对比新旧值，或懒执行的情况 | 依赖多个数据，只关心副作用 | --- ## 模板语法 ### 文本插值 ```vue ``` ### v-bind（绑定属性） ```vue ``` ### v-if / v-else-if / v-else 与 v-show ```vue ``` **v-if 与 v-show 的区别：** | 对比项 | v-if | v-show | | ------ | --------------- | --------------------- | | DOM 行为 | false 时从 DOM 移除 | false 时 display: none | | 初始渲染成本 | 低（false 时不渲染） | 高（总是渲染） | | 切换成本 | 高（需要销毁/重建） | 低（只改 CSS） | | 适用场景 | 很少切换的条件显示 | 频繁切换的显示隐藏 | ### v-for（列表渲染） ```vue ``` **key 的作用：** `key` 是 Vue 用来识别 v-for 中每个节点的唯一标识。有了 key，Vue 在更新列表时可以复用现有 DOM 节点（移动、更新），而不是全部重新创建，性能更好。key 应使用稳定的唯一 ID，不推荐用数组索引（index），因为删除/排序后索引会变化，导致意外行为。 ### v-on（事件绑定） ```vue ``` **常用事件修饰符：** | 修饰符 | 说明 | | -------- | ---------------------------------------- | | .prevent | event.preventDefault()，阻止默认行为（如表单提交刷新页面） | | .stop | event.stopPropagation()，阻止事件冒泡 | | .once | 事件只触发一次 | | .self | 只有事件在元素本身触发时才处理（不包括子元素触发的冒泡） | | .capture | 使用事件捕获模式 | **常用键盘修饰符：** | 修饰符 | 说明 | | ----------------------------- | -------------------- | | .enter | Enter 键 | | .tab | Tab 键 | | .delete | Delete 或 Backspace 键 | | .esc | Escape 键 | | .space | 空格键 | | .up / .down / .left / .right | 方向键 | | .ctrl / .alt / .shift / .meta | 系统修饰键 | ### v-model（双向绑定） ```vue ``` ### v-slot（插槽） 插槽用于向子组件传递模板内容，在"组件系统"章节有完整示例。 ```vue ``` --- ## 组件系统 ### 创建与局部注册组件 ```vue ``` ```vue ``` ### props（父传子） **defineProps() 参数说明：** | 参数 | 类型 | 说明 | | --------- | -------------- | --------------------------------------------------- | | type | 构造函数或数组 | 期望的类型，如 String、Number、Boolean、Array、Object、Function | | required | boolean | 是否必填，默认 false | | default | any / Function | 默认值（对象/数组类型必须用工厂函数返回） | | validator | Function | 自定义验证函数，返回 true/false | ```vue ``` ### emit（子传父） ```vue ``` ```vue ``` ### 插槽（slot） ```vue ``` ```vue ``` ### provide / inject（跨层级传值） ```vue ``` ```vue ``` --- ## 生命周期 ### 生命周期钩子 每个 Vue 组件实例在创建和销毁过程中会经历一系列阶段，每个阶段都有对应的钩子函数可以执行自定义代码。 ```vue ``` ### 与 Options API 生命周期对应关系 | Composition API | Options API | 触发时机 | | ---------------- | ------------- | --------------- | | onBeforeMount | beforeMount | 组件挂载前，DOM 不存在 | | onMounted | mounted | 组件挂载后，可访问 DOM | | onBeforeUpdate | beforeUpdate | 数据变化，DOM 更新前 | | onUpdated | updated | 数据变化，DOM 更新后 | | onBeforeUnmount | beforeDestroy | 组件卸载前 | | onUnmounted | destroyed | 组件卸载后 | | onErrorCaptured | errorCaptured | 子孙组件报错时 | | onActivated | activated | KeepAlive 激活时 | | onDeactivated | deactivated | KeepAlive 停用时 | | （无，用 setup() 本身） | created | 实例创建后，响应式数据已初始化 | | （无，用 setup() 本身） | beforeCreate | 实例创建前 | 注意：在 ` ``` ### isRef / isReactive / unref ```vue ``` ### readonly ```vue ``` --- ## 内置组件 ### Transition（过渡动画） **Transition 参数说明：** | 属性 | 类型 | 默认值 | 说明 | | ------ | -------------------------- | ----- | ------------------ | | name | string | 'v' | 过渡类名前缀 | | mode | 'in-out' / 'out-in' | 无 | 过渡模式，out-in 表示先出后入 | | appear | boolean | false | 初始渲染时是否应用过渡 | | type | 'transition' / 'animation' | 自动 | 指定监听哪种 CSS 事件 | ```vue ``` **CSS 过渡类名说明：** | 类名 | 触发时机 | | -------------- | --------- | | v-enter-from | 进入动画的起始帧 | | v-enter-active | 进入动画的整个过程 | | v-enter-to | 进入动画的结束帧 | | v-leave-from | 离开动画的起始帧 | | v-leave-active | 离开动画的整个过程 | | v-leave-to | 离开动画的结束帧 | 注：`v-` 是默认前缀，使用 `name="fade"` 时变为 `fade-`。 ### TransitionGroup（列表动画） ```vue ``` ### KeepAlive（组件缓存） KeepAlive 可以缓存组件实例，避免组件切换时重新创建和销毁，保留组件的状态。 **KeepAlive 参数说明：** | 属性 | 类型 | 说明 | | ------- | ----------------------- | ----------------------- | | include | string / RegExp / Array | 只缓存名字匹配的组件 | | exclude | string / RegExp / Array | 不缓存名字匹配的组件 | | max | number | 最多缓存多少个组件实例，超出时销毁最久未访问的 | ```vue ``` 被 KeepAlive 缓存的组件需要通过 `defineOptions` 设置组件名，才能被 `include/exclude` 识别： ```vue ``` ### Teleport（传送门） Teleport 可以将组件模板的一部分"传送"到 DOM 中的其他位置（比如 `body`），常用于模态框、提示框等。 **Teleport 参数说明：** | 属性 | 类型 | 必填 | 说明 | | -------- | -------------------- | -- | -------------------------- | | to | string / HTMLElement | 是 | 目标 DOM 元素的 CSS 选择器或 DOM 节点 | | disabled | boolean | 否 | 是否禁用传送（禁用时渲染在原位置） | ```vue ``` --- ## Vue Router 基础 ### 安装与配置 ```bash npm install vue-router@4 ``` ```javascript // src/router/index.js import { createRouter, createWebHistory, createWebHashHistory } from 'vue-router' import HomeView from '@/views/HomeView.vue' const routes = [ { path: '/', // URL 路径 name: 'home', // 路由名称（可选，但推荐） component: HomeView // 对应的组件 }, { path: '/about', name: 'about', // 懒加载：只在访问此路由时才加载组件，减小初始包体积 component: () => import('@/views/AboutView.vue') }, { // 动态路由参数，:id 会匹配任意值 path: '/post/:id', name: 'post-detail', component: () => import('@/views/PostDetail.vue') }, { // 嵌套路由 path: '/user', component: () => import('@/views/UserLayout.vue'), children: [ { path: '', // 空路径匹配 /user name: 'user-home', component: () => import('@/views/UserHome.vue') }, { path: 'profile', // 匹配 /user/profile name: 'user-profile', component: () => import('@/views/UserProfile.vue') } ] }, { // 重定向 path: '/old-path', redirect: '/new-path' }, { // 404 页面，匹配所有未匹配的路径 path: '/:pathMatch(.*)*', name: 'not-found', component: () => import('@/views/NotFound.vue') } ] const router = createRouter({ // createWebHistory：使用 HTML5 History 模式，URL 没有 # 号（需要服务器配置） // createWebHashHistory：使用 Hash 模式，URL 有 # 号，不需要服务器配置 history: createWebHistory(import.meta.env.BASE_URL), routes }) export default router ``` **History 模式对比：** | 模式 | URL 示例 | 优点 | 缺点 | | -------------------- | -------- | ------------ | ------------------------ | | createWebHistory | /about | URL 简洁美观 | 需要服务器配置，直接访问子路径时不能返回 404 | | createWebHashHistory | /#/about | 无需服务器配置，兼容性好 | URL 不美观，SEO 较差 | ### RouterView 与 RouterLink ```vue ``` ### useRouter / useRoute ```vue ``` ### 路由守卫 ```javascript // src/router/index.js // 全局前置守卫：每次路由跳转前执行 router.beforeEach((to, from, next) => { // to：即将进入的路由 // from：正在离开的路由 // next：调用此函数来 resolve 守卫 const isLoggedIn = localStorage.getItem('token') // 路由元信息 meta.requiresAuth 标记需要登录的路由 if (to.meta.requiresAuth && !isLoggedIn) { // 未登录，跳转到登录页，并记录来源页 next({ name: 'login', query: { redirect: to.fullPath } }) } else { next() // 正常放行 } }) // 全局后置守卫：路由跳转完成后执行（没有 next 参数） router.afterEach((to, from) => { // 修改页面标题 document.title = to.meta.title || '默认标题' }) ``` 在路由配置中添加 meta： ```javascript const routes = [ { path: '/dashboard', name: 'dashboard', component: () => import('@/views/Dashboard.vue'), meta: { requiresAuth: true, // 需要登录 title: '控制台' } } ] ``` ### params vs query ```javascript // params：动态路由参数，是路径的一部分 // 路由配置：{ path: '/post/:id' } router.push({ name: 'post-detail', params: { id: 123 } }) // URL：/post/123 // 组件中获取：route.params.id → '123'（字符串） // query：查询字符串，附加在 URL 后面 router.push({ path: '/search', query: { keyword: 'vue', page: 2 } }) // URL：/search?keyword=vue&page=2 // 组件中获取：route.query.keyword → 'vue'，route.query.page → '2' ``` --- ## Pinia 状态管理 Pinia 是 Vue 官方推荐的状态管理库，用于在多个组件之间共享状态。 ### 安装与配置 ```bash npm install pinia ``` 已在 main.js 中配置（见"项目结构"章节）。 ### defineStore ```javascript // src/stores/userStore.js import { defineStore } from 'pinia' import { ref, computed } from 'vue' // defineStore 参数： // 第一个参数：store 的唯一 ID（字符串），用于 devtools 识别 // 第二个参数：setup 函数（Composition API 风格，推荐） export const useUserStore = defineStore('user', () => { // state：响应式数据 const currentUser = ref(null) const token = ref(localStorage.getItem('token') || '') const loading = ref(false) // getters：计算属性 const isLoggedIn = computed(() => !!token.value) const username = computed(() => currentUser.value?.name || '游客') // actions：方法（可以是异步的） async function login(username, password) { loading.value = true try { const response = await fetch('/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username, password }) }) const data = await response.json() token.value = data.token currentUser.value = data.user localStorage.setItem('token', data.token) } catch (error) { console.error('登录失败：', error) throw error } finally { loading.value = false } } function logout() { token.value = '' currentUser.value = null localStorage.removeItem('token') } // 返回所有需要暴露的内容 return { currentUser, token, loading, isLoggedIn, username, login, logout } }) ``` 也可以用 Options 风格定义（与 Vue 2 的 Vuex 更接近）： ```javascript // Options 风格（了解即可） export const useCounterStore = defineStore('counter', { state: () => ({ count: 0 }), getters: { doubled: (state) => state.count * 2 }, actions: { increment() { this.count++ } } }) ``` ### 在组件中使用 Store ```vue ``` ### 与 Vuex 的对比 | 对比项 | Pinia | Vuex 4（Vue 3 版） | | ------------- | -------------------------- | ---------------------------------- | | 模板文件结构 | store、getters、actions 扁平结构 | state、getters、mutations、actions 四层 | | 修改状态 | 直接修改或在 action 中修改 | 必须通过 mutation（同步）才能修改 | | TypeScript 支持 | 原生支持，类型推断好 | 需要额外配置 | | 模块化 | 每个 store 文件是独立模块 | 需要显式 modules 配置 | | devtools | 支持 | 支持 | | 代码量 | 更少 | 更多（需要写 mutation） | --- ## 综合实战：博客列表应用 本节实现一个包含路由、Pinia 状态管理、父子组件通信、数据请求的完整应用。 ### 项目结构 ``` src/ ├── components/ │ ├── PostCard.vue # 文章卡片组件（子组件） │ └── LoadingSpinner.vue # 加载动画组件 ├── views/ │ ├── HomeView.vue # 首页（文章列表） │ └── PostDetail.vue # 文章详情页 ├── stores/ │ └── postsStore.js # 文章状态管理 └── router/ └── index.js # 路由配置 ``` ### 路由配置 ```javascript // src/router/index.js import { createRouter, createWebHistory } from 'vue-router' const routes = [ { path: '/', name: 'home', component: () => import('@/views/HomeView.vue'), meta: { title: '博客列表' } }, { path: '/post/:id', name: 'post-detail', component: () => import('@/views/PostDetail.vue'), meta: { title: '文章详情' } } ] const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes }) router.afterEach((to) => { document.title = to.meta.title || '我的博客' }) export default router ``` ### Pinia Store ```javascript // src/stores/postsStore.js import { defineStore } from 'pinia' import { ref, computed } from 'vue' export const usePostsStore = defineStore('posts', () => { const posts = ref([]) const currentPost = ref(null) const loading = ref(false) const error = ref(null) // 使用 JSONPlaceholder 提供的免费 API const API_BASE = 'https://jsonplaceholder.typicode.com' const postCount = computed(() => posts.value.length) async function fetchPosts() { loading.value = true error.value = null try { const response = await fetch(`${API_BASE}/posts?_limit=10`) if (!response.ok) throw new Error('请求失败') posts.value = await response.json() } catch (err) { error.value = err.message } finally { loading.value = false } } async function fetchPostById(id) { loading.value = true error.value = null currentPost.value = null try { const [postResponse, commentsResponse] = await Promise.all([ fetch(`${API_BASE}/posts/${id}`), fetch(`${API_BASE}/posts/${id}/comments`) ]) const post = await postResponse.json() const comments = await commentsResponse.json() currentPost.value = { ...post, comments } } catch (err) { error.value = err.message } finally { loading.value = false } } return { posts, currentPost, loading, error, postCount, fetchPosts, fetchPostById } }) ``` ### 文章卡片组件（子组件） ```vue ``` ### 加载动画组件 ```vue ``` ### 首页（文章列表） ```vue ``` ### 文章详情页 ```vue ``` --- ## 注意事项与常见误区 ### ref 相关 - 在 `