Vue / 知识点
Vue 3 开发速查手册
手册条目
使用子路由和 RouterView 构建共享布局页面。
配置嵌套路由
当多个页面需要共用侧边栏、顶部导航或面包屑时,把共享部分放进父级布局组件,再由子路由填充布局内的 RouterView。访问 /admin/users 时,外层渲染 AdminLayout,内层渲染 UsersView。
路由结构
父路由负责匹配公共路径和加载布局,子路由的 path 默认相对父路径拼接。默认子页面使用空字符串 path: "",不要写成 /;带前导斜杠的子路径会被当作根路径,失去父路径前缀。

基本配置
片段示例,依赖已安装 vue-router@4,并已有 AdminLayout.vue、DashboardView.vue 和 UsersView.vue。在 src/router/index.ts 中定义父子路由:
import { createRouter, createWebHistory } from "vue-router"
import AdminLayout from "@/layouts/AdminLayout.vue"
import DashboardView from "@/views/admin/DashboardView.vue"
import UsersView from "@/views/admin/UsersView.vue"
export const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{
path: "/admin",
component: AdminLayout,
children: [
// 空路径表示访问 /admin 时显示默认子页面
{ path: "", name: "admin-home", component: DashboardView },
{ path: "users", name: "admin-users", component: UsersView }
]
}
]
})父布局必须保留子路由出口:
<script setup lang="ts">
import { RouterLink, RouterView } from "vue-router"
</script>
<template>
<section>
<nav>
<RouterLink :to="{ name: 'admin-home' }">概览</RouterLink>
<RouterLink :to="{ name: 'admin-users' }">用户</RouterLink>
</nav>
<RouterView />
</section>
</template>预期结果:打开 /admin 显示共享导航和概览页;打开 /admin/users 时共享导航不变,只有内层内容切换为用户页。浏览器控制台不应出现 No match found 或组件加载错误。
高频用法
需要多层布局时继续在子路由中声明 children,但每一级布局都必须提供自己的 RouterView。需要详情页时使用相对动态路径,例如 { path: "users/:id", component: UserDetailView },最终地址为 /admin/users/<ID>。
需要让父地址只负责跳转时,可以给父记录添加 redirect: { name: "admin-home" };若已经配置空路径默认子路由,通常不再需要重复重定向。
风险与排障
- 子路由写成
/users时会匹配根地址/users,后果是布局关系与预期不一致;安全做法是删除前导斜杠。 - 页面只显示父布局时,先检查父布局是否遗漏
<RouterView />,再检查子组件导入路径和默认导出。 - 刷新
/admin/users返回服务器 404,说明静态服务器没有回退到index.html;应配置 SPA history fallback,或在无法控制服务器时改用createWebHashHistory()。 - 链接跳转异常时优先使用命名路由,避免手写路径时漏掉父级前缀。
兼容 Vue 3 与 Vue Router 4;Vue Router 3 的配置对象相似,但对应 Vue 2,不能与 Vue 3 项目混用。
在路由进入或离开前执行登录校验、确认和重定向。
添加导航守卫
当页面需要登录校验、按条件重定向,或在用户离开未保存表单前二次确认时,使用 Vue Router 4 导航守卫。守卫必须明确返回“继续、取消或跳转”,避免导航悬空或形成重定向循环。
守卫流程
一次导航可能同时经过全局校验和组件离开确认。登录校验适合放在全局 beforeEach,只对单个路由生效的规则可放在 beforeEnter,表单离开确认放在组件内的 onBeforeRouteLeave。

全局登录校验
片段示例,依赖现有路由组件。受保护路由通过 meta.requiresAuth 声明权限要求,守卫读取登录令牌并把原目标地址写入查询参数:
import { createRouter, createWebHistory } from "vue-router"
import HomeView from "@/views/HomeView.vue"
import LoginView from "@/views/LoginView.vue"
import AdminView from "@/views/AdminView.vue"
export const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{ path: "/", name: "home", component: HomeView },
{ path: "/login", name: "login", component: LoginView },
{
path: "/admin",
name: "admin",
component: AdminView,
meta: { requiresAuth: true }
}
]
})
router.beforeEach((to) => {
const token = localStorage.getItem("access_token")
// 登录页本身不能再次触发登录重定向,否则会循环
if (to.meta.requiresAuth && !token && to.name !== "login") {
return { name: "login", query: { redirect: to.fullPath } }
}
return true
})预期结果:未登录访问 /admin 时,地址变为 /login?redirect=/admin;写入有效令牌后再次访问可进入管理页。实际令牌格式和有效性应由认证模块判断,不能只依赖“字符串存在”。
离开页面前确认
在组合式 API 组件中使用 onBeforeRouteLeave。只有表单确实修改过时才弹出确认,避免每次离开都打断用户:
<script setup lang="ts">
import { ref } from "vue"
import { onBeforeRouteLeave } from "vue-router"
const dirty = ref(false)
onBeforeRouteLeave(() => {
if (!dirty.value) return true
// 返回 false 会取消本次导航并停留在当前页面
return window.confirm("内容尚未保存,确定离开吗?")
})
</script>
<template>
<textarea @input="dirty = true" />
</template>预期结果:未编辑时直接离开;编辑后选择“取消”会停留当前页,选择“确定”才继续导航。浏览器原生确认框的文字和样式由浏览器决定。
返回值速查
true或无返回值:继续导航。false:取消导航,并恢复原地址。- 路由位置对象:重定向,例如
{ name: "login" }。 - 抛出错误:导航失败,可由
router.onError()统一记录。
风险与排障
- 守卫重定向到仍满足同一拦截条件的页面会无限循环;登录页必须公开,或在条件中显式排除。
- 不要在守卫中只启动异步请求却不
await或返回结果,否则权限状态可能尚未确定就完成导航;安全做法是让守卫返回 Promise,并在失败时返回登录页或false。 localStorage在服务端渲染期间不可用;SSR 项目应从服务端会话、Cookie 或注入的认证状态读取。- 守卫未触发时,检查是否注册在实际传给
app.use(router)的同一个路由实例上,并确认组件使用的是 Vue Router 4 的组合式守卫 API。
兼容 Vue 3 与 Vue Router 4。旧式 next() 仍可见于历史代码,但新代码优先使用返回值风格,避免重复调用 next() 导致导航异常。
结合路由元信息和导航守卫限制页面访问权限。
实现路由权限控制
当页面只允许已登录用户或指定角色访问时,把访问规则放进路由 meta,再由全局 beforeEach 统一判断。守卫只负责前端导航体验,接口仍必须由服务端再次鉴权。
权限流程
访问受保护页面时,先检查登录状态,再检查角色;未登录跳转登录页,无权限跳转 403,通过后才加载目标页面。登录成功后可读取 redirect 查询参数返回原页面。

