Vue / 知识点
Vue 3 开发速查手册
手册条目
定位监听回调修改自身依赖导致的重复执行和页面卡顿。
排查监听无限循环
当 watch 回调或多个响应式副作用间接写回自己的依赖时,组件可能反复更新,表现为 CPU 占用升高、页面卡死,或控制台出现递归更新警告。watchEffect 能抑制部分同步自触发,但异步写回和跨监听闭环仍需排查。重点不是调整执行时机,而是找出“读取依赖 → 回调写回同一依赖”的闭环。
快速定位
先确认是否存在以下特征:删除某个监听后页面恢复;回调内直接修改监听源,或调用的方法间接修改监听源;监听对象使用了 deep: true,回调又改动其任意子属性;多个监听互相写入,形成 A 更新 B、B 再更新 A 的环。
下面是片段示例,可在开发环境为可疑监听加入触发日志。onTrack 显示依赖何时被收集,onTrigger 显示哪个响应式操作再次触发监听;这两个调试钩子只应临时使用,不要把高频日志带入生产环境。
watch(
() => form.value,
() => validateAndNormalize(),
{
deep: true,
onTrigger(event) {
console.log('[watch trigger]', event.type, event.key)
}
}
)预期结果
[watch trigger] set quantity
[watch trigger] set total
[watch trigger] set quantity同一组字段持续交替出现,通常说明回调或其调用链正在写回监听依赖。实际字段名取决于业务对象。

典型错误与修复
下面的组件中,监听回调每次都递增 count。用户点击一次后,回调修改了自己的监听源,因此会持续调度更新。
<script setup lang="ts">
import { ref, watch } from 'vue'
const count = ref(0)
watch(count, () => {
count.value++
})
</script>
<template>
<button @click="count++">count: {{ count }}</button>
</template>预期结果(错误现象)
[Vue warn]: Maximum recursive updates exceeded in component <COMPONENT>组件名和完整警告文字可能随 Vue 版本及构建模式不同,但页面卡顿和数值持续增长是关键现象。
优先把“根据状态计算另一个值”改成 computed,避免用监听器同步派生状态。以下片段替换同一组件的脚本和模板后,点击只更新源值,派生值由 Vue 缓存计算,不会写回依赖。
<script setup lang="ts">
import { computed, ref } from 'vue'
const count = ref(0)
const doubled = computed(() => count.value * 2)
</script>
<template>
<button @click="count++">
count: {{ count }}, doubled: {{ doubled }}
</button>
</template>预期结果
首次点击:count: 1, doubled: 2
再次点击:count: 2, doubled: 4
控制台无递归更新警告确实需要在监听中规范化源值时,必须保证写入可以收敛,并在写入前比较新旧值。下面是沿用上方 count 的片段示例,最多额外触发一次:只有输入超出范围时才回写规范化结果。
watch(count, (value) => {
const normalized = Math.max(0, Math.min(value, 10))
// 相同值不回写,避免无意义触发;规范化后必须能稳定在固定值
if (normalized !== value) {
count.value = normalized
}
})预期结果
输入 12:count 先变为 12,随后稳定为 10
输入 8:count 保持 8,不发生额外写入高频排查顺序
- 临时注释可疑监听,确认卡顿是否消失。
- 搜索回调内对监听源的直接赋值,以及调用链中的 store action、表单格式化和路由同步写入。
- 将
deep: true暂时移除或缩小监听源,判断是否由无关子属性触发。 - 检查多个监听、
computedsetter、Pinia 订阅和父子组件v-model是否互相回写。 - 用新旧值比较、单向数据流或显式事件入口替换双向同步,再恢复监听验证。
风险与边界
把 flush 改成 post 或 sync 只会改变回调执行时机,不能解除依赖闭环;sync 还可能让递归更快暴露。盲目加防抖只能降低触发频率,无法保证状态最终一致。安全替代方案是让派生值使用 computed,副作用监听不修改源值;必须回写时,加入相等判断、明确收敛条件,并限制 deep 监听范围。
速查结论:先画出每个监听“读哪些值、写哪些值”,只要依赖图中出现回到起点的写入路径,就应拆成单向更新或增加可证明收敛的保护条件。
检查路由匹配、动态导入、基础路径和服务器回退配置。
排查路由空白或 404
Vue Router 页面空白和 HTTP 404 是两类问题:空白通常表示 index.html 已返回,但路由匹配、动态组件加载或 <RouterView> 渲染失败;刷新地址出现 404,通常表示服务器没有把前端路由回退到入口文件。按“服务器响应 → 资源路径 → 路由匹配 → 组件渲染”的顺序检查,能避免在错误层反复修改配置。
先区分故障层
直接访问问题 URL,并同时查看浏览器 Network 与 Console:
- 文档请求返回 404:优先检查服务器回退规则和部署子路径。
- 文档请求返回 200,但 JS/CSS 返回 404:优先检查 Vite
base与静态资源发布目录。 - 文档和资源均为 200,控制台出现
Failed to fetch dynamically imported module:检查动态导入路径、旧缓存和分片是否完整发布。 - 请求均正常且无报错,但页面空白:检查路由是否匹配、父级组件是否包含
<RouterView />、组件是否真实渲染内容。