路由与守卫
以下是片段示例,依赖项目已有 LoginView.vue、ForbiddenView.vue、DashboardView.vue,以及能提供当前用户状态的认证模块。
import { createRouter, createWebHistory } from 'vue-router'
import { auth } from '@/auth'
const router = createRouter({
history: createWebHistory(),
routes: [
{
path: '/login',
name: 'login',
component: () => import('@/views/LoginView.vue'),
},
{
path: '/403',
name: 'forbidden',
component: () => import('@/views/ForbiddenView.vue'),
},
{
path: '/dashboard',
name: 'dashboard',
component: () => import('@/views/DashboardView.vue'),
meta: { requiresAuth: true, roles: ['admin', 'operator'] },
},
],
})
router.beforeEach(async (to) => {
// 首次刷新时先恢复会话,避免把尚未加载的用户误判为未登录。
await auth.ensureReady()
if (to.meta.requiresAuth && !auth.isLoggedIn()) {
return {
name: 'login',
query: { redirect: to.fullPath },
replace: true,
}
}
const allowedRoles = to.meta.roles as string[] | undefined
if (allowedRoles && !allowedRoles.some((role) => auth.hasRole(role))) {
return { name: 'forbidden', replace: true }
}
})
export default router预期结果
未登录访问 /dashboard -> /login?redirect=/dashboard
已登录但角色不匹配 -> /403
角色为 admin 或 operator -> 正常进入 /dashboard元信息类型
TypeScript 项目可扩展 RouteMeta,避免在守卫里反复断言类型。该声明应位于被 tsconfig.json 包含的 .d.ts 文件中。
import 'vue-router'
export {}
declare module 'vue-router' {
interface RouteMeta {
requiresAuth?: boolean
roles?: string[]
}
}生效后,路由配置中的 requiresAuth 和 roles 会获得类型检查;拼错字段名或传入错误类型时,编辑器与构建阶段会提示。
风险与边界
前端路由守卫可被用户绕过。触发条件是直接调用后端接口、篡改本地状态或禁用前端脚本,后果是仅靠前端判断的敏感数据可能泄露;安全替代方案是在服务端按会话、令牌和资源权限执行同等或更严格的校验。
不要在守卫中无条件重定向到受保护路由,否则会形成循环导航。登录页和 403 页应保持公开;异步权限请求失败时应取消导航或进入明确的错误页,不要默认放行。
排障清单
- 刷新后总被踢回登录页:确认
ensureReady()在权限判断前完成,并区分“未初始化”和“未登录”。 - 子路由权限未生效:检查父子路由的
meta合并结果,以及子路由是否覆盖了同名字段。 - 登录后没有回到原页面:登录成功后校验并使用
route.query.redirect,只允许站内路径,避免开放重定向。 - 守卫反复触发:检查目标页是否再次命中同一拒绝条件,并为登录页、403 页设置公开规则。
使用动态导入拆分页面代码并降低首屏加载体积。
懒加载路由页面
页面组件较多或首屏包体偏大时,把静态导入改为返回 import() Promise 的函数。构建工具会拆出独立 chunk,用户首次进入该路由时才下载,之后复用已加载模块。
基本语法
以下是片段示例,依赖 Vite 创建的 Vue 3 项目和对应页面文件。入口页可保持静态导入,低频业务页使用动态导入。
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'
export default createRouter({
history: createWebHistory(),
routes: [
{
path: '/',
name: 'home',
component: HomeView,
},
{
path: '/reports',
name: 'reports',
component: () => import('@/views/ReportsView.vue'),
},
{
path: '/settings',
name: 'settings',
component: () => import('@/views/SettingsView.vue'),
},
],
})生效行为:首屏加载入口代码和 HomeView;首次进入 /reports 或 /settings 时,再请求对应页面 chunk。路由组件直接使用加载函数,不要再包一层 defineAsyncComponent()。
构建验证
执行生产构建并检查 dist/assets,确认除入口文件外还生成了路由页面对应的 JavaScript chunk。
npm run build预期输出
dist/assets/index-<HASH>.js
dist/assets/<ROUTE_CHUNK>-<HASH>.js
✓ built in <TIME><HASH>、<ROUTE_CHUNK> 和 <TIME> 会随项目及构建变化。验证重点不是文件名固定,而是业务路由没有全部合并进单个入口文件;也可在浏览器 Network 面板中确认首次访问路由时才出现该 chunk 请求。
高频用法
- 管理后台、报表、编辑器等低频大页面优先懒加载。
- 登录页、错误页和首屏关键页面是否懒加载,应按真实网络与缓存数据评估,不要机械地全部拆分。
- 同一业务域的小页面过度拆分会增加请求数,可通过 Vite 的
build.rollupOptions.output.manualChunks合并为业务 chunk。 - 路由页面内部的大型图表或编辑器仍可继续组件级懒加载,避免进入页面就下载所有非首屏能力。
风险与边界
拆分过细会在弱网下产生大量串行请求。触发条件是单页依赖很多小 chunk 且没有预加载,后果是点击后长时间白屏;安全替代方案是按业务域合并 chunk,并为路由切换提供加载状态。
发布时若立即删除旧版本静态资源,仍打开旧页面的用户可能请求到不存在的 chunk,表现为 Failed to fetch dynamically imported module。更安全的做法是给静态资源使用内容哈希和长期缓存,同时保留上一版本资源一段时间,或在 router.onError() 中提示刷新后重试。
排障清单
- 构建后仍只有一个大文件:确认路由中使用的是
component: () => import('...'),不是文件顶部的静态import。 - 页面点击后才报模块不存在:检查路径大小写、别名配置和部署服务器是否上传了全部
dist文件。 - 本地正常、发布后 chunk 404:检查站点基础路径、CDN 回源目录和旧资源清理策略。
- 首次进入页面明显卡顿:检查该页面是否同时触发多个大依赖,必要时合并业务 chunk 或预加载高概率下一页。
使用 Setup Store 定义全局状态、计算值和操作。
创建 Pinia Setup Store
用于把跨组件共享的数据、派生值和业务操作集中到一个 Store。Setup Store 通过 ref 或 reactive 声明状态、computed 声明计算值,并把函数作为操作返回;组件调用 useCartStore() 后即可访问同一份状态。
前置条件
应用必须先安装同一个 Pinia 实例,并在 mount() 前注册。若项目已完成该配置,可直接创建 Store 文件。
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
const app = createApp(App)
app.use(createPinia())
app.mount('#app')生效结果:组件的 setup 或 <script setup> 中可以正常调用任意 useXxxStore(),不会出现“没有活动 Pinia 实例”的错误。
定义 Store
下面的 Store 保存购物车条目,计算商品总数,并提供添加与重置操作。cart 是 Store 的唯一标识,同一 Pinia 实例内不要与其他 Store 重复。
// src/stores/cart.ts
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'
interface CartItem {
id: number
name: string
quantity: number
}
export const useCartStore = defineStore('cart', () => {
const items = ref<CartItem[]>([])
const totalQuantity = computed(() =>
items.value.reduce((sum, item) => sum + item.quantity, 0),
)
function addItem(id: number, name: string): void {
const existing = items.value.find((item) => item.id === id)
if (existing) {
existing.quantity += 1
return
}
items.value.push({ id, name, quantity: 1 })
}
function reset(): void {
items.value = []
}
return { items, totalQuantity, addItem, reset }
})读取规则:返回的 ref 在组件模板中会自动解包,因此使用 cart.totalQuantity,不需要写 cart.totalQuantity.value。
组件调用与预期结果
<!-- src/App.vue -->
<script setup lang="ts">
import { useCartStore } from './stores/cart'
const cart = useCartStore()
</script>
<template>
<main>
<p>商品种类:{{ cart.items.length }}</p>
<p>商品总数:{{ cart.totalQuantity }}</p>
<button @click="cart.addItem(1, '键盘')">加入键盘</button>
<button @click="cart.reset()">清空</button>
</main>
</template>初始页面:
商品种类:0
商品总数:0点击一次“加入键盘”后:
商品种类:1
商品总数:1风险与边界
准备作为 Store 状态的 ref 或 reactive 应显式返回。漏掉 return 时,外部组件无法访问该状态,服务端渲染、开发工具或插件也可能拿不到完整状态;安全做法是返回全部公开状态、计算值和操作,仅把模块常量留在 Store 外部。
Setup Store 不会自动生成可恢复初始值的 $reset()。需要重置时,应像示例一样定义明确的 reset() 操作,避免在组件中分散编写多处清理逻辑。
排障清单
- 出现
getActivePinia()相关错误:确认app.use(createPinia())位于app.mount()之前。 - 不同组件读到不同状态:检查是否误创建并注册了多个 Pinia 实例。
- 计算值不更新:确认依赖来自
ref、reactive或其他响应式值,并已从 Store 返回。 - Store 无法自动导入:确认文件导出了
useCartStore,且组件导入路径与实际目录一致。
在组件中访问 Pinia 状态并使用直接赋值或 $patch 更新数据。
读取和修改 Pinia Store
在组件中调用 useXxxStore() 可直接读取状态、计算值和操作。单字段更新适合直接赋值;多个字段一起更新可使用 $patch 对象;涉及数组增删等原地修改时,使用 $patch 函数更清晰。
示例 Store
前提是应用已通过 app.use(createPinia()) 注册 Pinia。下面的 Setup Store 提供用户状态、未读数量、通知列表和一个派生展示文本。
// src/stores/session.ts
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'
export const useSessionStore = defineStore('session', () => {
const name = ref('访客')
const online = ref(false)
const unreadCount = ref(0)
const notices = ref<string[]>([])
const summary = computed(
() => `${name.value} / ${online.value ? '在线' : '离线'} / 未读 ${unreadCount.value}`,
)
return { name, online, unreadCount, notices, summary }
})读取响应式数据
需要解构状态或计算值时使用 storeToRefs(),否则 const { name } = store 得到的值不会继续跟随 Store 更新。操作函数可以直接从 Store 解构,但本例直接通过 Store 实例修改状态。
<!-- src/App.vue -->
<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { useSessionStore } from './stores/session'
const session = useSessionStore()
const { summary, notices } = storeToRefs(session)
function markOnline(): void {
// 单字段更新:直接赋值最直观
session.online = true
}
function applyProfile(): void {
// 多个简单字段作为一次补丁提交
session.$patch({
name: 'Alice',
unreadCount: 3,
})
}
function appendNotice(): void {
// 集合原地修改时使用函数补丁,相关字段一起更新
session.$patch((state) => {
state.notices.push('部署完成')
state.unreadCount += 1
})
}
</script>
<template>
<main>
<p>{{ summary }}</p>
<p>通知数量:{{ notices.length }}</p>
<button @click="markOnline">设为在线</button>
<button @click="applyProfile">更新资料</button>
<button @click="appendNotice">新增通知</button>
</main>
</template>预期结果
初始页面:
访客 / 离线 / 未读 0
通知数量:0依次点击“设为在线”“更新资料”“新增通知”后:
Alice / 在线 / 未读 4
通知数量:1更新方式速查
直接赋值适合一个明确字段,例如 session.online = true。$patch({ ... }) 适合同时替换多个已声明字段;$patch((state) => { ... }) 适合 push、splice 等集合操作,并可把相关计数同步放在同一次更新中。
不要给 Store 临时添加未声明属性。这样会绕过既有类型和状态设计,可能造成组件不更新或序列化结果不完整;安全替代方案是在 Store 定义中先声明初始状态,再通过直接赋值、$patch 或操作函数更新。
风险与排障
- 解构后页面不更新:不要写
const { summary } = session,改用storeToRefs(session),或始终读取session.summary。 - 多个字段出现短暂不一致:把相关修改放进同一个
$patch函数,或封装为 Store 操作。 - 数组更新后数量错误:确认只在一个位置递增计数,避免组件和 Store 同时修改同一业务状态。
- TypeScript 提示属性不存在:先在 Store 中声明该状态,不要通过运行时动态挂载新字段。
- 在组件外调用时报活动实例错误:确保 Pinia 已安装;路由守卫或普通模块中应在应用初始化之后再取得 Store。
在 Pinia Store 中组织派生状态和可复用业务操作。
定义 Getter 与 Action
在 Pinia 中,Getter 用来从现有状态计算只读派生值,Action 用来集中执行状态修改和可复用业务操作。把“计算”与“修改”分开后,组件只负责调用和展示,状态规则不会散落在多个页面中。
基本语法
Option Store 的 getters 类似组件中的 computed,会基于依赖缓存结果;actions 是可直接修改 state 的方法,也可以接收参数并返回业务结果。
import { defineStore } from "pinia"
interface Todo {
id: number
title: string
done: boolean
}
export const useTodoStore = defineStore("todo", {
state: () => ({
todos: [{ id: 1, title: "检查发布清单", done: true }] as Todo[],
nextId: 2
}),
getters: {
completedCount: (state) => state.todos.filter((item) => item.done).length,
// 通过 this 访问其他 Getter 时使用普通函数,并显式声明返回类型
pendingCount(): number {
return this.todos.length - this.completedCount
}
},
actions: {
addTodo(title: string): boolean {
const normalized = title.trim()
if (!normalized) return false
this.todos.push({
id: this.nextId++,
title: normalized,
done: false
})
return true
},
toggleTodo(id: number): boolean {
const target = this.todos.find((item) => item.id === id)
if (!target) return false
target.done = !target.done
return true
}
}
})在已通过 app.use(createPinia()) 注册 Pinia 的 Vue 3 项目中,可直接从组件调用:
<script setup lang="ts">
import { storeToRefs } from "pinia"
import { useTodoStore } from "./stores/todo"
const todoStore = useTodoStore()
const { todos, completedCount, pendingCount } = storeToRefs(todoStore)
todoStore.addTodo("回归核心流程")
todoStore.toggleTodo(2)
</script>
<template>
<p>总数:{{ todos.length }}</p>
<p>已完成:{{ completedCount }},待办:{{ pendingCount }}</p>
</template>预期结果:页面显示以下内容。Getter 会在 todos 变化后自动重新计算。
总数:2
已完成:2,待办:0高频用法
Getter 适合筛选列表、统计数量、拼接展示字段和判断权限,不应发请求或修改状态。需要读取另一个 Getter 时,使用普通函数形式;只读取 state 时,优先使用箭头函数,类型推断更直接。
Action 适合封装“校验输入后修改状态”“连续修改多个字段”“复用同一业务步骤”等操作。让 Action 返回 boolean、ID 或结果对象,组件即可根据返回值决定是否提示成功,而不必复制 Store 内部判断。
组件需要解构状态或 Getter 时使用 storeToRefs(store);Action 可直接从 Store 解构,因为方法本身不会丢失响应性。
风险与边界
不要在 Getter 中写 this.xxx = ...、调用接口或产生随机值。Getter 被多处读取时可能重复触发副作用,导致状态循环更新或结果不可预测;安全做法是把副作用移入 Action,把 Getter 保持为纯计算。
不要直接写 const { completedCount } = todoStore。这样得到的是当时的普通值,后续状态变化可能不会驱动视图更新;应改为 storeToRefs(todoStore),或在模板中直接访问 todoStore.completedCount。
排障清单
- Getter 中访问
this报类型错误:改用普通函数,并显式声明返回类型。 - 页面值不更新:检查是否直接解构了状态或 Getter,改用
storeToRefs。 - Action 调用后数据没变:确认调用的是同一个 Pinia 实例,并检查输入校验是否提前返回。
- Store 间互相调用出现循环:把共享逻辑提取为普通函数,避免两个 Store 在初始化阶段相互读取。
在 Pinia Action 中调用接口并维护成功或失败状态。
执行异步 Store Action
异步 Action 用于把接口请求、加载状态、错误信息和结果写入集中在同一个 Store 中。组件只调用 Action 并读取 loading、error 与数据,能避免多个页面各自维护一套不一致的请求状态。
前置条件
以下示例适用于已注册 Pinia 的 Vue 3 + Vite 项目。先创建本地静态接口数据,运行开发服务器后,浏览器会通过 /users.json 发起真实 HTTP 请求。
[
{ "id": 1, "name": "Ada" },
{ "id": 2, "name": "Linus" },
{ "id": 3, "name": "Grace" }
]将该文件保存为 public/users.json。
主示例
Action 在请求前重置错误并开启加载状态,在成功时写入数据,在失败时保存可展示的错误信息,最后确保关闭加载状态。requestSeq 用于避免较早请求晚返回时覆盖最新结果。
import { defineStore } from "pinia"
interface User {
id: number
name: string
}
export const useUserStore = defineStore("user", {
state: () => ({
users: [] as User[],
loading: false,
error: null as string | null,
requestSeq: 0
}),
actions: {
async fetchUsers(): Promise<User[]> {
const currentSeq = ++this.requestSeq
this.loading = true
this.error = null
try {
const response = await fetch("/users.json", {
headers: { Accept: "application/json" }
})
if (!response.ok) {
throw new Error(`HTTP ${response.status}`)
}
const users = (await response.json()) as User[]
// 只允许最后一次请求提交结果,避免旧响应覆盖新数据
if (currentSeq === this.requestSeq) {
this.users = users
}
return users
} catch (error: unknown) {
const message = error instanceof Error ? error.message : "未知请求错误"
if (currentSeq === this.requestSeq) {
this.error = message
}
throw error
} finally {
if (currentSeq === this.requestSeq) {
this.loading = false
}
}
}
}
})组件在挂载时执行 Action,并在本地捕获异常,避免产生未处理的 Promise 拒绝:
<script setup lang="ts">
import { onMounted } from "vue"
import { storeToRefs } from "pinia"
import { useUserStore } from "./stores/user"
const userStore = useUserStore()
const { users, loading, error } = storeToRefs(userStore)
onMounted(async () => {
try {
await userStore.fetchUsers()
} catch {
// 错误详情已由 Store 写入 error,组件只负责决定展示方式
}
})
</script>
<template>
<p v-if="loading">加载中...</p>
<p v-else-if="error">加载失败:{{ error }}</p>
<ul v-else>
<li v-for="user in users" :key="user.id">{{ user.name }}</li>
</ul>
</template>预期结果:请求成功后页面依次显示 Ada、Linus、Grace,同时 loading 为 false、error 为 null。实际网络耗时可能不同。
Ada
Linus
Grace高频用法
需要由调用方继续处理结果时,Action 返回解析后的数据;只需更新 Store 时可以不返回。失败后通常继续 throw,让组件决定弹窗、重试或跳转;若 Action 已完全处理错误,则返回明确的结果对象,不要静默吞掉异常。
同一查询可能被搜索框、路由切换或刷新按钮连续触发时,应使用请求序号或 AbortController。仅设置 loading 不能阻止旧响应覆盖新响应。
风险与边界
多个并发请求共用一个布尔 loading 时,较早结束的请求可能提前把它设为 false。后果是页面停止显示加载状态,但仍有请求在执行;安全方案是像示例一样只让最新请求修改状态,或改用计数器记录活动请求数。
不要把原始异常对象直接绑定到页面。异常可能包含实现细节且结构不稳定;应在 Action 中转换为可控字符串或错误码,同时把完整异常交给日志系统。
不要在每次组件挂载时无条件重复请求长期不变的数据。可增加 loadedAt、缓存有效期或显式 force 参数,在需要刷新时再绕过缓存。
排障清单
loading一直为true:确认关闭逻辑位于finally,且没有在try前抛出异常。- 页面没有错误提示:检查组件是否捕获了异常,以及 Store 是否在
catch中写入error。 - 数据偶尔回退到旧值:存在并发竞态,增加请求序号或取消前一次请求。
- 返回 JSON 解析失败:查看 Network 中的响应体,确认接口没有返回 HTML 登录页或空响应。
使用 storeToRefs 解构 Store 状态并保持响应性。
解构 Pinia 状态
在 <script setup> 中需要把 Store 的状态或 getter 单独交给模板、监听器或组合式函数时,使用 storeToRefs(store)。它会为状态、getter 和插件添加的响应式状态创建引用;action 仍直接从 Store 实例取得。
基本语法
先创建 Store 实例,再将需要的状态和 getter 从 storeToRefs() 返回值中解构。模板会自动解包这些引用;在脚本逻辑中读取或修改状态时仍使用 .value。
// src/stores/counter.ts
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'
export const useCounterStore = defineStore('counter', () => {
const count = ref(0)
const doubleCount = computed(() => count.value * 2)
function increment() {
count.value++
}
return { count, doubleCount, increment }
})<!-- src/App.vue -->
<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { useCounterStore } from './stores/counter'
const counterStore = useCounterStore()
const { count, doubleCount } = storeToRefs(counterStore)
// action 已绑定 Store,可直接解构,不要放进 storeToRefs()
const { increment } = counterStore
</script>
<template>
<p>计数:{{ count }}</p>
<p>双倍:{{ doubleCount }}</p>
<button type="button" @click="increment">加 1</button>
</template>预期结果
初始页面:
计数:0
双倍:0
点击“加 1”一次后:
计数:1
双倍:2读取与修改
count 是可写状态引用,脚本中可执行 count.value++;doubleCount 来源于 getter,应按只读值使用。组件只需要展示少量字段时可解构,字段很多且均在模板中使用时,直接保留 counterStore.count 通常更清楚。
action 不需要响应式包装,可使用 const { increment } = counterStore。storeToRefs() 会忽略方法和非响应式属性,因此不能从它的返回值中取得 increment。
风险与边界
直接写 const { count } = counterStore 会取得当前值而不是响应式引用,后续 Store 更新时局部变量不会同步。安全替代方案是使用 storeToRefs(counterStore),或始终通过 counterStore.count 访问。
不要给 getter 引用赋值;需要双向修改时,应修改其依赖的 state,或在 Store 中提供 action。将整个 Store 交给 Vue 通用 toRefs() 也不合适,Pinia 专用方法会主动过滤 action 和非响应式成员。
排障清单
- 页面数值不更新:检查是否直接解构了 Store,而不是通过
storeToRefs()。 - 脚本报
value相关错误:模板中不用.value,脚本中引用需要.value。 - action 为
undefined:从 Store 实例解构 action,不要从storeToRefs()返回值中取。 - getter 无法赋值:getter 是派生值,改 state 或调用 action。
适用于 Vue 3 Composition API 与 Pinia;Options API 更适合使用 mapState、mapWritableState 和 mapActions。
将必要的 Store 数据保存到浏览器存储并处理恢复与版本变化。
持久化 Pinia 状态
需要在刷新或重新打开页面后恢复主题、语言、筛选偏好等非敏感状态时,可使用 pinia-plugin-persistedstate。生产配置应只保存必要字段,并为存储结构设置版本和迁移逻辑,避免旧数据破坏新版 Store。
前置配置
安装 Pinia 与持久化插件:
npm install pinia pinia-plugin-persistedstate预期结果
added <N> packages<N> 取决于现有依赖;命令应以退出码 0 结束,并在 package.json 中出现对应依赖。在创建应用时先注册持久化插件,再挂载 Vue:
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import App from './App.vue'
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
createApp(App).use(pinia).mount('#app')该配置生效后,声明了 persist 的 Store 会在首次创建时读取存储,并在状态变化后同步写回。
持久化与版本迁移
下面只保存 schemaVersion、theme 和 density。反序列化时把旧版 theme: "night" 迁移为 "dark",把 compact 布尔值迁移为 density;未知版本或损坏 JSON 直接回退默认状态。

// src/stores/preferences.ts
import { defineStore } from 'pinia'
type Theme = 'system' | 'light' | 'dark'
type Density = 'comfortable' | 'compact'
interface PreferencesState {
schemaVersion: 2
theme: Theme
density: Density
}
const STORAGE_KEY = 'app:preferences'
const DEFAULT_STATE: PreferencesState = {
schemaVersion: 2,
theme: 'system',
density: 'comfortable',
}
function deserializePreferences(raw: string): PreferencesState {
try {
const saved = JSON.parse(raw) as {
schemaVersion?: number
theme?: string
density?: string
compact?: boolean
}
// v1 -> v2:重命名主题值,并把 compact 合并到 density。
if (saved.schemaVersion === 1) {
return {
schemaVersion: 2,
theme: saved.theme === 'night'
? 'dark'
: saved.theme === 'light'
? 'light'
: 'system',
density: saved.compact === true ? 'compact' : 'comfortable',
}
}
const validTheme =
saved.theme === 'system' ||
saved.theme === 'light' ||
saved.theme === 'dark'
const validDensity =
saved.density === 'comfortable' ||
saved.density === 'compact'
if (saved.schemaVersion === 2 && validTheme && validDensity) {
return saved as PreferencesState
}
} catch {
// 损坏数据不进入 Store,统一使用当前默认值。
}
return { ...DEFAULT_STATE }
}
export const usePreferencesStore = defineStore('preferences', {
state: (): PreferencesState => ({ ...DEFAULT_STATE }),
actions: {
setTheme(theme: Theme) {
this.theme = theme
},
},
persist: {
key: STORAGE_KEY,
storage: localStorage,
pick: ['schemaVersion', 'theme', 'density'],
serializer: {
serialize: state => JSON.stringify(state),
deserialize: deserializePreferences,
},
},
})验证恢复
组件读取恢复后的值,并通过 action 触发一次新版本写回:
<!-- src/App.vue -->
<script setup lang="ts">
import { storeToRefs } from 'pinia'
import { usePreferencesStore } from './stores/preferences'
const preferences = usePreferencesStore()
const { schemaVersion, theme, density } = storeToRefs(preferences)
</script>
<template>
<p>版本:{{ schemaVersion }}</p>
<p>主题:{{ theme }}</p>
<p>密度:{{ density }}</p>
<button type="button" @click="preferences.setTheme('light')">
保存浅色主题
</button>
</template>在浏览器控制台写入一份 v1 数据并刷新:
localStorage.setItem(
'app:preferences',
JSON.stringify({ schemaVersion: 1, theme: 'night', compact: true }),
)
location.reload()预期结果
版本:2
主题:dark
密度:compact点击“保存浅色主题”后,在控制台验证写回内容:
console.log(localStorage.getItem('app:preferences'))预期输出
{"schemaVersion":2,"theme":"light","density":"compact"}风险与边界
浏览器存储可被同源 JavaScript 读取。触发条件是页面存在 XSS、第三方脚本被劫持或设备被他人使用;后果可能是凭据泄露和隐私暴露。不要持久化访问令牌、密码、支付信息或完整用户资料,认证优先使用服务端会话和 HttpOnly、Secure、SameSite Cookie。
localStorage 是同步存储,保存大对象或高频变更会阻塞主线程,并可能触发容量限制。安全替代方案是只用 pick 保存小型偏好,避免缓存接口大列表;需要异步、大容量数据时改用 IndexedDB,并在 action 层显式同步。
JSON 会丢失 Date、Map、Set、对象引用关系等运行时类型。应持久化可序列化 DTO,并在恢复后重建对象;跨标签页状态也不会自动更新,可额外监听 storage 事件或使用 BroadcastChannel。
排障清单
- 刷新后没有恢复:确认
pinia.use(piniaPluginPersistedstate)在 Store 首次创建前执行。 - 存储键不存在:确认 Store 已被组件实际调用,且
pick不是空数组。 - 旧版数据导致异常:检查
schemaVersion分支;无法迁移时删除旧键并回退默认值。 - SSR 报
localStorage is not defined:不要在服务端直接引用浏览器存储;Nuxt 使用对应模块和客户端安全配置。 - 修改后未写回:确认修改的是 Store state,而不是脱离响应性的普通变量。
该方案适用于 Vue 3 单页应用与 Pinia 2/3。Nuxt 或其他 SSR 环境应使用框架集成方案,并确保服务端渲染阶段不访问 window、localStorage。
使用 scoped、:deep() 和全局选择器控制组件样式作用范围。
编写作用域样式
在单文件组件中使用 <style scoped> 限制普通选择器只影响当前组件;需要修改子组件内部元素时使用 :deep(),确实要影响全局节点时使用 :global()。三者应按影响范围从小到大选择,避免样式泄漏。
基本语法
scoped 会在编译阶段为模板元素和 CSS 选择器附加同一作用域标记。它不是 Shadow DOM:样式仍位于页面样式表中,只是选择器被改写,因此优先级、继承和层叠规则仍按普通 CSS 计算。
下面的 App.vue 可直接运行,并用一个内联子组件演示 :deep():
<template>
<section class='profile-card'>
<h2 class='title'>用户资料</h2>
<ThirdPartyPanel class='panel' />
</section>
</template>
<script setup>
import { defineComponent, h } from 'vue'
const ThirdPartyPanel = defineComponent({
name: 'ThirdPartyPanel',
setup() {
// 使用渲染函数定义子组件,保证示例不依赖其他文件。
return () => h('div', { class: 'panel-title' }, '子组件标题')
}
})
</script>
<style scoped>
.profile-card {
padding: 16px;
border: 1px solid #dcdfe6;
}
/* 只影响当前组件模板中的 .title */
.title {
color: #1f2937;
}
/* 穿透子组件作用域,匹配其内部元素 */
.panel :deep(.panel-title) {
color: #2563eb;
}
/* 明确生成不带当前作用域标记的全局规则 */
:global(body) {
margin: 0;
}
</style>预期结果
页面显示带内边距和边框的卡片;“用户资料”为深色;子组件标题为蓝色;body 默认外边距被清除。读取页面效果时,先确认普通规则没有影响其他组件,再确认 :deep() 只命中了指定子树,最后检查全局规则是否造成非预期覆盖。
高频用法
普通组件样式优先放在 <style scoped> 中。修改 UI 组件库内部结构时,将稳定的外层类与 :deep() 组合,例如 .dialog :deep(.el-dialog__header),避免从页面根节点开始无边界穿透。
少量全局规则可写成 :global(.utility-class)。项目级样式重置、主题变量和字体规则更适合放入独立的全局样式文件,不要分散在多个组件中重复声明。
风险与边界
当 :deep() 依赖第三方组件的内部类名时,组件库升级可能使选择器失效,导致局部样式恢复默认。安全替代方案是优先使用组件库公开的 CSS 变量、主题 API、插槽或自定义类名。
对 body、通用标签或高频类使用 :global() 会扩大影响范围,可能覆盖其他页面。仅在规则确实属于全局基线时使用,并尽量通过业务根类限制匹配范围。
不要继续使用 /deep/、>>> 等旧写法;Vue 3 项目统一使用 :deep(),以避免预处理器解析失败或后续版本兼容问题。
排障清单
样式未生效时,先在开发者工具中确认目标元素和类名存在,再检查编译后的选择器是否包含 data-v-*。父组件无法命中子组件内部节点时确认已使用 :deep();全局规则被覆盖时比较选择器优先级和加载顺序,不要直接堆叠 !important。
速查:默认使用 scoped,跨子组件边界使用 :deep(),真正的全局基线才使用 :global()。
使用 Transition 为条件内容和动态组件添加过渡效果。
添加进入离开动画
使用 Vue 的 <Transition> 包裹单个条件节点或动态组件,可以在节点插入和移除时自动应用过渡类。关键是让模板中的 name 与 CSS 类名前缀一致,并保证过渡组件只有一个直接子节点。
基本语法
下面示例可直接放入 Vue 3 项目的 App.vue。点击按钮后,提示文字通过透明度和纵向位移完成进入、离开动画。
<template>
<main>
<button type='button' @click='visible = !visible'>
{{ visible ? '隐藏' : '显示' }}
</button>
<Transition name='fade-slide'>
<p v-if='visible' class='message'>保存成功</p>
</Transition>
</main>
</template>
<script setup>
import { ref } from 'vue'
const visible = ref(false)
</script>
<style scoped>
.fade-slide-enter-active,
.fade-slide-leave-active {
/* 只动画合成友好的属性,降低布局抖动风险。 */
transition: opacity 180ms ease, transform 180ms ease;
}
.fade-slide-enter-from,
.fade-slide-leave-to {
opacity: 0;
transform: translateY(-8px);
}
.message {
margin-top: 12px;
}
</style>预期结果
初始只显示“显示”按钮。点击后“保存成功”在约 180ms 内淡入并向下归位;再次点击时先淡出并向上移动,动画结束后节点从 DOM 中移除。fade-slide-enter-from 表示进入前状态,fade-slide-enter-active 定义进入过程;fade-slide-leave-active 定义离开过程,fade-slide-leave-to 表示离开终点。
高频用法
条件内容使用 <Transition><div v-if='open'>...</div></Transition>。动态组件可使用 <Transition name='fade' mode='out-in'><component :is='currentView' /></Transition>;切换同一种标签但内容不同时,需要提供不同的 key 才会触发节点替换。
首屏也需要播放进入动画时添加 appear。需要等待旧组件完全离开后再进入新组件时使用 mode='out-in',可减少两个视图同时占位造成的闪动。
风险与边界
<Transition> 默认处理一个直接子节点;存在多个并列节点时,动画类可能无法按预期应用。列表增删应改用 <TransitionGroup>,并为每项提供稳定且唯一的 key。
使用 v-show 时元素不会从 DOM 移除,只切换 display,适合频繁显示和隐藏。使用 v-if 会真实创建和销毁节点,适合切换频率较低或需要释放子组件状态的场景。
动画 height: auto、大面积阴影或复杂滤镜可能触发布局和重绘,造成页面卡顿。优先动画 transform 和 opacity,并针对系统的“减少动态效果”偏好提供无动画或弱动画降级方案。
排障清单
动画完全不执行时,检查 name 与类名前缀是否一致、响应式条件是否确实变化,以及直接子节点是否唯一。进入正常但离开瞬间消失时,确认父级没有提前卸载;动态组件切换无动画时,检查 key 是否变化,并在需要串行动画时添加 mode='out-in'。
速查:单节点使用 <Transition>,列表使用 <TransitionGroup>;动画属性优先选择 opacity 和 transform。
使用 Teleport 将模态框或通知渲染到指定 DOM 容器。
传送弹层内容
Teleport 用于把模态框、抽屉、通知等内容渲染到组件 DOM 层级之外,同时保留原有的组件父子关系。它能避开祖先元素的 transform、overflow 和局部层叠上下文,但不会自动处理焦点、滚动锁定或关闭交互。