检查路由匹配和渲染出口
先确认应用安装了同一个 router 实例,并在 router.isReady() 后打印初始地址的匹配记录。下面是片段示例,放入已创建的 Vue 3 + Vue Router 工程,并确保 App.vue 与三个视图组件存在;访问 /users 时应匹配布局和用户页两层记录。
// src/main.ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import App from './App.vue'
import LayoutView from './views/LayoutView.vue'
import UserListView from './views/UserListView.vue'
import NotFoundView from './views/NotFoundView.vue'
const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
{
path: '/',
name: 'layout',
component: LayoutView,
children: [
{
path: 'users',
name: 'users',
component: UserListView
}
]
},
{
path: '/:pathMatch(.*)*',
name: 'not-found',
component: NotFoundView
}
]
})
const app = createApp(App)
app.use(router)
router.isReady().then(() => {
const route = router.currentRoute.value
console.table(
route.matched.map((record) => ({
path: record.path,
name: String(record.name ?? '')
}))
)
app.mount('#app')
})预期输出
访问 /users 时:
path name
/ layout
/users users如果表格为空,检查当前 URL、路由 path、部署基础路径和通配路由顺序。如果只匹配父路由而子页面空白,父级布局必须提供子路由出口。
<!-- src/views/LayoutView.vue -->
<script setup lang="ts">
import { RouterView } from 'vue-router'
</script>
<template>
<main>
<h1>管理后台</h1>
<RouterView />
</main>
</template>预期结果
访问 /users 时先显示“管理后台”,并在其下方渲染 UserListView。检查基础路径与动态导入
应用部署在 /app/ 子目录时,Vite 和 Vue Router 必须使用相同基础路径。不要在每条业务路由前重复写 /app;createWebHistory(import.meta.env.BASE_URL) 会统一处理前缀。
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
base: '/app/',
plugins: [vue()]
})生效行为与验证方法:构建后的 index.html 应引用 /app/assets/...,浏览器访问 /app/users 时路由仍匹配业务路径 /users。若部署在域名根目录,base 使用 /。
动态路由组件应使用可被构建工具静态分析的导入路径。不要把完整文件路径任意拼接成变量;这可能在开发环境看似可用,生产构建后却找不到分片。
const routes = [
{
path: '/users',
component: () => import('./views/UserListView.vue')
}
]验证方法:执行生产构建后检查 dist/assets 存在对应分片,并确认 Network 中该分片返回 200。若刚发布后只有部分用户报错,通常需要同时检查 CDN 缓存:旧 index.html 可能仍引用已经删除的旧哈希文件。
配置服务器回退
使用 createWebHistory() 时,刷新 /users 会先由服务器处理。服务器必须在静态文件不存在时返回入口 index.html,再交给 Vue Router 匹配。Nginx 部署在根目录时可使用:
server {
listen 80;
server_name example.com;
root /srv/vue-app/dist;
location / {
try_files $uri $uri/ /index.html;
}
}验证方法
# 将 <HOST> 替换为实际域名或主机地址
curl -i "http://<HOST>/users"预期输出
HTTP/1.1 200 OK
Content-Type: text/html
...
<div id="app"></div>域名、响应头和 HTML 细节会不同;关键是深层路由返回 200 且响应体为当前应用入口。若应用部署在 /app/,回退目标也应是 /app/index.html,并确保服务器别名或根目录与该路径一致。不要把所有 404 都无条件回退:/api/、上传文件和真实静态资源应使用独立 location,否则后端错误可能被伪装成 HTML 200。
排障清单
- 确认入口组件包含顶层
<RouterView />,嵌套路由的父组件也包含子级出口。 - 查看
router.currentRoute.value.matched;为空时检查 path、重定向、路由顺序和 history base。 - 查看 Network 中文档、JS、CSS 和动态分片状态码,区分入口 404 与资源 404。
- 本地执行生产构建和预览,避免只依据开发服务器结果判断。
- 检查服务器回退、反向代理前缀、CDN 缓存及新旧哈希文件是否同时一致。
- 用
/:pathMatch(.*)*提供应用内 404 页面,但不要把它误认为服务器回退配置。
速查结论:刷新即 404 先修服务器回退;资源 404 先对齐 base;matched 为空修路由表;matched 正常但空白则检查动态导入、运行时异常和各级 <RouterView />。
处理 Store 在 Pinia 安装前或应用上下文之外调用产生的错误。
排查 Pinia 未激活
当控制台出现 getActivePinia() 或 “no active Pinia” 错误时,优先检查 useStore() 的调用时机和 Pinia 实例来源。目标是保证 Store 只在 app.use(pinia) 之后创建,或显式接收同一个 Pinia 实例。
典型触发条件
常见原因是模块顶层提前执行 useStore():导入路由、请求客户端或工具模块时,代码已经创建 Store,但应用尚未安装 Pinia。多应用、SSR、单元测试中混用了不同实例,也会得到相同错误。
// 错误示例:模块一被导入就立即执行
import { useAuthStore } from '@/stores/auth'
export const authStore = useAuthStore()这段是片段示例,依赖应用上下文;若它在 app.use(pinia) 前被导入,初始化阶段会直接抛错。预期错误
[🍍]: "getActivePinia()" was called but there was no active Pinia.安装修复
先创建并安装 Pinia,再调用 Store。应用入口、路由守卫和外部模块应复用同一个实例;在组件外调用时,显式传入 pinia 最稳妥。
// src/stores/auth.ts
import { defineStore } from 'pinia'
export const useAuthStore = defineStore('auth', {
state: () => ({ signedIn: false })
})
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import { useAuthStore } from './stores/auth'
const app = createApp(App)
const pinia = createPinia()
app.use(pinia)
// 组件外调用时显式传入已安装的实例,避免依赖隐式活动上下文
const authStore = useAuthStore(pinia)
console.info(`Pinia ready: ${authStore.$id}`)
app.mount('#app')预期输出
Pinia ready: auth看到 Store ID 且页面正常挂载,说明入口顺序和实例引用一致。
高频修复
路由守卫不要在路由模块顶层创建 Store,可在守卫回调内调用,或由入口把 pinia 传给注册函数。测试中每个用例先执行 setActivePinia(createPinia());SSR 中每个请求创建独立 Pinia,禁止跨请求复用。
风险与边界
直接调用 setActivePinia() 可以临时消除报错,但在生产应用中可能掩盖实例串用,导致 Store 状态写入错误应用。安全替代方案是通过参数传递 Pinia,并保证创建、安装和使用顺序可追踪。
排障清单
- 搜索所有模块顶层的
useXxxStore(),改到函数或生命周期内部。 - 确认
app.use(pinia)位于首次 Store 调用之前。 - 检查是否创建了多个
createPinia(),以及调用方是否传错实例。 - 测试、SSR、微前端场景分别隔离 Pinia 生命周期。
检查变量前缀、模式文件、服务重启和构建时注入规则。
排查环境变量未定义
当 import.meta.env 中目标变量为 undefined 时,依次核对变量前缀、当前 mode、环境文件名、开发服务重启和构建时注入。以下检查适用于 Vite 驱动的 Vue 3 项目。
基本规则
客户端变量默认必须以 VITE_ 开头,并通过 import.meta.env.VITE_NAME 读取。环境文件在开发服务启动或构建时加载,修改文件后必须重启;变量值默认按字符串处理。
# .env.staging
VITE_API_BASE_URL=https://staging.example.com
VITE_FEATURE_FLAG=true配置生效后,使用 staging mode 启动或构建才能读取 .env.staging。.env.local 和 .env.staging.local 通常用于本机覆盖,不应提交敏感内容。
验证当前注入
创建一个最小检查脚本,只打印变量是否存在和当前 mode,不要在日志中输出令牌或密码。
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
console.info('mode:', import.meta.env.MODE)
console.info('api configured:', Boolean(apiBaseUrl))
console.info('api base:', apiBaseUrl ?? '<undefined>')使用目标 mode 启动开发服务:
npm run dev -- --mode staging预期输出
mode: staging
api configured: true
api base: https://staging.example.com端口和启动时间可能不同;判断重点是 mode 与目标文件一致,且变量不再为 <undefined>。
高频原因
- 写成
API_BASE_URL,未使用默认的VITE_前缀。 - 文件名与 mode 不匹配,例如启动
development却只配置.env.staging。 - 修改
.env*后没有重启开发服务器。 - 使用
process.env读取 Vite 客户端变量,或把变量名写成动态索引。 - Docker、Nginx 或容器运行时才设置变量,但前端资源已在更早的构建阶段完成替换。
构建时边界
Vite 客户端环境变量会进入构建产物,不是部署后自动读取的服务器环境。若同一构建产物需要在多个环境复用,应在运行时加载独立配置文件或由后端接口提供公开配置,而不是期待容器环境覆盖已打包的值。
风险与安全替代
任何暴露给客户端的变量都可能被用户查看。把数据库密码、私钥或服务端令牌放入 VITE_* 会随产物泄露;安全替代是只在服务端保存秘密,由前端调用受控接口。
排障清单
- 执行目标 mode,并确认对应
.env.[mode]文件位于项目根目录。 - 检查变量名大小写和
VITE_前缀。 - 重启开发服务,删除旧构建产物后重新构建。
- 在代码中记录
import.meta.env.MODE和布尔存在性,不打印敏感值。 - 若构建后仍缺失,检查 CI 是否在构建步骤前注入变量。
避免直接渲染不可信 HTML,并在确需使用时先进行可靠净化。
防止 v-html 注入
v-html 只用于渲染已经净化的可信富文本。它会把字符串直接写入 DOM,不像 {{ value }} 那样自动转义;评论、URL 参数、localStorage、接口返回和数据库历史内容只要可被攻击者影响,都应视为不可信。
安全用法
普通文本直接使用插值。确需保留 <p>、<strong> 等富文本标签时,在进入 v-html 前使用维护中的净化库,并用允许列表限制标签和属性。
npm install dompurify
npm ls dompurify --depth=0预期输出
<PROJECT>@<VERSION> <PATH>
└── dompurify@<VERSION><PROJECT>、<VERSION> 和 <PATH> 取决于当前项目,看到顶层依赖 dompurify 即表示安装成功。
<script setup lang="ts">
import { computed, ref } from 'vue'
import DOMPurify from 'dompurify'
const rawHtml = ref(
'<p>Hello <strong>Vue</strong><img src=x onerror="alert(1)"></p>' +
'<a href="javascript:alert(2)">打开</a>'
)
const safeHtml = computed(() =>
DOMPurify.sanitize(rawHtml.value, {
// 只开放业务确实需要的富文本能力,其他标签和属性全部移除。
ALLOWED_TAGS: ['p', 'strong', 'em', 'a'],
ALLOWED_ATTR: ['href', 'title']
})
)
</script>
<template>
<article v-html="safeHtml"></article>
</template>预期结果
页面显示“Hello Vue”和“打开”,其中 Vue 保持加粗。
img、onerror 和 javascript: 链接不会生效,也不会弹出 alert。高频用法
仅展示文字时使用 {{ content }},不要为了换行或样式改用 v-html。富文本来自 CMS 或编辑器时,服务端应先做权威净化,浏览器端再做防御性净化;若只需要 Markdown,关闭原始 HTML,并限制链接协议和图片来源。
净化必须是最后一次字符串变换。先净化再拼接用户输入、用正则替换标签,或把净化结果写入另一个 innerHTML 后追加未净化内容,都会重新引入注入点。
风险与边界
触发条件是攻击者能够控制任意 HTML 片段或危险 URL。可能后果包括窃取页面数据、冒用登录态发起操作、钓鱼覆盖和持久化 XSS。安全替代方案是文本插值、结构化组件渲染,或服务端允许列表净化后再配合 CSP;CSP 只能降低影响,不能代替净化。
不要随意允许 style、iframe、svg、事件属性或未知协议。业务确需扩展允许列表时,先为新增标签和属性补充恶意样例测试,再逐项开放。
排障清单
- 在 Vue Devtools 或断点中检查传给
v-html的必须是safeHtml,不是原始值。 - 用
onerror、javascript:和畸形嵌套标签验证净化结果,不要只测正常富文本。 - 内容被误删时缩小到具体标签或属性调整允许列表,不要关闭净化器。
- 发现历史内容曾未经净化入库时,重新清洗存量数据并轮换可能暴露的令牌。
兼容性
上例适用于浏览器端 Vue 3 与 Vite。SSR 环境不要直接依赖浏览器 DOM;应使用支持服务端 DOM 的净化方案,或在服务端完成净化,并保证服务端与客户端规则一致,避免水合结果不一致。
识别会进入浏览器构建产物的配置,禁止存放服务端密钥和长期凭证。
避免泄露前端密钥
凡是发送到浏览器的 JavaScript、Source Map、HTML、请求头和运行时配置都应视为公开信息。Vite 的 VITE_* 变量会被写入客户端构建产物;代码压缩、变量改名、关闭控制台或把文件加入 .gitignore 都不能把其中的密钥变成秘密。
暴露边界
前端可以保存公开 API 地址、公开分析标识和非敏感功能开关,但不能保存第三方 API Secret、数据库密码、私钥、长期访问令牌或可绕过服务端授权的签名密钥。静态站点部署后,所谓“运行时环境变量”最终仍会以可读取形式交给浏览器。
还要检查 vite.config.* 中的 define、loadEnv 和 envPrefix。把完整 process.env 注入前端,或把 envPrefix 放宽为空字符串,会绕过 Vite 默认的暴露边界。
推荐架构
浏览器只调用自己的后端接口,后端从部署平台的 Secret Store 或进程环境读取密钥,再执行受限的第三方调用、签名或数据访问;返回给浏览器的响应必须去除密钥、上游调试信息和内部凭证。