基本语法
Teleport 是 Vue 内置组件,在模板中可直接使用。to 指向 CSS 选择器或真实 DOM 元素;弹层虽然出现在目标容器中,事件、插槽、依赖注入和 Vue Devtools 中的组件层级仍按原组件树工作。
在 index.html 中把目标节点放到 #app 外,确保应用挂载时它已经存在:
<body>
<div id="app"></div>
<div id="overlay-root"></div>
<script type="module" src="/src/main.ts"></script>
</body>组件示例:
<script setup lang="ts">
import { ref } from 'vue'
const open = ref(false)
</script>
<template>
<button type="button" @click="open = true">打开弹层</button>
<Teleport to="#overlay-root">
<div v-if="open" class="backdrop" @click.self="open = false">
<section class="dialog" role="dialog" aria-modal="true" aria-label="确认操作">
<p>弹层已传送到 #overlay-root。</p>
<button type="button" @click="open = false">关闭</button>
</section>
</div>
</Teleport>
</template>
<style scoped>
.backdrop {
position: fixed;
inset: 0;
display: grid;
place-items: center;
background: rgb(0 0 0 / 45%);
z-index: 1000;
}
.dialog {
min-width: 280px;
padding: 20px;
border-radius: 10px;
background: white;
}
</style>预期结果:
初始页面只显示“打开弹层”按钮。
单击后,弹层覆盖视口;在开发者工具中可看到 .backdrop 位于 #overlay-root 下。
单击遮罩空白处或“关闭”按钮后,弹层节点被移除。常用参数
| 参数 | 作用 | 使用要点 |
|---|---|---|
to |
指定目标容器 | 优先使用专用节点,如 #overlay-root;默认要求目标在挂载前存在 |
disabled |
为 true 时保留在原位置 |
适合桌面端传送、移动端内联的响应式布局 |
defer |
延迟到本次挂载周期末再解析目标 | Vue 3.5+ 可用;只解决同一挂载周期内较晚出现的目标,不等待异步节点 |
高频用法
- 全局模态框、抽屉和通知统一传送到专用根节点,由业务组件继续管理打开状态和事件。
- 多个
Teleport可以指向同一目标,内容按挂载顺序追加;弹层前后关系仍应由统一的层级或z-index规则控制。 - 通过
:disabled="isMobile"在小屏幕内联显示内容,避免为两种布局维护两套组件状态。
风险与边界
| 触发条件 | 可能后果 | 安全替代方案 |
|---|---|---|
to 选择器不存在或创建过晚 |
Vue 无法找到目标,内容不按预期渲染并产生警告 | 在静态 HTML 中预留目标;Vue 3.5+ 且目标在同一挂载周期出现时使用 defer |
| 目标节点仍位于受限的层叠上下文内 | 弹层继续被遮挡或被祖先裁剪 | 把目标放到 body 的直接子级,并集中管理弹层层级 |
SSR 直接传送到混有其他内容的 body |
服务端内容注入和客户端水合难以定位,可能出现不匹配 | 使用只承载传送内容的独立容器,并按 SSR 框架约定注入 Teleport 内容 |
| 只完成视觉传送,未处理键盘和滚动 | 焦点逃出弹层、背景仍可滚动,影响可访问性 | 增加焦点陷阱、Esc 关闭、焦点归还、滚动锁定和必要的 ARIA 属性 |
排障清单
- 弹层没有出现:检查
to的选择器、目标节点创建时机以及v-if条件。 - 弹层仍被遮挡:确认目标不是
#app内的深层节点,并检查目标自身及兄弟元素的层叠上下文。 - 点击遮罩无法关闭:将监听器放在遮罩层并使用
@click.self,避免内容区点击冒泡触发误关闭。 - SSR 出现水合告警:不要把复杂的服务端页面内容与 Teleport 共用
body目标,改用独立容器。
速查结论:Teleport 只移动最终 DOM,不移动组件关系;先保证目标稳定存在,再补齐弹层交互与可访问性。
使用 KeepAlive 保留切换组件的状态并控制缓存范围。
缓存动态组件
KeepAlive 用于缓存动态切换组件的实例,使表单输入、滚动位置和组件局部状态在切走后仍能恢复。它适合标签页、步骤面板和返回频繁的页面,但缓存会占用内存,必须明确缓存名单、容量和停用时的副作用处理。

基本语法
KeepAlive 是内置组件,通常包裹唯一的动态组件直接子节点。切换时,被缓存组件从 DOM 移除但实例不销毁;再次显示时复用原实例,因此局部响应式状态不会回到初始值。
下面的单文件组件可直接替换 Vite 项目的 src/App.vue:
<script setup lang="ts">
import {
defineComponent,
h,
onActivated,
onDeactivated,
ref,
shallowRef
} from 'vue'
const EditorPanel = defineComponent({
name: 'EditorPanel',
setup() {
const text = ref('')
onActivated(() => console.log('EditorPanel activated'))
onDeactivated(() => console.log('EditorPanel deactivated'))
return () =>
h('label', { class: 'panel' }, [
'编辑内容:',
h('input', {
value: text.value,
onInput: (event: Event) => {
text.value = (event.target as HTMLInputElement).value
}
})
])
}
})
const CounterPanel = defineComponent({
name: 'CounterPanel',
setup() {
const count = ref(0)
return () =>
h(
'button',
{ class: 'panel', onClick: () => count.value++ },
`计数:${count.value}`
)
}
})
// shallowRef 避免把组件定义转换成深层响应式对象。
const current = shallowRef(EditorPanel)
</script>
<template>
<nav>
<button type="button" @click="current = EditorPanel">编辑</button>
<button type="button" @click="current = CounterPanel">计数</button>
</nav>
<KeepAlive :include="['EditorPanel', 'CounterPanel']" :max="2">
<component :is="current" />
</KeepAlive>
</template>
<style scoped>
nav {
display: flex;
gap: 8px;
margin-bottom: 12px;
}
.panel {
display: block;
padding: 12px;
}
</style>预期结果:
在“编辑”面板输入 draft,切换到“计数”再切回,“draft”仍保留。
控制台首次显示 EditorPanel activated;切走显示 EditorPanel deactivated;切回再次显示 EditorPanel activated。缓存范围
| 参数 | 作用 | 使用要点 |
|---|---|---|
include |
只缓存名称匹配的组件 | 支持逗号字符串、正则或数组;按组件 name 匹配 |
exclude |
排除名称匹配的组件 | 与 include 同时存在时,排除规则用于阻止对应组件进入缓存 |
max |
限制缓存实例数量 | 超出上限时按最近最少使用策略销毁最久未访问的实例 |
生产代码应给需要匹配的组件稳定名称。文件名推断虽可减少配置,但重命名文件可能改变缓存结果;跨团队项目更适合显式声明 name,并使用稳定的 key 区分确实需要独立状态的实例。
生命周期处理
缓存组件不会在每次切换时执行普通的卸载与重新挂载流程。onActivated 在首次挂载和每次从缓存恢复时触发;onDeactivated 在进入缓存以及最终卸载时触发。定时器、轮询、媒体播放和订阅不应仅依赖 onUnmounted 清理。
常见做法是在 onDeactivated 中暂停持续任务,在 onActivated 中恢复或刷新易过期数据。需要完全释放资源时仍保留 onUnmounted 兜底,避免组件因缓存淘汰或父级销毁而留下资源。
风险与边界
| 触发条件 | 可能后果 | 安全替代方案 |
|---|---|---|
| 不设置范围并缓存大量页面 | 内存持续增长,旧页面状态和 DOM 长期保留 | 使用 include 限定高价值页面,并设置合理的 max |
| 停用后定时器、Socket 或监听器继续运行 | 重复请求、后台耗电或重复消费消息 | 在 onDeactivated 暂停,在 onActivated 恢复,最终在 onUnmounted 释放 |
include 名称与组件 name 不一致 |
组件未进入缓存,切回后状态被重置 | 显式声明稳定名称,并在 Vue Devtools 中核对实际组件名 |
每次切换都生成新的随机 key |
不断创建独立实例,缓存快速膨胀并触发淘汰 | 只在业务实体确需独立状态时使用稳定 key,不要用时间戳或随机数 |
排障清单
- 状态仍被重置:确认动态组件确实位于
KeepAlive内,且外层条件没有把整个KeepAlive一并卸载。 onActivated没有按预期触发:检查组件是否被exclude排除、名称是否匹配,以及当前实例是否真的从缓存恢复。- 页面返回后数据过旧:在
onActivated按时间戳或版本号判断是否刷新,不要无条件重复请求。 - 内存占用持续上升:统计动态组件名称与
key的组合数量,收紧include并降低max。
速查结论:只缓存“返回时值得保留状态”的组件,并把容量限制、稳定名称和停用副作用处理作为同一套配置。
通过组件错误钩子和应用级处理器集中记录运行时异常。
捕获 Vue 运行时错误
用于把组件渲染、生命周期、侦听器和事件处理器中的异常集中记录。组件级 onErrorCaptured 适合就近降级,应用级 app.config.errorHandler 适合统一上报;两者应保留原始错误并避免重复记录。
捕获链路
子组件抛错后,Vue 会沿父组件链调用错误捕获钩子;若钩子未返回 false,错误继续传给更高层并最终进入应用级处理器。当前组件不能靠自己的捕获钩子处理自身错误,因此边界组件必须位于故障组件的父级。