下面的完整示例让服务端使用环境变量完成 HMAC,浏览器或调用方只能得到签名结果,无法读取原始密钥。保存为 server.mjs。
import { createHmac } from 'node:crypto'
import { createServer } from 'node:http'
const secret = process.env.SIGNING_SECRET
if (!secret) {
console.error('SIGNING_SECRET is required')
process.exit(1)
}
const server = createServer((req, res) => {
if (req.method !== 'GET' || req.url !== '/api/sign-demo') {
res.writeHead(404, { 'content-type': 'application/json' })
res.end(JSON.stringify({ error: 'not_found' }))
return
}
// 密钥只参与服务端计算,响应中只返回业务需要的派生结果。
const signature = createHmac('sha256', secret)
.update('demo-request')
.digest('hex')
res.writeHead(200, { 'content-type': 'application/json' })
res.end(JSON.stringify({ signature }))
})
server.listen(3000, '127.0.0.1', () => {
console.log('listening on http://127.0.0.1:3000')
})运行命令
SIGNING_SECRET='server-only-demo' node server.mjs预期输出
listening on http://127.0.0.1:3000在另一个终端验证接口。
curl -s http://127.0.0.1:3000/api/sign-demo预期输出
{"signature":"7b3a501bc0176f5cead3de0e642fd3826a25db619931ce3251392816ce9788fb"}生产环境不要提供可对任意输入签名的通用接口;应校验身份、固定允许的业务动作,并设置权限、频率和审计限制。
构建后验证
构建完成后扫描 dist,用于阻止明显的密钥格式进入发布物。正则应按团队实际密钥前缀补充。
npm run build
if grep -R -n -E 'sk_live_|BEGIN (RSA|OPENSSH) PRIVATE KEY|SIGNING_SECRET' dist; then
echo 'secret-like content found'
exit 1
else
echo 'no secret-like content found'
fi预期输出
no secret-like content found扫描只能发现已知模式,不能证明绝对安全。还应检查 Source Map、浏览器 Network、前端错误上报、日志平台和 Git 历史,并在 CI 中使用专用 secret scanner。
风险与边界
触发条件是密钥被写入 VITE_*、客户端源码、公开配置接口、请求头、Source Map 或提交历史。可能后果包括第三方额度被盗用、数据泄露、越权访问和持续产生费用。安全替代方案是服务端代理、短时且限权的临时凭证,或由身份提供商签发的用户级令牌。
一旦确认泄露,先在上游平台撤销或轮换密钥,再删除发布物和缓存;只从 Git 删除字符串并不能使已泄露凭证失效。
排障清单
- 搜索源码中的
VITE_、define、loadEnv、process.env和密钥固定前缀。 - 在生产构建而不是开发源码中复查,因为替换和内联发生在构建阶段。
- 检查浏览器请求头、响应体和错误监控,确认后端没有把上游凭证回传。
- 对必须下发的临时令牌设置最小权限、短过期时间、受众限制和服务端撤销能力。
在组件卸载时移除事件监听、定时器、订阅和未完成请求。
清理组件副作用
用于组件离开页面时停止由组件主动创建的外部工作,避免卸载后仍执行回调、重复订阅、占用连接,或让旧请求覆盖新页面状态。原则是“在哪里创建,就保存清理句柄,并在同一作用域统一释放”。
基本做法
onUnmounted() 适合清理不依赖现存 DOM 的资源;若第三方实例的 destroy() 必须读取组件 DOM,则改用 onBeforeUnmount()。Vue 会停止在 setup() 中同步创建的计算属性和侦听器,但浏览器事件、定时器、连接及异步创建的侦听器仍需手工释放。
下面的完整组件同时演示窗口事件、轮询定时器和可取消异步任务。异步任务用本地延迟模拟,因此不依赖后端接口。
<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue'
const ticks = ref(0)
const status = ref('等待挂载')
let intervalId: number | undefined
const controller = new AbortController()
function handleResize() {
console.log(`viewport=${window.innerWidth}`)
}
function mockRequest(signal: AbortSignal): Promise<string> {
return new Promise((resolve, reject) => {
const timeoutId = window.setTimeout(() => {
signal.removeEventListener('abort', onAbort)
resolve('请求完成')
}, 5000)
function onAbort() {
window.clearTimeout(timeoutId)
reject(new DOMException('Aborted', 'AbortError'))
}
signal.addEventListener('abort', onAbort, { once: true })
})
}
onMounted(() => {
window.addEventListener('resize', handleResize)
intervalId = window.setInterval(() => {
ticks.value += 1
}, 1000)
status.value = '运行中'
void mockRequest(controller.signal)
.then((result) => {
status.value = result
})
.catch((error: unknown) => {
if (error instanceof DOMException && error.name === 'AbortError') {
console.log('request aborted')
return
}
console.error(error)
})
})
onUnmounted(() => {
window.removeEventListener('resize', handleResize)
if (intervalId !== undefined) window.clearInterval(intervalId)
controller.abort()
})
</script>
<template>
<p>{{ status }},计时:{{ ticks }}</p>
</template>预期结果
挂载后页面显示:运行中,计时:0
每秒计数加 1;停留 5 秒后状态变为“请求完成”
若 5 秒内切换路由卸载组件,控制台输出:request aborted
卸载后继续缩放窗口,不再输出 viewport 日志常见资源与清理动作
| 创建动作 | 卸载时处理 | 关键要求 |
|---|---|---|
addEventListener() |
removeEventListener() |
目标、事件名、函数引用和捕获选项保持一致 |
setInterval() / setTimeout() |
clearInterval() / clearTimeout() |
保存每一个 ID,包括递归定时器 |
subscribe() |
调用返回的 unsubscribe() |
不要只把订阅对象置空 |
fetch(..., { signal }) |
AbortController.abort() |
将 AbortError 视为主动取消,不提示业务失败 |
WebSocket / EventSource |
close() |
同时停止重连定时器 |
| 图表、编辑器等实例 | destroy() / dispose() |
需要访问 DOM 时在 onBeforeUnmount() 执行 |
风险与边界
<KeepAlive> 只会停用组件,不会立即卸载;需要在切走时暂停轮询或连接,应配合 onDeactivated(),返回时再用 onActivated() 恢复。若把侦听器放进 setTimeout()、Promise 回调等异步位置创建,需保存其停止函数并在卸载时调用。
不要用新的匿名函数移除旧监听,例如注册和移除分别写两个 () => handler(),两者引用不同,监听不会被删除。安全做法是先声明具名函数,再用同一引用完成注册和移除。
排障清单
- 反复进入、离开页面后,监听器数量和网络连接数不应持续增长。
- 卸载后不应再出现定时日志、状态写入或“组件已卸载仍更新”的异常。
- 所有订阅都能找到对应的取消函数,所有请求都能找到对应的控制器。
- 第三方实例已调用官方销毁 API,而不是仅删除变量引用。
- 开发者工具中保留对象数量持续增长时,检查闭包是否仍引用组件状态。
使用浅层响应式、不可变数据和组件拆分降低大对象更新成本。
优化大型响应式数据
当大数组或深层对象在一次渲染中触发大量代理访问、依赖收集和组件更新时,可把深层响应式改为浅层响应式,并用不可变替换触发更新。先用性能面板确认瓶颈;普通表单和中小对象通常不需要这类优化。
主方案
shallowRef() 只跟踪 .value 的替换,不递归代理内部对象。读取大型数据仍是普通对象访问,更新时复制必要层级并替换根引用,Vue 才会重新计算依赖。
<script setup lang="ts">
import { computed, shallowRef } from 'vue'
type Row = {
id: number
name: string
metrics: {
score: number
}
}
const rows = shallowRef<Row[]>(
Array.from({ length: 50000 }, (_, index) => ({
id: index + 1,
name: `row-${index + 1}`,
metrics: { score: 0 }
}))
)
// 示例只渲染前 5 条,避免把响应式开销与海量 DOM 开销混在一起。
const visibleRows = computed(() => rows.value.slice(0, 5))
function increaseFirstScore() {
const first = rows.value[0]
if (!first) return
const next = rows.value.slice()
next[0] = {
...first,
metrics: {
...first.metrics,
score: first.metrics.score + 1
}
}
rows.value = next
}
</script>
<template>
<button @click="increaseFirstScore">首条分数 +1</button>
<p>总记录数:{{ rows.length }}</p>
<ul>
<li v-for="row in visibleRows" :key="row.id">
{{ row.name }}:{{ row.metrics.score }}
</li>
</ul>
</template>预期结果
初始显示总记录数 50000,前 5 条分数均为 0
每次点击“首条分数 +1”,row-1 的分数增加 1
其余 49999 个对象保持原引用,不会被递归转换为深层响应式代理方案选择
| 方案 | 适用情况 | 更新约束 |
|---|---|---|
shallowRef() |
大型数组、树或只读快照 | 修改后替换整个 .value |
shallowReactive() |
只关心根属性变化的大对象 | 嵌套对象仍是普通对象 |
| 不可变数据 | 需要可预测更新、撤销或时间旅行 | 只复制变更路径,复用未变对象 |
markRaw() |
图表实例、编辑器实例、静态索引等不应代理的对象 | 该对象内部变化不会驱动视图 |
大型列表应由父组件持有集合,把稳定的单行数据传给行组件,使局部变化限制在对应子树。若同时挂载成千上万个节点,需再使用分页或虚拟列表;组件拆分和浅层响应式不能消除 DOM 数量本身的成本。
风险与边界
直接执行 rows.value[0].metrics.score++ 不会触发 shallowRef() 更新,因为根引用没有变化;后果是数据已改变但界面仍显示旧值。安全做法是复制变更路径并重新赋值,只有明确掌握依赖关系时才使用 triggerRef() 强制刷新。
不要把浅层响应式对象嵌进深层响应式树后再混合修改,这会形成局部语义不一致,排查时很难判断哪一层会触发更新。大型不可变数组每次整体复制也会产生内存和时间成本;高频单点更新可改为按 ID 归一化、分块存储或把热数据拆成独立 ref()。
验证与排障
- 使用同一数据集和同一交互录制优化前后的 Performance 轨迹,比较脚本执行和组件更新时间。
- Vue Devtools 中确认一次单行更新没有导致整棵列表组件无条件重渲染。
- 若脚本耗时下降但页面仍卡顿,检查是否一次渲染了过多 DOM,优先分页或虚拟化。
- 若界面不更新,先检查是否只改了深层属性而没有替换浅层根引用。
- 若内存峰值升高,检查不可变更新是否复制了整棵对象树,而不是仅复制变更路径。