可运行示例
BrokenChild.vue 主动制造渲染错误,App.vue 在父级显示降级界面,main.ts 负责兜底记录。
<!-- src/components/BrokenChild.vue -->
<script setup lang="ts">
function renderProfile(): string {
// 模拟渲染阶段读取到无效数据
throw new Error('profile render failed')
}
</script>
<template>
<div>{{ renderProfile() }}</div>
</template><!-- src/App.vue -->
<script setup lang="ts">
import { onErrorCaptured, ref } from 'vue'
import BrokenChild from './components/BrokenChild.vue'
const failed = ref(false)
onErrorCaptured((error, _instance, info) => {
failed.value = true
const err = error instanceof Error ? error : new Error(String(error))
console.error('[boundary]', err.message, info)
// 返回 false:已在边界内处理,不再交给祖先和应用级处理器重复记录
return false
})
</script>
<template>
<p v-if="failed">个人资料暂时不可用</p>
<BrokenChild v-else />
</template>// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
app.config.errorHandler = (error, instance, info) => {
const err = error instanceof Error ? error : new Error(String(error))
console.error('[global]', err.message, info)
}
app.mount('#app')预期结果:页面显示降级文案,控制台只出现组件边界日志;info 的具体文本可能随构建模式变化。
[boundary] profile render failed <INFO>删除 return false 后,错误会继续进入应用级处理器,控制台还会出现:
[global] profile render failed <INFO>上报字段
记录时至少保留错误名称、消息、堆栈、组件信息、路由、发布版本和时间。instance 可能为空,生产构建中的 info 也可能被压缩为代码,因此上报逻辑不能依赖固定中文或英文文本。
风险与边界
错误钩子只负责捕获和降级,不应静默吞掉所有异常。无条件返回 false 会阻断全局监控,导致生产故障缺少证据;安全做法是在边界中完成上报后再阻断,或让异常继续传播并由全局处理器统一去重。
不要在捕获钩子中再次执行容易失败的业务逻辑。钩子自身抛错时会产生新的异常,可能同时上报原错误和钩子错误;上报客户端应使用最小依赖,并用 try...catch 防止监控代码反向影响页面。
排障清单
- 全局处理器未触发:检查父级
onErrorCaptured是否返回了false。 - 同一错误重复上报:为事件增加指纹,或明确只在组件边界与全局处理器中的一处上报。
- 页面仍为空白:捕获错误不会自动恢复 DOM,必须用状态切换到降级视图。
- Promise 拒绝未捕获:确认异常发生在 Vue 管理的回调中;独立异步任务还需处理
unhandledrejection。
速查:边界组件负责用户可见降级,全局处理器负责最终兜底,监控字段不要依赖 info 的固定文本。
运行 TypeScript、Vue 模板、ESLint 和格式化检查。
执行类型和代码检查
用于在提交或构建前一次性检查 TypeScript、Vue 单文件组件模板、ESLint 规则和 Prettier 格式。推荐把命令固定到 package.json,本地与 CI 使用同一入口,避免只检查 .ts 文件而漏掉 .vue 模板错误。
前置配置
安装项目实际使用的检查器,并在脚本中把类型、规则和格式检查串联起来。vue-tsc 负责 Vue 模板与 <script setup> 类型检查,eslint 负责代码规则,prettier --check 只验证格式而不改文件。
以下是 package.json 的片段示例,应合并到现有 Vue 项目;检查器版本由项目锁文件固定。
{
"scripts": {
"type-check": "vue-tsc --noEmit",
"lint": "eslint . --max-warnings=0",
"format-check": "prettier . --check",
"check": "npm run type-check && npm run lint && npm run format-check"
}
}项目需已安装 typescript、vue-tsc、eslint、Vue 对应的 ESLint 插件和 prettier。新增依赖后提交锁文件,确保本地与 CI 使用相同版本。
一次执行全部检查
npm run check全部通过时,vue-tsc 和 ESLint 通常不输出错误,Prettier 会给出完成提示。
> <PACKAGE>@<VERSION> type-check
> vue-tsc --noEmit
> <PACKAGE>@<VERSION> lint
> eslint . --max-warnings=0
> <PACKAGE>@<VERSION> format-check
> prettier . --check
Checking formatting...
All matched files use Prettier code style!读取方法:命令退出码为 0 表示全部通过;串联命令中任一步返回非零,后续步骤不会执行,CI 应直接判定失败。
高频用法
只检查类型,适合定位模板属性、组件事件和泛型推断问题:
npm run type-check预期结果:
> <PACKAGE>@<VERSION> type-check
> vue-tsc --noEmit<PACKAGE> 和 <VERSION> 取决于当前项目;没有后续诊断且退出码为 0 表示类型检查通过。若需要自动修复 ESLint 和格式问题,应显式执行写入型命令:
npx eslint . --fix && npx prettier . --write预期结果:可修复问题会直接写回文件;全部成功时 ESLint 可能无输出,Prettier 会逐行列出处理过的路径。
src/App.vue <TIME>
src/main.ts <TIME><TIME> 是格式化耗时,实际值可能不同。修复后仍应再次运行 npm run check,确认没有不可自动修复的问题。
失败输出定位
类型错误通常包含文件、行列、错误码和说明:
src/components/UserCard.vue(8,18): error TS2339: Property 'email' does not exist on type '{ name: string; }'.先按 文件(行,列) 定位,再根据 TS2339 判断是属性缺失、类型声明错误,还是模板使用了未暴露变量。ESLint 输出中的 error 会导致失败;由于配置了 --max-warnings=0,warning 也会让 CI 返回非零。
风险与边界
prettier --write 和 eslint --fix 会修改工作区。未提交改动时直接执行可能覆盖人工排版或产生大量无关差异;安全做法是先运行只读的 npm run check,确认范围后再在独立分支执行修复并审阅 git diff。
不要用普通 tsc --noEmit 替代 vue-tsc --noEmit 检查 Vue SFC。前者主要处理 TypeScript 文件,可能漏掉模板表达式和组件参数错误;仅在纯 TypeScript 子项目中使用 tsc。
排障清单
- 本地通过、CI 失败:核对 Node.js、包管理器版本和锁文件,CI 应使用
npm ci。 - ESLint 找不到配置:确认项目采用
eslint.config.js,或按旧版要求提供.eslintrc。 - 检查速度过慢:先排除
dist、coverage、生成代码和缓存目录,再考虑启用 ESLint 缓存。 - Prettier 反复改动:统一编辑器保存格式化器,并确保仓库只保留一套 Prettier 配置。
速查:提交前运行 npm run check;需要改文件时再执行 --fix 或 --write,并始终审阅差异。
挂载组件并验证渲染结果、用户交互和事件输出。
测试 Vue 组件
使用 Vitest 与 Vue Test Utils 挂载组件,直接验证页面渲染、用户操作和组件事件。测试应从外部可观察行为出发,避免断言组件内部变量或私有实现。
基本配置
在 Vite 创建的 Vue 3 项目中安装测试依赖:
npm install -D vitest @vue/test-utils jsdom在 vite.config.ts 中启用 Vue 插件和浏览器 DOM 环境:
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vitest/config'
export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom'
}
})配置生效后,测试文件可以导入 .vue 组件,并使用 document、按钮点击等 DOM 能力。
主示例
被测组件 UserButton.vue:
<script setup lang="ts">
const emit = defineEmits<{
save: [id: number]
}>()
</script>
<template>
<button type="button" @click="emit('save', 42)">保存</button>
</template>测试文件 UserButton.spec.ts:
import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import UserButton from './UserButton.vue'
describe('UserButton', () => {
it('渲染按钮并在点击后输出 save 事件', async () => {
const wrapper = mount(UserButton)
expect(wrapper.get('button').text()).toBe('保存')
// trigger 返回 Promise;等待 Vue 完成本轮响应式更新。
await wrapper.get('button').trigger('click')
expect(wrapper.emitted('save')).toEqual([[42]])
})
})运行单个测试文件:
npx vitest run UserButton.spec.ts预期输出:
✓ UserButton.spec.ts (1 test)
Test Files 1 passed (1)
Tests 1 passed (1)
Duration <TIME><TIME> 会随机器性能变化。重点读取测试文件数和测试数是否全部为 passed;退出码为 0 才表示命令成功。
高频断言
- 渲染结果:使用
get()获取必须存在的元素,再检查text()、attributes()或classes()。 - 用户交互:对按钮、输入框执行
trigger()或setValue(),异步操作前使用await。 - 事件输出:使用
wrapper.emitted('事件名')检查触发次数与参数。 - 条件渲染:通过
mount(Component, { props: {...} })构造不同输入,不直接修改组件内部状态。
风险与边界
只断言 class、内部方法名或响应式变量,会让测试与实现细节强绑定;重构后即使用户行为不变也可能大量失败。优先检查用户可见文本、可访问属性、事件和最终 DOM。
trigger()、setValue()、异步请求或定时器未等待完成时,断言可能偶发失败。安全做法是等待返回的 Promise;涉及外部请求时使用稳定的 mock,并只模拟组件边界之外的依赖。
排障清单
- 报
document is not defined:确认test.environment为jsdom,且配置文件被 Vitest 读取。 - 报无法解析
.vue:确认安装并启用了@vitejs/plugin-vue。 emitted()返回undefined:检查事件名大小写,并确认交互目标确实触发了事件。- 单测通过但批量失败:检查全局 mock、定时器和挂载后的副作用是否在每个测试结束后正确清理。
为部署到域名子目录的应用设置正确的资源基础路径。
配置部署基础路径
应用部署到 https://example.com/portal/ 这类域名子目录时,需要同时对齐 Vite 资源前缀和 Vue Router 历史基路径,否则常见结果是脚本、样式 404,或路由跳转到域名根目录。
基本配置
在 vite.config.ts 中把 base 设置为部署目录,路径应以 / 开头并以 / 结尾:
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [vue()],
base: '/portal/'
})Vite 会把构建产物中的入口脚本、样式和导入资源改写为 /portal/...。部署目录变更时,只修改这一处,不要手工替换 dist 内文件。
对齐路由基路径
使用 HTML5 History 路由时,让 Router 读取 Vite 注入的基础路径:
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'
export const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{
path: '/',
component: HomeView
}
]
})import.meta.env.BASE_URL 在本例中为 /portal/。这样 / 路由实际访问 /portal/,不会跳到站点根目录。
构建与验证
先构建,再检查入口文件是否包含目标资源前缀:
npm run build
node -e "const fs=require('node:fs');const h=fs.readFileSync('dist/index.html','utf8');console.log(h.includes('/portal/assets/'))"预期输出:
vite v<VERSION> building for production...
✓ <N> modules transformed.
✓ built in <TIME>
true<VERSION>、<N> 和 <TIME> 为动态值。最后一行必须为 true;若为 false,说明当前构建未使用预期的 base,应检查配置文件、构建命令和环境变量覆盖。
静态资源写法
通过 import、CSS url() 或模板中的模块资源引用交给 Vite 处理。必须在运行时拼接公共目录资源时,使用基础路径:
const logoUrl = `${import.meta.env.BASE_URL}logo.svg`生效结果:当 base 为 /portal/ 时,logoUrl 等于 /portal/logo.svg。不要把 /portal/ 同时硬编码在多处,否则切换部署目录时容易遗漏。
风险与边界
base 与反向代理实际暴露的前缀不一致时,浏览器会请求错误地址并返回 404。先确认代理是保留 /portal/ 还是转发时剥离该前缀,再让外部访问路径、Vite base 和 Router 基路径保持一致。
createWebHistory() 还要求服务器把 /portal/users/42 等未知静态路径回退到 /portal/index.html;缺少回退规则时,站内跳转正常但刷新深层路由会 404。无法配置服务器时,可改用 createWebHashHistory(),代价是 URL 包含 #。
排障清单
- 首页空白且控制台报脚本 404:查看 Network 中请求是否缺少或重复
/portal/。 - 页面资源正常但路由跳到根目录:确认使用
createWebHistory(import.meta.env.BASE_URL)。 - 站内跳转正常、刷新子路由 404:补充服务器 history fallback,且回退目标位于相同子目录。
- 本地正常、生产异常:检查 CI 是否使用了另一份 Vite 配置或通过环境变量覆盖了
base。
让服务器将未知前端路径回退到入口页面,避免刷新后返回 404。
配置 SPA 路由回退
当 Vue Router 使用 HTML5 History 模式时,浏览器直接访问或刷新 /orders/42 会向服务器请求该路径。服务器必须在“文件和目录均不存在”时返回 index.html,再由前端路由解析地址;API、静态资源和真实文件不能进入回退规则。
Nginx 主配置
下面配置适合 Vite 构建产物位于 /var/www/app/dist、后端接口监听 127.0.0.1:8080 的场景。/api/ 和 /assets/ 必须放在通用回退之前,避免接口错误被伪装成前端页面,也避免缺失的 JavaScript、CSS 返回 HTML。
server {
listen 80;
server_name example.com;
root /var/www/app/dist;
index index.html;
# API 保持独立转发,不能回退到 index.html
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Vite 默认静态资源目录;资源不存在时应返回真实 404
location ^~ /assets/ {
try_files $uri =404;
}
location / {
try_files $uri $uri/ /index.html;
}
}try_files 按顺序检查真实文件、真实目录,最后才回退入口页。项目若通过 base 修改了资源目录,应同步调整 /assets/ 规则。
验证回退是否生效
先检查配置并平滑重载,再请求一个只存在于前端路由中的地址。示例中的域名和端口按实际环境替换。
sudo nginx -t
sudo nginx -s reload
curl -i -H 'Host: example.com' http://127.0.0.1/orders/42预期输出的关键部分如下;时间、长度等动态值可能不同。
nginx: configuration file /etc/nginx/nginx.conf test is successful
HTTP/1.1 200 OK
Content-Type: text/html
...
<!doctype html>读取方法:路由地址应返回 200 和 HTML 入口页;随后由浏览器加载前端资源并显示订单页面。若响应体是 Nginx 404 页面,说明回退规则未命中或 root 指向错误目录。再验证缺失资源没有被错误回退:
curl -i -H 'Host: example.com' http://127.0.0.1/assets/not-found.js预期输出:
HTTP/1.1 404 Not Found
Content-Type: text/html这里的 404 是正确结果。若返回 200 且响应体以 <!doctype html> 开头,浏览器通常会报告模块 MIME 类型错误,说明静态资源路径也落入了 SPA 回退。
Apache 等价规则
Apache 启用 mod_rewrite 后,可在站点目录的 .htaccess 中仅回退不存在的文件和目录。API 若与前端同域,应在更高层 VirtualHost 中单独代理或排除。
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [L]生效行为:访问真实文件仍返回文件;访问 /orders/42 返回 index.html。可复用前面的 curl -i 方法验证状态码和响应体。
风险与边界
不要把所有 404 无条件改成 index.html。触发条件是 API、图片、脚本或下载文件不存在;后果是监控误判为成功、前端收到 HTML 后解析失败,甚至缓存错误内容。安全做法是先为 API 和静态资源建立独立路由,只对页面路径执行回退。
回退只能解决服务器入口分发,不能修复 Vue Router 自身未声明的路由。若入口页已返回但页面仍显示前端 404,应检查路由表、动态参数、部署 base 与 createWebHistory() 的基路径是否一致。
检查解构、数组对象替换、模板自动解包和非响应式数据导致的更新失效。
排查状态不更新
先判断“数据是否真的变化”,再判断“变化是否仍在 Vue 的响应式链路中”。高频原因是直接解构 Pinia 状态、替换 reactive 根对象、在脚本中漏写 .value,或把普通变量误当成响应式数据;不要先用强制刷新掩盖问题。

最小复现与正确写法
以下示例放入现有 Vue 3 + Pinia 项目。它同时展示错误的状态快照、正确的 storeToRefs()、数组属性替换,以及模板与脚本对 ref 的不同读取方式。
// src/stores/counter.ts
import { defineStore } from 'pinia'
export const useCounterStore = defineStore('counter', {
state: () => ({
count: 0,
items: [{ id: 1, done: false }]
}),
actions: {
advance() {
this.count += 1
// 替换 store 的响应式属性是安全的,模板会收到新数组
this.items = this.items.map(item =>
item.id === 1 ? { ...item, done: true } : item
)
}
}
})<!-- src/components/StateProbe.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/stores/counter'
const store = useCounterStore()
// 错误:取得当前数字快照,后续不会跟随 store.count
const { count: staleCount } = store
// 正确:把状态属性转换为保持连接的 ref
const { count, items } = storeToRefs(store)
const clicks = ref(0)
function update() {
clicks.value += 1
store.advance()
// 模板会自动解包 ref;脚本中必须显式读取 .value
console.log({
clicks: clicks.value,
count: count.value,
staleCount
})
}
</script>
<template>
<button @click="update">更新状态</button>
<p>本地点击:{{ clicks }}</p>
<p>响应式计数:{{ count }}</p>
<p>错误快照:{{ staleCount }}</p>
<p>首项完成:{{ items.length > 0 ? items[0].done : false }}</p>
</template>点击一次按钮后的预期页面与控制台结果:
页面:
本地点击:1
响应式计数:1
错误快照:0
首项完成:true
控制台:
{ clicks: 1, count: 1, staleCount: 0 }读取方法:count、items 和 clicks 更新说明渲染链路正常;staleCount 保持为 0,证明直接解构得到的是普通值快照。
四类高频失效点
直接解构响应式对象
从 Pinia store 解构方法通常没问题,但状态和 getter 应使用 storeToRefs()。普通 reactive 对象可使用 toRefs();只取单个属性时可使用 toRef(object, 'key')。
替换 reactive 根对象
下面写法会让变量指向新的普通对象,已有依赖仍订阅旧代理,因此界面不更新:
import { reactive } from 'vue'
let state = reactive({ count: 0 })
state = { count: 1 } // 错误:丢失原代理安全替代方案是原地修改 state.count = 1,或把根对象声明为 ref 后使用 state.value = { count: 1 }。数组同理:reactive([]) 适合 push、splice 等原地操作;需要整体替换时优先使用 ref([]) 并赋值给 .value。
混淆模板自动解包
模板顶层访问 ref 时可以写 {{ count }},脚本、普通 TypeScript 模块和大多数回调中仍需 count.value。若日志打印的是 Ref 对象而不是值,先检查是否漏写 .value,不要把它误判为 Vue 未更新。
使用非响应式数据
Date.now()、普通对象副本、第三方类实例或 markRaw() 数据不会自动触发渲染。触发条件是值在响应式容器之外变化;后果是日志可能显示新值,但模板没有重新执行。安全做法是只把需要驱动界面的最小状态放入 ref 或 reactive,外部实例则用响应式版本号或计算结果桥接。
排障清单
先在事件处理器、请求回调或 action 内打印更新前后值,并用 Vue Devtools 查看 store 是否变化。值未变化时检查代码分支、异步异常和提前返回;值已变化但界面未动时检查解构、根对象替换和非响应式来源。
监听属性时不要写 watch(state.count, callback),因为传入的是当下数字;应写 watch(() => state.count, callback)。另外确认组件仍处于挂载状态、模板读取的是同一份 store 实例,并排除用重复 Pinia 实例或错误导入路径创建了两套状态。
速查结论:状态变化但视图不变,优先找“响应式连接在哪里被切断”,而不是调用 $forceUpdate()。