Vue / 知识点
Vue 3 开发速查手册
手册条目
使用官方脚手架创建新的 Vue 3 项目并选择 TypeScript、路由和状态管理能力。
初始化 Vite 项目
需要创建新的 Vue 3 单页应用,并在脚手架阶段一次启用 TypeScript、Vue Router 和 Pinia 时使用本条目。最终会得到一个基于 Vite、可直接安装依赖并启动的项目目录。
命令定位
在准备存放项目的父目录执行 create-vue。开始前确认 node -v 和 npm -v 能正常输出;若脚手架提示 Node.js 版本不满足要求,先升级 Node.js,再重新创建项目。
node -v
npm -v预期输出
v<NODE_VERSION>
<NPM_VERSION>版本号因本机环境而异;命令不可用时,说明 Node.js 或 npm 尚未正确安装,或终端的 PATH 未刷新。
高频用法
推荐使用 Vue 官方脚手架的交互模式,项目名示例为 vue-admin-app。依次选择 TypeScript、Vue Router 和 Pinia,其余测试、格式化与调试选项按团队规范决定。
npm create vue@latest预期输出
✔ Project name: … vue-admin-app
✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
...
Scaffolding project in ./vue-admin-app...
Done.提示项可能随 create-vue 版本调整,但核心读取方式不变:确认项目名正确,并检查 TypeScript、Router、Pinia 三项均选择 Yes。
项目生成后进入目录并安装锁定依赖。首次安装会创建或更新 package-lock.json,后续团队成员应优先使用该锁文件保持版本一致。
cd vue-admin-app
npm install预期输出
added <COUNT> packages, and audited <COUNT> packages in <TIME>
found 0 vulnerabilities包数量、耗时和审计结果会随版本及网络环境变化。若审计结果不为零,不要直接执行带 --force 的自动修复,应先确认升级是否会引入破坏性变更。
输出与验证
检查脚手架是否真正加入三项能力,而不是只依赖交互记录。以下命令读取 package.json 中的关键依赖;版本号为动态值。
npm pkg get dependencies.vue dependencies.vue-router dependencies.pinia devDependencies.typescript预期输出
{
"dependencies.vue": "^<VERSION>",
"dependencies.vue-router": "^<VERSION>",
"dependencies.pinia": "^<VERSION>",
"devDependencies.typescript": "~<VERSION>"
}四个字段都有版本值,表示 Vue、路由、状态管理和 TypeScript 已写入项目配置。某字段返回空值时,通常是创建时未选择对应能力,应重新创建项目,或在确认入口配置后手动补装。
风险与边界
不要在含有重要文件的非空目录中直接使用 . 作为项目名,文件冲突可能导致创建失败或覆盖同名模板文件。安全做法是创建新的独立目录,确认生成结果后再迁移已有代码。
不要混用 npm、pnpm、Yarn 和 Bun 安装同一份依赖,否则多个锁文件可能让本地与 CI 解析出不同版本。项目已经生成 package-lock.json 时,继续使用 npm;切换包管理器前应删除旧锁文件和 node_modules,再统一重新安装。
排障清单
- 出现
Unsupported engine或 Node.js 版本提示:升级 Node.js,关闭并重新打开终端后再次检查node -v。 - 包下载超时或连接重置:先检查代理、DNS 和 npm registry 配置,不要反复删除项目目录。
- 目录已存在或文件冲突:换用新的项目名,或先备份并清空目标目录。
- 安装后缺少 Router 或 Pinia:检查
package.json与src/main.ts,确认依赖存在且插件已通过app.use(...)注册。
兼容性
使用其他包管理器时,创建命令分别为 pnpm create vue@latest、yarn create vue@latest 或 bun create vue@latest。同一项目只保留一种锁文件,并使用对应的安装与脚本命令。
安装项目依赖并启动支持热更新的本地开发服务器。
启动开发服务器
需要安装项目依赖并启动带热更新的本地 Vue 3 开发环境时使用本条目。成功后终端会给出本机访问地址;修改 .vue、.ts 或样式文件时,浏览器通常会自动更新。
基本用法
先进入包含 package.json 的项目根目录,再安装依赖并执行 dev 脚本。已有可信 package-lock.json 的 CI 或全新检出环境可用 npm ci,日常本地开发通常使用 npm install。
cd vue-admin-app
npm install
npm run dev预期输出
> vue-admin-app@<VERSION> dev
> vite
VITE v<VITE_VERSION> ready in <TIME> ms
➜ Local: http://localhost:5173/
➜ press h + enter to show help浏览器打开 Local 后能看到项目首页,说明依赖安装、Vite 配置和入口模块均已正常加载。版本、耗时和端口可能不同;默认端口占用时,Vite 通常会尝试下一个可用端口。
常用参数
需要让同一局域网设备访问、固定端口并自动打开浏览器时,把参数放在 npm 的 -- 之后,确保它们传递给 Vite。
# 0.0.0.0 会监听所有网络接口;只在可信网络中使用
npm run dev -- --host 0.0.0.0 --port 5173 --strictPort --open预期输出
VITE v<VITE_VERSION> ready in <TIME> ms
➜ Local: http://localhost:5173/
➜ Network: http://<LAN_IP>:5173/--host 0.0.0.0 生成 Network 地址;--port 5173 指定端口;--strictPort 在端口被占用时直接失败,避免服务静默切换端口;--open 在启动后打开默认浏览器。
依赖预构建缓存异常、链接本地包后代码未更新或模块解析结果明显过时时,可临时强制重新优化依赖。
npm run dev -- --force预期输出
Re-optimizing dependencies because vite --force was used
VITE v<VITE_VERSION> ready in <TIME> ms只在缓存或依赖优化确有异常时使用 --force。频繁使用会增加启动耗时,也可能掩盖锁文件、包版本或模块入口配置问题。
输出字段说明
Local 是当前计算机可访问的地址;Network 仅在监听非本地主机接口时出现;ready in <TIME> ms 表示开发服务器已完成启动准备。终端持续占用是正常现象,按 Ctrl+C 才会停止服务。
Vite 的热更新依赖文件监听和浏览器 WebSocket。修改组件后页面局部更新且状态尽量保留,说明 HMR 正常;若每次都整页刷新,应检查循环依赖、插件处理能力和文件导入路径大小写。
风险与边界
使用 --host 0.0.0.0 时,同一网络中的其他设备可能访问开发服务器;若应用连接了测试账号、内部接口或包含未保护的环境变量,可能造成信息暴露。安全替代方案是默认仅监听 localhost,确需联调时再临时开放,并配合防火墙限制来源。
Vite 开发服务器面向本地开发,不是生产 Web 服务器。它没有替代生产级反向代理、缓存、安全头、访问控制和稳定性配置;部署前应执行正式构建,再由受控的静态托管或应用服务器提供服务。
排障清单
Missing script: "dev":确认位于正确项目目录,并检查package.json的scripts.dev是否为vite。vite: command not found:依赖尚未安装或node_modules损坏,重新执行npm install;不要全局安装 Vite 代替项目依赖。- 端口占用:结束占用进程、改用
--port <PORT>,或保留--strictPort让错误明确暴露。 - 页面能打开但修改不更新:检查导入文件名大小写是否与磁盘一致;WSL2、容器或网络文件系统还需检查文件监听设置。
- 浏览器无法从其他设备访问:确认使用
--host 0.0.0.0,并检查系统防火墙、虚拟机端口映射和实际Network地址。
兼容性
pnpm、Yarn 和 Bun 的对应命令是 pnpm dev、yarn dev、bun run dev;附加参数时仍需按各包管理器规则传递给 Vite。不要在已有锁文件的项目中临时切换包管理器。
生成生产环境产物并在本地预览构建后的应用。
验证生产构建
用于在提交或部署前确认 Vue 3 应用能生成生产产物,并验证构建后的静态文件可被浏览器正常访问。以下流程以 Vite 项目为例,默认脚本为 build 和 preview。
生成生产产物
先在项目根目录执行构建。团队项目建议先提交并校验锁文件;CI 中可用 npm ci 安装依赖,本地已有可靠依赖时可直接构建。
npm run build预期输出:
> <APP_NAME>@<VERSION> build
> vite build
vite v<VERSION> building for production...
✓ <COUNT> modules transformed.
dist/index.html <SIZE>
dist/assets/index-<HASH>.css <SIZE>
dist/assets/index-<HASH>.js <SIZE>
✓ built in <TIME>看到 dist/ 文件列表和 built in <TIME> 表示构建完成;<VERSION>、<COUNT>、<HASH>、<SIZE> 与 <TIME> 会随项目和环境变化。若 vite.config.* 修改了 build.outDir,产物目录以该配置为准。
本地预览构建结果
preview 只读取已经生成的产物,不会替代 build。指定回环地址和固定端口,可避免误对外暴露并便于自动检查。
npm run preview -- --host 127.0.0.1 --port 4173预期输出:
> <APP_NAME>@<VERSION> preview
> vite preview --host 127.0.0.1 --port 4173
➜ Local: http://127.0.0.1:4173/保持该终端运行,在另一个终端检查首页响应:
curl -I http://127.0.0.1:4173/预期输出:
HTTP/1.1 200 OK
Content-Type: text/html状态码 200 说明入口页可访问;响应头的大小写和附加字段可能不同。还应在浏览器中打开地址,检查控制台报错、静态资源加载、前端路由刷新以及关键接口请求。
高频验证点
- 打开首页和至少一个懒加载路由,确认对应 JS 分块没有
404。 - 直接刷新非首页路由,确认正式 Web 服务器配置了 SPA 回退规则。
- 检查 Network 面板中的资源 URL;部署在子路径时,重点核对 Vite 的
base配置。 - 使用与目标环境一致的环境变量重新构建,因为
VITE_*值通常在构建时写入产物。
风险与边界
vite preview 是本地验收服务器,不适合作为公网生产服务。对外暴露可能缺少正式的 TLS、访问控制、缓存策略、日志和容量保护;安全替代方案是把 dist/ 部署到经过配置的 Nginx、对象存储或静态托管平台。
本地成功只证明当前依赖、Node.js 版本和环境变量组合可构建,不能替代 CI 验证。为减少“本机成功、流水线失败”,应在干净环境执行锁文件安装和构建,并固定项目支持的 Node.js 版本。
排障清单
Missing script: build:检查package.json的scripts.build,Vite 项目通常为vite build。- 构建成功但页面空白:查看浏览器控制台,优先检查资源路径、运行时异常和错误的环境变量。
- 静态资源
404:核对base、部署子目录和服务器根目录是否指向实际产物目录。 - 端口被占用:改用
--port <PORT>;实际端口需同步到验证地址。 - 本地路由正常、正式环境刷新
404:为生产服务器配置 history fallback,而不是修改前端路由来掩盖问题。
速查结论:先 npm run build,再用 npm run preview 读取产物,最后同时验证 HTTP 状态、浏览器控制台、资源路径和路由刷新。
在 Vue 组件和工程配置中启用 TypeScript 类型检查。
启用 TypeScript
用于在现有 Vue 3 与 Vite 工程中启用组件类型、严格编译检查和独立的 vue-tsc 校验。关键点是同时配置 TypeScript、在单文件组件中声明 lang="ts",并把类型检查接入构建流程。
安装类型检查工具
在项目根目录安装开发依赖。@vue/tsconfig 提供适合 Vue 浏览器项目的基础配置,vue-tsc 负责理解 .vue 文件中的模板和脚本类型。
npm install -D typescript vue-tsc @vue/tsconfig --silent
npm ls --depth=0 typescript vue-tsc @vue/tsconfig预期输出:
<APP_NAME>@<VERSION> <PATH>
├── @vue/tsconfig@<VERSION>
├── typescript@<VERSION>
└── vue-tsc@<VERSION><APP_NAME>、<VERSION> 和 <PATH> 会随项目变化;三项依赖均列出且命令退出码为 0 即表示安装成功。若项目使用 pnpm 或 Yarn,应使用同一锁文件对应的包管理器,避免生成第二份锁文件。
配置 TypeScript
在项目根目录创建或合并 tsconfig.json。不要直接覆盖已有的路径别名、项目引用或测试配置。
{
"extends": "@vue/tsconfig/tsconfig.dom.json",
"include": [
"env.d.ts",
"src/**/*",
"src/**/*.vue"
],
"compilerOptions": {
"strict": true,
"noEmit": true
}
}同时创建 env.d.ts,让 TypeScript 识别 Vite 注入的模块和环境变量类型。
/// <reference types="vite/client" />将以下脚本合并进现有 package.json。这是片段示例,只替换或补充 scripts 中的对应键,不要用它覆盖完整文件。
{
"scripts": {
"type-check": "vue-tsc --noEmit",
"build": "npm run type-check && vite build"
}
}noEmit 表示只检查类型、不生成 JavaScript;实际打包仍由 Vite 完成。把 type-check 放在 build 前面,可阻止类型错误进入生产产物。
在组件中声明类型
下面是完整的 Vue 单文件组件,可保存为 src/components/CounterButton.vue。lang="ts" 启用 TypeScript,defineProps 和 ref 会保留可推断类型。
<script setup lang="ts">
import { ref } from "vue"
const props = defineProps<{
initial?: number
}>()
const count = ref(props.initial ?? 0)
function increment(step: number = 1): void {
count.value += step
}
</script>
<template>
<button type="button" @click="increment()">
Count: {{ count }}
</button>
</template>在父组件中正常导入后,传入非数字的 initial 会被类型检查发现;编辑器也能为属性、事件和模板表达式提供补全。
执行类型检查
运行独立检查,适合提交前、CI 或只想验证类型而不生成产物的场景。
npm run type-check预期输出:
> <APP_NAME>@<VERSION> type-check
> vue-tsc --noEmit成功时通常没有额外诊断并以退出码 0 结束。出现错误时,输出会包含文件路径、行列号、错误码和说明;先修复首个根因,再重新执行,避免被连锁错误干扰。
风险与边界
Vite 的生产构建主要负责转译和打包,不能把“打包成功”当作“类型正确”。若保留默认的 vite build 而不运行 vue-tsc,类型错误可能仍生成产物;安全替代方案是使用上面的串联脚本,或在 CI 中分别执行 npm run type-check 与 npm run build。
不要为快速通过检查而全局使用 any、关闭 strict 或添加大范围忽略规则,这会把问题推迟到运行时。第三方包缺少类型时,优先安装官方类型包、升级依赖或编写最小的局部声明文件,并明确限制声明覆盖范围。
排障清单
.vue文件仍按 JavaScript 检查:确认<script setup lang="ts">或<script lang="ts">已声明。Cannot find module "*.vue":确认使用vue-tsc,并且tsconfig.json的include覆盖src/**/*.vue。ImportMetaEnv或资源导入缺少类型:确认根目录存在引用vite/client的env.d.ts。- 编辑器与命令行结果不同:重启 TypeScript/Vue 语言服务,并确认编辑器使用工作区内的 TypeScript。
- 构建仍未拦截类型错误:检查
package.json的build是否先执行type-check,以及 CI 是否调用了同一脚本。
兼容性
以上配置适用于 Vue 3、Vite 和现代 TypeScript 项目。使用 Vue CLI、Nuxt 或多 tsconfig 项目引用时,构建脚本和配置入口不同,但 .vue 类型检查仍应由与框架版本匹配的 vue-tsc 或框架专用检查命令完成。
为源码目录设置稳定的导入别名并同步编辑器类型解析。
配置路径别名
当组件层级变深、相对路径出现 ../../../ 时,用 Vite 别名稳定运行时导入,并在 TypeScript 配置中同步同一映射,确保构建、类型检查和编辑器跳转得到一致结果。
配置位置
Vite 负责开发服务器与构建时解析,TypeScript 负责类型检查和编辑器导航。两处都要配置;只改其中一处,通常会出现“页面能运行但编辑器报错”或“编辑器正常但构建失败”。
现代 Vue 3 项目通常把应用源码配置写在 tsconfig.app.json。如果项目只有一个 tsconfig.json,则把相同的 baseUrl 和 paths 写入该文件。
主配置
在 vite.config.ts 中把 @ 指向绝对的 src 目录。使用 import.meta.url 可兼容 Vite 的 ESM 配置文件,不依赖 CommonJS 的 __dirname。
import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
// 使用绝对路径,避免别名随启动目录变化
"@": fileURLToPath(new URL("./src", import.meta.url))
}
}
});在 tsconfig.app.json 的 compilerOptions 中加入匹配规则。下面是片段示例,应合并到现有配置,保留项目原有的 include、lib 和严格模式选项。
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}paths 只告诉 TypeScript 如何解析模块,不会替代 Vite 的 resolve.alias,因此两边的别名名称和目标目录必须一致。
使用与验证
新建 src/config/app.ts:
export const appName = "Vue Alias Demo";将 src/App.vue 改为以下最小页面,确认别名同时被 Vue、Vite 和 TypeScript 识别。
<script setup lang="ts">
import { appName } from "@/config/app";
</script>
<template>
<h1>{{ appName }}</h1>
</template>执行构建:
npm run build预期结果:命令以退出码 0 结束,页面构建成功;版本号和耗时会随环境变化。
vite v<VERSION> building for production...
✓ built in <TIME>同时打开 @/config/app 可跳转到源文件。若项目提供 type-check 脚本,再运行 npm run type-check,成功时应无类型诊断并以退出码 0 结束。
常见故障
- 编辑器报错但开发页面正常:确认修改的是实际参与项目引用的
tsconfig.app.json,然后重启 TypeScript 服务或 IDE。 - 构建报错但编辑器能跳转:确认
vite.config.ts已配置同名别名,并且目标使用绝对路径。 - 报错无法解析
node:url:确认项目安装了@types/node,且tsconfig没有排除 Node 类型。 - 测试文件解析失败:Vitest 通常复用 Vite 配置;其他测试工具需要在自身配置中补充同一映射。
风险与边界
别名映射错误会让导入指向意外目录,可能在本地通过却在 CI 的大小写敏感文件系统失败。目录名与导入大小写应完全一致,并优先使用少量、语义稳定的别名。不要用别名掩盖跨层级的循环依赖;发现模块相互引用时,应先调整目录职责,而不是继续增加映射。
按开发、测试和生产环境读取 Vite 环境变量。
读取环境变量
Vue 3 在 Vite 项目中通过 import.meta.env 读取环境变量。按模式拆分 .env 文件,并只把允许进入浏览器的值加上 VITE_ 前缀,可在开发、测试和生产构建间切换接口地址与功能开关。
文件与加载规则
Vite 会读取通用文件 .env、本地覆盖文件 .env.local、模式文件 .env.[mode] 和模式本地文件 .env.[mode].local。模式专用值优先于通用值,已存在于启动进程中的系统环境变量优先级更高。
npm run dev 默认使用 development 模式,npm run build 默认使用 production 模式;自定义测试模式可通过 --mode test 启用。
定义变量
分别创建模式文件。所有暴露给客户端代码的自定义变量都必须以 VITE_ 开头。
# .env.development
VITE_API_BASE_URL=http://localhost:3000
VITE_ENABLE_MOCK=true# .env.test
VITE_API_BASE_URL=https://test-api.example.com
VITE_ENABLE_MOCK=false# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_ENABLE_MOCK=false这些文件保存后需重启开发服务器。.env.local 与 .env.[mode].local 常用于机器私有覆盖,通常应加入 .gitignore。
集中读取与类型转换
import.meta.env 中的自定义值都是字符串。集中转换后再导出,可避免在组件内重复比较字符串,并在缺少关键变量时尽早失败。
// src/config/env.ts
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
if (!apiBaseUrl) {
throw new Error("Missing VITE_API_BASE_URL");
}
export const env = Object.freeze({
apiBaseUrl,
enableMock: import.meta.env.VITE_ENABLE_MOCK === "true",
mode: import.meta.env.MODE,
isDev: import.meta.env.DEV,
isProd: import.meta.env.PROD
});将 src/App.vue 改为以下最小验证页面:
<script setup lang="ts">
import { env } from "./config/env";
console.log("runtime env", env);
</script>
<template>
<pre>{{ env }}</pre>
</template>以测试模式启动:
npm run dev -- --mode test预期结果:页面显示测试地址与解析后的布尔值;终端端口可能不同,以实际输出为准。
{
"apiBaseUrl": "https://test-api.example.com",
"enableMock": false,
"mode": "test",
"isDev": true,
"isProd": false
}类型声明
需要严格约束变量名时,可在 src/vite-env.d.ts 中扩展接口。该文件是声明文件,不会产生运行时代码。
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_BASE_URL: string;
readonly VITE_ENABLE_MOCK?: "true" | "false";
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}生效行为:拼错变量名时,编辑器和类型检查会直接报错。运行项目已有的 type-check 脚本可验证声明文件是否被 TypeScript 包含。
风险与排障
带 VITE_ 前缀的值会被打包进浏览器资源,任何用户都能查看。触发条件是变量在客户端代码中被引用;后果是密钥、令牌或数据库密码泄露。安全替代方案是把秘密保留在后端环境变量中,由前端调用受控 API。
变量为 undefined 时,依次检查前缀、当前模式、文件名和开发服务器是否已重启。布尔值判断异常时,不要使用 Boolean("false"),因为结果仍是 true;应显式比较 === "true"。接口地址变更后构建未生效时,确认 CI 在构建阶段注入变量,因为 Vite 环境变量不是部署后自动读取的运行时配置。
通过 Vite 开发服务器代理后端接口并减少本地跨域问题。
配置开发代理
当 Vue 3 页面需要调用本地或测试环境后端时,在 Vite 的 server.proxy 中把同源路径转发到后端。浏览器只请求当前开发服务器,因此通常不再触发浏览器跨域校验;该配置仅在 Vite 开发服务器运行期间生效。
前置条件与基本语法
假设 Vue 项目由 Vite 启动,后端监听 http://localhost:8080,并提供 GET /health。代理键按请求路径前缀匹配;下面把浏览器的 /api/health 转成后端的 /health。
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
server: {
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
// 后端没有 /api 前缀时,在转发前删除它
rewrite: (path) => path.replace(/^\/api/, ''),
},
},
},
})前端请求必须使用 /api/health 这类相对地址;直接请求 http://localhost:8080/health 会绕过 Vite 代理。
验证代理
先在终端 A 启动后端和 Vite,再在终端 B 请求 Vite 端口。<PORT> 以终端实际显示为准,默认通常为 5173。
# 终端 A:保持 Vite 持续运行
npm run dev
# 终端 B:Vite 启动后执行
curl -i http://localhost:<PORT>/api/health预期结果取决于后端响应。若后端约定返回 {"status":"ok"},代理成功时可看到:
HTTP/1.1 200 OK
content-type: application/json
{"status":"ok"}读取方法:状态码来自后端,响应体通过 Vite 代理返回;后端访问日志中的路径应为 /health,而不是 /api/health。
常用参数
target:实际后端地址,必须包含协议和端口。changeOrigin:把转发请求的Host改为目标主机,后端按虚拟主机校验时常用。rewrite:修改转发路径;后端已包含/api前缀时不要删除。ws:代理 WebSocket 时设为true,并确保规则命中升级请求路径。configure:访问代理实例,适合临时记录代理错误,不要长期输出令牌或 Cookie。
高频用法
保留路径前缀时可直接写 '/api': 'http://localhost:8080'。后端路由没有前缀时使用 rewrite。Socket.IO 或原生 WebSocket 需要独立规则并开启 ws: true。使用非相对 base 时,代理键还要包含该 base 前缀。
风险与边界
开发代理不是生产网关。把它当成生产反向代理会导致构建后的静态文件失去转发能力;生产环境应由 Nginx、Ingress、API Gateway 或同域后端承担转发。
规则过宽会把静态资源或内部调试路径也转发出去,造成 404、敏感接口暴露或难以追踪的请求链。优先使用明确前缀,并避免让不可信输入决定代理目标。WebSocket 场景不要随意开启 rewriteWsOrigin,错误改写 Origin 可能扩大跨站请求风险。
排障清单
- 浏览器仍报 CORS:检查请求是否写成绝对 URL,或路径是否未命中代理键。
- 返回 404:对照后端真实路由,确认
rewrite应保留还是删除前缀。 - 返回 502 或
ECONNREFUSED:确认后端已启动;容器内的localhost指向当前容器,不一定是宿主机。 - 登录后 Cookie 丢失:检查后端 Cookie 的
Domain、Path、SameSite和Secure,代理不会自动修正所有属性。 - WebSocket 无法连接:确认规则路径、
ws: true、后端升级协议和代理目标均一致。
检查组件树、响应式状态、事件、路由和 Pinia 数据。
使用 Vue Devtools
当页面状态、组件更新或路由跳转与预期不一致时,用 Vue Devtools 直接查看组件树、响应式状态、事件时间线、Vue Router 路由和 Pinia store。先在最小可复现页面中确认数据如何变化,再回到业务代码定位来源。
安装与启动
Vue 3 项目可安装浏览器扩展;Vite 项目也可使用官方 Vite 插件。插件方案需要 Vite 6 或更高版本,并应只作为开发依赖安装。
npm add -D vite-plugin-vue-devtools预期结果:
package.json 的 devDependencies 中出现 vite-plugin-vue-devtools在 Vite 配置中注册插件:
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
export default defineConfig({
plugins: [
vue(),
vueDevTools(),
],
})启动项目:
npm run dev预期输出:
VITE v<MAJOR>.<MINOR>.<PATCH> ready in <TIME> ms
➜ Local: http://localhost:<PORT>/打开本地页面后,可通过插件入口或浏览器开发者工具中的 Vue 面板进入 Devtools;版本号、启动耗时和端口以本机输出为准。
建立可观察样例
下面的组件同时包含响应式状态和派生状态,适合验证 Devtools 是否正常识别。将其保存为 src/App.vue 后刷新页面。
<script setup lang="ts">
import { computed, ref } from 'vue'
const count = ref(0)
const doubled = computed(() => count.value * 2)
function increment() {
count.value += 1
}
</script>
<template>
<main>
<button type="button" @click="increment">count: {{ count }}</button>
<p>doubled: {{ doubled }}</p>
</main>
</template>预期结果:
页面初始显示:count: 0,doubled: 0
点击一次后:count: 1,doubled: 2
Components 面板选中 App 时,可看到 count 和 doubled 的当前值常用检查路径

在 Components 中先选中异常组件,查看 props、setup state 和计算值;修改可编辑状态只用于验证假设,不要把临时改值当成修复。组件频繁更新时转到 Timeline,结合点击、路由或 store 操作缩小时间范围。使用 Vue Router 时在 Router 查看当前路由、参数和匹配记录;使用 Pinia 时在 Pinia 查看 store 列表、state,并观察 action 前后的变化。
高频用法
定位“值为什么不对”时,从子组件向父组件检查 props 和注入状态。定位“为什么重复渲染”时,在 Timeline 复现一次操作,只分析对应时间窗口。定位“跳错页面”时,对照当前路由的 params、query 和 matched 记录。定位“store 被谁改了”时,先复现单次操作,再结合 Pinia 状态变化和时间线寻找触发点。
风险与边界
Devtools 中直接编辑状态只改变当前运行实例,刷新后通常恢复;把这种变化误认为代码已修复,会让问题在重新加载或其他环境中再次出现。安全做法是先记录原值和触发步骤,再回到源码修改并重新复现。
不要在共享截图、录屏或远程协作中暴露令牌、用户信息、订单数据等敏感状态。调试生产环境时应先脱敏,并优先在受控测试数据中复现。Vue Devtools v7 面向 Vue 3;Vue 2 项目需要使用兼容版本,避免多个扩展版本同时启用。
排障清单
- 看不到 Vue 面板:确认页面确实挂载了 Vue 3 应用,扩展已启用,并刷新页面和开发者工具。
- Components 为空:检查应用是否运行在 iframe、浏览器扩展页或受限制环境;必要时改用 Vite 插件或独立应用。
- Router 或 Pinia 标签缺失:确认项目实际安装并挂载了对应插件,且当前 Devtools 连接的是正确 Vue 应用。
- 状态不更新:先排除页面连接到旧标签页、多个 Vue 实例或热更新残留,重新加载后再复现。
- 打开源码失败:确认使用 Vite 插件并正确配置编辑器;浏览器扩展本身不保证所有“在编辑器中打开”能力。
使用 <script setup> 组织单文件组件的模板、逻辑和样式。
编写 <script setup> 组件
在 Vue 3 单文件组件中,使用 <script setup> 可以直接声明模板所需的状态、计算属性和事件处理函数,无需编写 setup() 或手动 return。适合新组件、组合式 API 组件,以及希望减少样板代码的页面逻辑。
基本结构
<script setup> 中的顶层变量、函数和导入组件会自动暴露给当前模板。样式仍放在 <style> 中;需要限制样式只作用于当前组件时使用 scoped。
将下面内容保存为 src/App.vue,在已有 Vue 3 项目中运行:
<script setup>
import { computed, ref } from 'vue'
const count = ref(0)
const doubled = computed(() => count.value * 2)
function increment() {
count.value += 1
}
</script>
<template>
<main class="counter">
<p>当前值:{{ count }}</p>
<p>两倍值:{{ doubled }}</p>
<button type="button" @click="increment">加一</button>
</main>
</template>
<style scoped>
.counter {
padding: 16px;
}
</style>预期结果:
页面初始显示:
当前值:0
两倍值:0
点击“加一”后显示:
当前值:1
两倍值:2模板会自动解包 ref,所以模板中写 count,脚本中修改时仍需使用 count.value。computed 会在依赖变化后重新计算。
高频用法
接收父组件参数时使用编译宏 defineProps();向父组件发送事件时使用 defineEmits();双向绑定组件值时可使用 defineModel();需要让父组件通过模板引用访问内部方法时使用 defineExpose()。这些宏在 <script setup> 中无需导入。
局部组件只需正常导入即可在模板中使用,例如 import UserCard from './UserCard.vue'。导入名应使用大驼峰,避免与原生 HTML 标签混淆。
风险与边界
触发条件:在脚本中把 ref 当普通值直接执行 count += 1。后果:变量本身不会按预期更新,或产生只读、类型错误。安全做法是在脚本中读写 count.value,只在模板中依赖自动解包。
触发条件:为兼容不同 Vue 3 次版本,直接依赖 defineProps() 解构后的响应式行为。后果:旧版本项目中解构变量可能无法跟随父组件更新。安全替代是使用 const props = defineProps(...) 后读取 props.name,或显式使用 toRefs(props)。
触发条件:把密钥、访问令牌或服务端专用逻辑写进组件。后果:构建后代码可被浏览器用户查看。安全替代是把敏感操作放到服务端,通过受控接口调用。
排障清单
- 模板提示变量未定义:确认变量位于
<script setup>顶层,名称与模板完全一致。 - 点击事件无响应:确认模板使用
@click="increment",函数名未拼错,按钮没有被遮挡或禁用。 - 修改状态后页面不更新:确认状态由
ref()或reactive()创建,而不是普通变量。 - 样式影响其他组件:为当前组件样式添加
scoped,全局样式应单独放入入口样式文件。
兼容性
<script setup> 需要 Vue 3.2 及以上版本。defineModel() 需要较新的 Vue 3 版本;维护旧项目时可使用 modelValue 属性与 update:modelValue 事件实现同等行为。
通过模板插值显示响应式文本并调用简单表达式。
渲染文本
Vue 3 模板使用双大括号插值 {{ ... }} 把响应式状态渲染为文本。插值适合标题、计数、状态提示和简单格式化表达式;状态变化后,页面中的对应文本会自动更新。
基本语法
插值写在元素内容中,表达式可以读取变量、访问属性、执行运算或调用无副作用的格式化函数。属性值不能使用双大括号,应改用 v-bind 或简写形式 :title="message"。
将下面内容保存为 src/App.vue,在已有 Vue 3 项目中运行:
<script setup>
import { computed, ref } from 'vue'
const username = ref('Ada')
const unread = ref(2)
const summary = computed(() => `${username.value} 有 ${unread.value} 条未读消息`)
function markOneRead() {
if (unread.value > 0) {
unread.value -= 1
}
}
</script>
<template>
<main>
<h1>欢迎,{{ username }}</h1>
<p>{{ summary }}</p>
<p>下一次计数:{{ unread + 1 }}</p>
<button type="button" @click="markOneRead">标记一条已读</button>
</main>
</template>预期结果:
页面初始显示:
欢迎,Ada
Ada 有 2 条未读消息
下一次计数:3
点击“标记一条已读”后:
欢迎,Ada
Ada 有 1 条未读消息
下一次计数:2读取结果时重点确认两点:按钮点击后 summary 是否重新计算,以及模板表达式 unread + 1 是否随状态同步变化。
可用表达式
模板插值支持单个 JavaScript 表达式,例如三元运算、字符串拼接、数组读取和函数调用。适合写短小且易读的展示逻辑;复杂判断应移到 computed 中,避免模板难以维护。
不能在插值中写 if、for、变量声明或多条语句。条件显示使用 v-if,列表渲染使用 v-for,事件处理使用 @click 等指令。
输出与转义
插值默认按纯文本输出,字符串中的 <strong> 不会变成 HTML 标签,而会作为文本显示。这能降低把用户输入直接渲染为脚本的风险。
需要渲染 HTML 时只能使用 v-html,并确保内容来自可信来源或已经经过可靠清洗。触发条件是把用户输入、评论或接口返回的未知 HTML 直接交给 v-html;可能后果是跨站脚本攻击。安全替代是继续使用普通插值,或在服务端和前端双重清洗后再渲染。
常见问题
- 页面显示空白:检查变量是否为
null或undefined,并为缺省值提供回退,例如{{ nickname || '访客' }}。 - 页面没有更新:确认数据由
ref()、reactive()或computed()提供,而不是普通常量或被错误解构的响应式对象。 - 属性中原样出现花括号:把
title="{{ message }}"改成:title="message"。 - 表达式过长或重复:提取为
computed,让模板只保留最终展示变量。
速查原则:内容节点用 {{ value }},属性用 :attribute="value",复杂展示逻辑优先放进计算属性。
使用 v-html 输出可信 HTML,并识别不可信内容带来的注入风险。
渲染原始 HTML
当接口返回已经审核过的富文本片段,需要保留其中的标签结构时使用 v-html。它会把表达式结果写入元素的 innerHTML;普通文本优先使用插值或 v-text,不要为了换行、加粗等简单效果引入原始 HTML。
基本语法
v-html="htmlSource" 接收字符串,并替换当前元素原有的子节点。写在该元素内部的插值、组件或静态文本都会被覆盖,而且插入的 HTML 不会再次经过 Vue 模板编译,因此其中的 {{ value }}、v-if 或组件标签不会生效。
主示例
在已创建的 Vue 3 项目中,将以下内容保存为 src/App.vue。示例中的字符串视为服务端审核后返回的可信内容。
<script setup>
const trustedHtml = '<strong>安全提示</strong><p>仅展示服务端已审核内容。</p>'
</script>
<template>
<section class="notice" v-html="trustedHtml"></section>
</template>预期结果
安全提示
仅展示服务端已审核内容。浏览器会创建一个 strong 元素和一个 p 元素,而不是把尖括号原样显示。若改成 {{ trustedHtml }},Vue 会进行转义,页面会直接显示 HTML 字符串。
风险与边界
当内容来自用户输入、URL 参数、第三方接口、可编辑后台或未受信任数据库字段时,v-html 可能把事件属性、危险链接或伪造表单写入页面,导致跨站脚本、账号操作诱导或页面内容被篡改。不要把“来自自己的接口”当作可信证明,因为存储型恶意内容同样可能从后端返回。
安全替代方案是默认使用 {{ content }} 或 v-text;确实需要富文本时,在服务端和前端按允许标签、属性及 URL 协议进行白名单清洗,并尽量限制可用标签。不要依赖简单正则删除 <script>,它无法覆盖事件属性、编码绕过和危险协议。
排障清单
- 页面显示尖括号:检查是否误用了插值,而不是
v-html。 - 原有子组件消失:
v-html会覆盖绑定元素的全部子节点,应把富文本放到独立容器。 - 富文本中的 Vue 指令不生效:这是预期行为;把交互拆成真实 Vue 组件,不要尝试执行后端返回的模板。
- 样式选择器未命中:
scoped样式不会自动给运行时插入的节点加作用域标记,可使用:deep()限定容器内样式,但仍要避免全局污染。
速查原则:只有经过明确清洗并允许以 HTML 渲染的内容才使用 v-html。
使用 v-bind 动态设置元素属性、布尔属性和对象属性集合。
绑定元素属性
需要让 href、src、disabled、aria-*、data-* 等属性随组件状态变化时使用 v-bind。单个属性通常写成 :属性名="表达式",多个属性可以通过 v-bind="对象" 一次绑定。
基本语法
<template>
<img :src="imageUrl" :alt="imageAlt">
<button :disabled="isSubmitting">保存</button>
<a v-bind="linkAttrs">打开文档</a>
</template>: 是 v-bind: 的缩写。属性值可以是变量、计算表达式或对象字段;绑定值为 null 或 undefined 时,Vue 会移除对应属性。对 disabled、checked、required 等布尔属性,绑定 false 会使其不再生效。
主示例
在已创建的 Vue 3 项目中,将以下内容保存为 src/App.vue。对象绑定适合一组需要共同传递的原生属性。
<script setup>
import { ref } from 'vue'
const isSubmitting = ref(true)
const requestId = 'req-42'
const linkAttrs = {
href: '/guide',
target: '_blank',
rel: 'noopener noreferrer',
'aria-label': '打开 Vue 指南'
}
</script>
<template>
<a v-bind="linkAttrs">打开文档</a>
<button
:disabled="isSubmitting"
:data-request-id="requestId"
>
保存
</button>
</template>预期结果
“打开文档”链接指向 /guide,并在新标签页打开。
“保存”按钮处于禁用状态,并带有 data-request-id="req-42"。把 isSubmitting 设为 false 后,按钮恢复可用。data-request-id 和 aria-label 会按原属性名写入 DOM,适合测试定位、埋点和无障碍说明。
高频用法
- 单属性绑定:
:src="avatarUrl"、:href="detailUrl"。 - 布尔属性:
:disabled="loading",不要写成disabled="false";HTML 中只要该静态属性存在,按钮仍会被禁用。 - 对象属性集合:
v-bind="attrs",适合透传aria-*、data-*或链接安全属性。 - 动态属性名:
:[attrName]="value",仅在属性名本身确实动态时使用,避免降低模板可读性。
风险与边界
把不可信值绑定到 href、src、formaction 等 URL 属性时,可能产生危险协议、跳转欺骗或加载非预期资源。对外部 URL 应限制协议和目标域名;新窗口链接同时设置 rel="noopener noreferrer"。不要用对象绑定把未筛选的任意键全部透传到 DOM,应先挑选允许的属性。
排障清单
- 属性没有更新:确认绑定的是响应式状态,并检查更新的是否为模板实际引用的变量。
- 布尔属性表现相反:使用
:disabled="false",不要使用静态字符串disabled="false"。 - 对象绑定覆盖单独属性:同一属性出现多次时不要依赖书写顺序,先在脚本中合并成一个明确对象。
- 组件不接收属性:自定义组件会按 props 和属性透传规则处理;需要绑定原生 DOM 属性时,确认它最终落在目标元素上。
速查原则:单个属性用 :,成组原生属性用 v-bind="对象",URL 和批量透传必须先校验。
根据状态使用字符串、对象或数组动态控制 class 和内联样式。
绑定类与样式
当元素外观需要随组件状态变化时,使用 :class 切换 CSS 类,使用 :style 设置少量运行时样式。优先把可复用视觉规则放进 class,仅将尺寸、坐标或颜色等真正动态的值放进内联样式。
基本语法
:class 接受字符串、对象和数组。对象的键是类名,值决定是否应用;数组可组合固定类、条件对象和计算得到的类名。:style 接受样式对象或对象数组,属性可写成 camelCase,也可使用带引号的 kebab-case。将下列内容保存为已初始化 Vue 3 项目的 src/App.vue。
<script setup>
import { computed, ref } from 'vue'
const active = ref(false)
const level = ref('normal')
const width = ref(60)
const statusClass = computed(() => ({
active: active.value,
danger: level.value === 'danger'
}))
const progressStyle = computed(() => ({
width: `${width.value}%`
}))
</script>
<template>
<button
class="card"
:class="[statusClass, `level-${level}`]"
@click="active = !active"
>
点击切换选中状态
</button>
<select v-model="level">
<option value="normal">普通</option>
<option value="danger">危险</option>
</select>
<input v-model.number="width" type="range" min="0" max="100">
<div class="track">
<div class="progress" :style="progressStyle">{{ width }}%</div>
</div>
</template>
<style scoped>
.card { padding: 8px 12px; border: 1px solid #999; }
.card.active { outline: 2px solid #2563eb; }
.card.danger { color: #b91c1c; }
.level-danger { background: #fee2e2; }
.track { width: 240px; background: #e5e7eb; }
.progress { min-width: 2rem; background: #93c5fd; }
</style>预期结果
点击按钮后出现蓝色轮廓;选择“危险”后文字和背景变为警示样式;拖动滑块时进度条宽度与百分比同步变化。读取方法:在浏览器开发者工具中检查按钮的 class,可看到 active、danger 和 level-danger 按状态增删;检查进度条的 style,可看到 width 实时更新。
高频用法
固定类与条件类组合时,保留静态 class,把变化部分交给 :class,可避免重复拼接。多个条件彼此独立时使用对象;需要按顺序组合多个来源时使用数组;只有一个动态类名时可直接绑定字符串。
样式值依赖响应式数据时,优先使用计算属性返回对象,避免在模板中堆叠复杂表达式。数值型 CSS 属性通常需要单位,例如 width: '60%';少数无单位属性,如 opacity、zIndex,可直接传数字。
风险与边界
不要把用户输入直接作为任意样式对象绑定。触发条件是样式键和值来自未经限制的外部数据,可能造成界面遮挡、内容隐藏或通过 url() 发起非预期资源请求。安全替代方案是建立允许列表,只映射预定义 class 或经过校验的有限样式值。
内联样式优先级通常高于样式表规则,滥用 :style 会让主题覆盖和响应式适配变难。可复用状态应改用语义化 class;只有必须由运行时计算的单个属性才保留为内联样式。
排障清单
类名未生效时,先检查对象值是否为真、类名拼写是否一致,再确认 scoped 样式选择器是否命中。样式未更新时,检查是否通过 ref、reactive 或 computed 提供响应式值,并确认模板中没有把对象误写成普通字符串。
速查:状态切换选 :class,连续数值选 :style;能写进 CSS 的规则不要长期留在模板表达式中。
根据条件选择 v-if、v-else 或 v-show 控制内容显示。
条件渲染内容
需要按状态创建或移除节点时使用 v-if、v-else-if、v-else;需要频繁显示和隐藏但保留节点状态时使用 v-show。选择依据不是语法长短,而是切换频率和隐藏期间是否需要保留 DOM。
基本语法
v-if 为假时不会渲染对应节点,后续分支必须紧邻前一个条件节点。v-show 始终渲染元素,只通过内联 display 控制可见性,因此不能用于 <template>,也没有 v-else 分支。将下列内容保存为已初始化 Vue 3 项目的 src/App.vue。
<script setup>
import { ref } from 'vue'
const role = ref('guest')
const showDetails = ref(false)
</script>
<template>
<label>
角色:
<select v-model="role">
<option value="guest">访客</option>
<option value="member">成员</option>
<option value="admin">管理员</option>
</select>
</label>
<p v-if="role === 'admin'">可管理用户和系统配置</p>
<p v-else-if="role === 'member'">可查看成员内容</p>
<p v-else>请登录后访问更多功能</p>
<button @click="showDetails = !showDetails">
切换详情
</button>
<section v-show="showDetails">
该节点始终存在,仅切换 display。
</section>
</template>预期结果
选择不同角色时,页面只保留对应的一段权限说明;点击“切换详情”时,详情区域反复显示或隐藏,但元素仍保留在 DOM 中。读取方法:在开发者工具的 Elements 面板观察角色说明,未命中的 v-if 分支不会存在;详情关闭后仍可找到 section,其内联样式变为 display: none;。
选择规则
初始条件大多为假、组件创建成本较高或隐藏期间不应继续占用资源时,选择 v-if。例如弹窗首次打开、权限分支、按需加载的大型组件。条件频繁切换、需要保留输入值或组件内部状态时,选择 v-show。
| 场景 | 推荐 | 原因 |
|---|---|---|
| 很少切换的面板 | v-if |
未显示时不创建节点 |
| 高频展开与收起 | v-show |
切换只修改 CSS |
| 多分支互斥内容 | v-if / v-else-if / v-else |
一次只渲染一个分支 |
<template> 包裹多个节点 |
v-if |
v-show 不支持 <template> |
风险与边界
不要把 v-show 当作权限控制。触发条件是敏感内容已经随页面数据下发,只在界面上隐藏;后果是用户仍可能在 DOM、网络响应或组件状态中读取内容。安全替代方案是在服务端校验权限,并用 v-if 仅作为界面层补充,敏感数据未授权时不得返回。
对频繁切换的复杂组件使用 v-if,会反复执行挂载和卸载,可能丢失局部状态并增加开销。安全替代方案是改用 v-show,或将必须保留的状态提升到父组件、Pinia 等外部状态容器。
排障清单
分支同时出现或语法报错时,确认 v-else-if、v-else 与前一个条件节点紧邻,中间不要插入其他元素。条件变化但界面不更新时,检查条件是否来自响应式状态,并避免把 ref 对象本身用于脚本中的布尔判断,应读取其 .value。
速查:低频创建销毁用 v-if,高频显隐用 v-show;任何前端条件渲染都不能替代后端授权。
使用 v-for 渲染数组或对象,并设置稳定且唯一的 key。
循环渲染列表
使用 v-for 把数组或对象映射为 DOM 节点。列表会增删、排序或更新时,必须为每个节点提供稳定且唯一的 key,让 Vue 正确复用元素和组件状态。
基本语法
数组常用 (item, index) in items,对象常用 (value, key, index) in object。in 与 of 都可用于数组,但团队内应统一一种写法。
<li v-for="(user, index) in users" :key="user.id">
{{ index + 1 }}. {{ user.name }}
</li>
<dd v-for="(value, key) in profile" :key="key">
{{ key }}:{{ value }}
</dd>以上是片段示例,依赖组件中已定义的 users 数组和 profile 对象。
主示例
下面的单文件组件同时演示数组渲染、对象渲染和删除列表项。user.id 来自业务数据,不会因删除或排序而变化。
<script setup>
import { reactive, ref } from 'vue'
const users = ref([
{ id: 101, name: 'Ada', active: true },
{ id: 102, name: 'Linus', active: false },
{ id: 103, name: 'Grace', active: true }
])
const profile = reactive({
framework: 'Vue 3',
buildTool: 'Vite'
})
function removeUser(id) {
users.value = users.value.filter(user => user.id !== id)
}
</script>
<template>
<section>
<h2>用户列表</h2>
<p v-if="users.length === 0">暂无用户</p>
<ul v-else>
<li v-for="(user, index) in users" :key="user.id">
{{ index + 1 }}. {{ user.name }}
<span>{{ user.active ? '启用' : '停用' }}</span>
<button type="button" @click="removeUser(user.id)">删除</button>
</li>
</ul>
<h2>运行信息</h2>
<dl>
<template v-for="(value, key) in profile" :key="key">
<dt>{{ key }}</dt>
<dd>{{ value }}</dd>
</template>
</dl>
</section>
</template>预期结果:首次渲染显示 3 名用户及两项运行信息;点击 Ada 的“删除”后,列表立即变为 Linus、Grace,序号重新从 1 开始。
用户列表
1. Ada 启用
2. Linus 停用
3. Grace 启用
运行信息
framework Vue 3
buildTool Vitekey 选择
优先使用数据库主键、UUID 或业务唯一编码。key 只需在当前同级列表中唯一,支持字符串和数字;不要使用对象本身作为 key。
仅当列表永不插入、删除、排序,且每一项没有输入框、动画或子组件状态时,才可临时使用索引。动态列表使用 :key="index" 可能导致输入值、选中状态或组件内部状态错位。
高频用法
需要过滤或排序时,先用 computed 生成新数组,再对结果执行 v-for,不要把 v-if 与 v-for 放在同一元素上。需要为一项输出多个相邻节点时,用带 :key 的 <template v-for> 包裹。
列表为空时,把 v-if 放在列表容器或相邻节点上;超大列表不要一次渲染全部数据,应使用分页、虚拟列表或增量加载降低 DOM 数量。
排障清单
- 出现
Duplicate keys found:检查接口数据是否重复,并确认key不是空值。 - 删除后输入框内容串行:把索引
key改为稳定业务 ID。 - 数据已变化但页面未更新:确认修改的是响应式数据,如
ref、reactive或其内部属性。 - 对象字段顺序不符合业务要求:不要依赖对象遍历顺序,先转换为按目标顺序排列的数组。
速查原则:v-for 决定“渲染哪些项”,稳定 key 决定“每个节点是谁”。
绑定点击、输入和键盘事件,并使用常见事件修饰符。
处理用户事件
使用 v-on 或缩写 @ 监听点击、输入、提交和键盘事件。简单赋值可写内联表达式;包含校验、异步请求或多步状态更新时,应调用组件方法,并按需使用事件修饰符。
基本语法
@click="handler" 绑定方法,@click="count++" 执行简单表达式,@click="handler($event)" 显式传入原生事件对象。输入事件可读取 event.target.value,键盘事件可追加 .enter、.esc 等按键修饰符。
<button type="button" @click="save">保存</button>
<input @input="handleInput" @keyup.enter="save">
<form @submit.prevent="save">...</form>以上是片段示例,save 和 handleInput 需要在组件脚本中定义。
主示例
下面的单文件组件覆盖输入、点击、回车提交、阻止表单默认刷新,以及阻止子按钮点击继续冒泡到父容器。
<script setup>
import { ref } from 'vue'
const draft = ref('')
const message = ref('尚未提交')
const cardClicks = ref(0)
function handleInput(event) {
// 保留受控输入值,避免直接操作 DOM 作为状态源
draft.value = event.target.value
}
function submit() {
const value = draft.value.trim()
message.value = value ? `已提交:${value}` : '请输入内容'
}
function countCardClick() {
cardClicks.value += 1
}
function clearDraft() {
draft.value = ''
message.value = '内容已清空'
}
</script>
<template>
<form @submit.prevent="submit">
<label>
内容
<input
:value="draft"
@input="handleInput"
@keyup.enter.exact.prevent="submit"
>
</label>
<button type="submit">提交</button>
</form>
<div class="card" @click="countCardClick">
<p>卡片点击次数:{{ cardClicks }}</p>
<button type="button" @click.stop="clearDraft">清空但不触发卡片</button>
</div>
<p>{{ message }}</p>
</template>预期结果:输入 Vue 3 后按 Enter,页面显示“已提交:Vue 3”且不会刷新;点击卡片空白处次数加 1;点击“清空”只清空内容,不增加卡片点击次数。
已提交:Vue 3
卡片点击次数:0常用修饰符
| 修饰符 | 作用 | 常见位置 |
|---|---|---|
.prevent |
调用 preventDefault() |
表单提交、链接点击 |
.stop |
调用 stopPropagation() |
嵌套点击区域 |
.once |
监听器最多触发一次 | 首次确认、一次性引导 |
.self |
仅事件目标是当前元素时触发 | 遮罩层、容器点击 |
.enter、.esc |
仅指定按键触发 | 输入框快捷操作 |
.exact |
必须精确匹配系统修饰键状态 | 防止 Ctrl、Alt 等组合误触 |
修饰符顺序会影响生成的事件处理逻辑。例如 @click.prevent.self 可能先阻止默认行为,再检查是否点击自身;@click.self.prevent 则只在点击自身时阻止默认行为。
高频用法
表单优先使用 @submit.prevent,让回车和按钮点击走同一提交函数。普通文本输入通常优先用 v-model;只有需要访问原始事件、输入法状态或自定义转换时,才手动监听 @input。
需要传入业务参数时可写 @click="remove(item.id)";同时需要原生事件时写 @click="remove(item.id, $event)"。事件处理函数中不要依赖全局 event,它在不同浏览器和严格模式下不可靠。
风险与边界
不要同时使用 .passive 与 .prevent。.passive 表示处理器不会取消默认行为,二者并用会产生浏览器警告,且 preventDefault() 不生效;滚动性能场景使用 .passive,确需拦截默认行为时移除它。
连续触发的 input、scroll 或 mousemove 可能造成高频计算和请求。后果通常是卡顿或重复提交;安全做法是对昂贵逻辑使用防抖、节流或请求取消,而不是阻塞事件线程。
排障清单
- 点击没有反应:确认模板中的方法名与脚本定义一致,并查看控制台是否有未捕获异常。
- 表单提交后页面刷新:使用
@submit.prevent,不要只给按钮绑定@click。 - 父子区域同时触发:在子元素使用
.stop,或在父元素使用.self。 - 回车触发两次:避免同时在输入框和表单中执行相同提交逻辑;统一由
submit事件处理。 event.target.value类型报错:TypeScript 中将事件目标收窄为HTMLInputElement,或直接改用v-model。
速查原则:先确定事件源,再决定是否阻止默认行为、停止冒泡或限制按键,最后把复杂逻辑收口到单一处理函数。
使用 ref 声明基本值或可替换对象的响应式状态。
创建 ref 状态
ref 适合保存基本值,或保存需要整体替换的对象。它返回一个响应式引用:脚本中通过 .value 读写,模板中会自动解包,可直接使用变量名。
命令定位
优先在计数器、开关、输入值、加载状态和接口返回对象等场景使用 ref。当业务动作需要把整个对象替换成新对象时,ref 通常比 reactive 更直观。
基本语法
下面是可直接放入 Vue 3 项目 src/App.vue 的完整示例。
<script setup>
import { ref } from 'vue'
const count = ref(0)
const user = ref({ name: 'Ada', online: false })
function increment() {
// 脚本中读写 ref 必须访问 .value
count.value += 1
}
function replaceUser() {
// ref 允许整体替换对象,同时保持响应式更新
user.value = { name: 'Lin', online: true }
}
</script>
<template>
<main>
<p>计数:{{ count }}</p>
<button @click="increment">加一</button>
<p>用户:{{ user.name }} / {{ user.online ? '在线' : '离线' }}</p>
<button @click="replaceUser">替换用户</button>
</main>
</template>预期结果
初始页面:
计数:0
用户:Ada / 离线
点击“加一”后:
计数:1
点击“替换用户”后:
用户:Lin / 在线模板中的 count 和 user 会自动解包;脚本函数中的读写仍需使用 count.value、user.value。
高频用法
- 基本值:
ref(false)、ref('')、ref(0),适合开关、表单值和状态码。 - 可替换对象:接口响应到达后执行
data.value = responseData。 - 可空状态:TypeScript 中可写
ref<User | null>(null),读取前先判空。 - 大型不可变对象:只需监听整体替换时使用
shallowRef,避免深层代理成本。
风险与边界
在脚本中漏写 .value 时,可能修改的是引用对象本身的错误位置,页面不会按预期更新;安全做法是始终通过 .value 读写。把 const snapshot = count.value 保存为普通变量只会得到当时的快照,后续不会同步;需要持续派生值时使用 computed。
ref 包含普通对象时默认会深度响应。对象很大、由第三方实例构成或只按整体替换时,深度代理可能增加开销或干扰实例行为,可改用 shallowRef,并通过重新赋值触发更新。
排障清单
- 页面不更新:确认状态由
ref()创建,并在脚本中通过.value修改。 - 控制台出现未定义:确认已从
vue导入ref,且变量位于当前组件作用域。 - 解构后不再变化:不要把
.value解构成普通变量;直接保留 ref,或用computed派生。 - TypeScript 报空值:为
null初始值声明联合类型,并在访问属性前完成判空。
速查:基本值或需要整体替换的状态用 ref;脚本写 .value,模板通常不写。
使用 reactive 创建对象状态并避免解构导致响应性丢失。
创建 reactive 状态
reactive 适合把一组相关字段组织成响应式对象,并通过修改属性驱动视图更新。它返回对象的代理,读写属性时不需要 .value,但不能随意替换整个代理对象。
命令定位
表单、筛选条件、分页参数和带嵌套字段的页面状态通常适合 reactive。状态只有一个基本值,或后续需要整体替换对象时,优先使用 ref。
基本语法
下面示例可直接放入 Vue 3 项目 src/App.vue。toRefs 用于安全解构需要单独暴露的属性。
<script setup>
import { reactive, toRefs } from 'vue'
const state = reactive({
count: 0,
user: {
name: 'Ada',
online: false
}
})
// 直接解构 state.count 会失去响应性,toRefs 会保留连接
const { count } = toRefs(state)
function increment() {
state.count += 1
}
function updateUser() {
// 修改嵌套属性会触发模板更新
state.user.name = 'Lin'
state.user.online = true
}
</script>
<template>
<main>
<p>计数:{{ count }}</p>
<button @click="increment">加一</button>
<p>用户:{{ state.user.name }} / {{ state.user.online ? '在线' : '离线' }}</p>
<button @click="updateUser">更新用户</button>
</main>
</template>预期结果
初始页面:
计数:0
用户:Ada / 离线
点击“加一”后:
计数:1
点击“更新用户”后:
用户:Lin / 在线count 是由 toRefs 生成的 ref,模板会自动解包;state.user 仍通过代理对象直接访问。
高频用法
- 表单对象:集中保存
name、email、errors等字段,提交前统一读取。 - 查询条件:维护分页、排序、关键词和筛选项,并按属性局部更新。
- 嵌套状态:直接修改
state.user.name、state.items.push(item)。 - 安全解构:向模板或组合函数暴露多个字段时使用
toRefs(state)。
风险与边界
reactive 只能接收对象、数组、Map 或 Set 等对象类型,传入数字或字符串不会得到可用的对象状态。需要基本值时改用 ref。
重新执行 state = newState 会让模板和依赖仍指向旧代理,造成更新中断;通常把状态声明为 const,批量覆盖字段时使用 Object.assign(state, newState)。直接写 const { count } = state 会得到普通值快照,后续不再更新;应使用 toRefs 或 toRef。
排障清单
- 属性更新但页面不变:确认修改的是原始
reactive代理,而不是解构出的普通值。 - 整体赋值后失效:不要替换代理变量,改用
Object.assign或改成ref。 - 组合函数返回后失去响应性:返回
toRefs(state),不要返回普通解构结果。 - 与原对象做全等比较失败:代理与原对象不是同一引用;业务判断应比较稳定标识,不依赖对象身份。
速查:成组对象状态用 reactive;按属性修改,不整体替换;需要解构时配合 toRefs。
使用 computed 缓存由其他响应式状态派生出的结果。
定义计算属性
当页面值完全由一个或多个响应式状态推导而来,并且会被模板或其他逻辑重复读取时,使用 computed。它会跟踪依赖并缓存结果,只有依赖变化后才重新计算,适合金额、筛选结果、状态文案等派生数据。
基本语法
只读计算属性传入 getter,返回 ComputedRef。在 <script setup> 中读取或赋给普通 JavaScript 逻辑时使用 .value,模板会自动解包,因此直接写计算属性名称。
<script setup lang="ts">
import { computed, ref } from "vue"
const price = ref(100)
const discount = ref(0.8)
// 仅依赖 price 和 discount;任一值变化后,下一次读取时重新计算
const finalPrice = computed(() => price.value * discount.value)
function useMemberDiscount() {
discount.value = 0.9
}
</script>
<template>
<p>原价:¥{{ price.toFixed(2) }}</p>
<p>折扣:{{ discount * 10 }} 折</p>
<p>应付:¥{{ finalPrice.toFixed(2) }}</p>
<button @click="useMemberDiscount">改为 9 折</button>
</template>预期结果:页面初始显示应付 ¥80.00;点击按钮后显示 ¥90.00。price 未变化,但 discount 变化使 finalPrice 的缓存失效并重新计算。
原价:¥100.00
折扣:8 折
应付:¥80.00
点击“改为 9 折”后:
折扣:9 折
应付:¥90.00常用写法
只读派生值优先使用 computed(() => expression)。只有确实需要通过“写入派生值”反向更新源状态时,才使用带 get 和 set 的可写计算属性;普通表单字段通常直接绑定 ref 更清楚。
import { computed, ref } from "vue"
const firstName = ref("Ada")
const lastName = ref("Lovelace")
// 片段示例:依赖已有的 firstName 和 lastName
const fullName = computed({
get: () => `${firstName.value} ${lastName.value}`,
set: (value: string) => {
const [first = "", ...rest] = value.trim().split(/\s+/)
firstName.value = first
lastName.value = rest.join(" ")
},
})
fullName.value = "Grace Hopper"
console.log(firstName.value, lastName.value)预期输出:
Grace Hopper风险与边界
不要在 getter 中发请求、修改依赖、写日志计数或启动定时器。触发条件是任何代码读取该计算属性;可能后果是重复副作用、循环更新或难以预测的执行次数。安全替代方案是用 watch 执行副作用,用普通函数处理每次都必须运行的逻辑。
computed 只缓存响应式依赖。Date.now()、普通全局变量或未包装的数据变化不会主动使缓存失效;需要实时值时使用方法、定时更新的 ref,或显式把变化来源纳入依赖。
排障清单
- 值不更新:确认 getter 内实际读取了
ref.value或reactive属性,而不是读取一次后保存的普通值。 - TypeScript 报错:脚本中把计算属性当普通值使用时补上
.value;模板中不要额外写.value。 - 出现递归更新:检查 getter 或可写计算属性的
set是否又修改了自身依赖。 - 只读取一次:确认没有在响应式上下文外提前解构成普通变量;对象属性需要保留响应式引用。
速查:纯派生数据用 computed,副作用用 watch,需要每次调用都重新执行则使用普通函数。
使用 watch 精确监听单个或多个数据源并执行副作用。
监听状态变化
当某个响应式数据变化后需要执行请求、持久化、日志、定时处理或同步第三方组件时,使用 watch。它显式声明监听源,并把新值、旧值和清理函数交给回调;仅用于派生展示值时应改用 computed。
基本语法
监听 ref 时直接传引用;监听 reactive 对象的单个属性时传 getter;监听多个数据源时传数组。回调默认在依赖变化后异步执行,并会合并同一轮更新中的重复触发。
watch(source, (newValue, oldValue, onCleanup) => {
// 执行副作用,并在下一次回调前清理旧任务
})这是签名示意,不是独立运行程序。source 可以是 ref、getter、响应式对象或这些来源组成的数组。
高频用法
以下组件对输入进行 300 毫秒防抖。每次关键词变化都会取消旧定时器,避免快速输入时重复执行过期搜索;将内容保存为已有 Vue 3 项目的 src/App.vue 即可验证。
<script setup lang="ts">
import { ref, watch } from "vue"
const keyword = ref("")
const lastSearch = ref("尚未搜索")
watch(keyword, (newKeyword, _oldKeyword, onCleanup) => {
const normalized = newKeyword.trim()
const timer = window.setTimeout(() => {
lastSearch.value = normalized ? `搜索:${normalized}` : "尚未搜索"
}, 300)
// 下一次变更前取消旧任务,避免旧结果覆盖新输入
onCleanup(() => window.clearTimeout(timer))
})
</script>
<template>
<label>
关键词:
<input v-model="keyword" placeholder="输入 vue" />
</label>
<p>{{ lastSearch }}</p>
</template>预期结果:快速输入 v、vu、vue 后等待 300 毫秒,页面只显示最后一次结果;实际输入间隔由用户操作决定。
搜索:vue监听对象属性时不要传当前属性值,应传 getter;多个来源则用数组,并按相同顺序解构新旧值。
watch(() => user.id, (newId, oldId) => {
console.log(`${oldId} -> ${newId}`)
})
watch([page, pageSize], ([newPage, newSize], [oldPage, oldSize]) => {
console.log({ newPage, newSize, oldPage, oldSize })
})预期行为:只有 user.id 变化时第一个回调才执行;page 或 pageSize 任一变化时第二个回调执行。示例依赖外部已定义的响应式变量,因此属于片段示例。
常用选项
immediate: true:创建监听器后立即执行一次,适合首屏也要加载数据的场景;首次调用的旧值为undefined。deep: true:递归监听嵌套修改。大型对象会增加遍历成本,优先监听具体字段或稳定 getter。flush: "post":回调延后到组件 DOM 更新完成后,适合读取更新后的元素尺寸;默认时机不保证拿到本组件最新 DOM。- 返回的停止函数可手动调用。同步创建于
setup的监听器会随组件卸载自动停止,异步创建的监听器应自行清理。
风险与边界
监听回调中的异步请求可能乱序返回:触发条件是用户连续修改条件且旧请求更晚完成;后果是旧响应覆盖新状态。安全替代方案是在清理函数中取消旧请求,或为每次请求记录序号并只接收最新结果。
deep 监听嵌套对象时,新值和旧值可能仍指向同一个对象;不要依赖引用差异定位具体字段。需要精确变更时监听 getter 数组,或在回调前后保存不可变快照。
排障清单
- 回调不执行:检查是否错误写成
watch(state.count, ...);应改为watch(() => state.count, ...)。 - 首次不执行:这是默认行为,需要首轮执行时添加
{ immediate: true }。 - 读取到旧 DOM:把选项改为
{ flush: "post" },或在回调内等待nextTick()。 - 回调触发过多:缩小监听源,避免对大对象使用
deep,并为高频输入增加防抖或节流。 - 组件卸载后仍运行:检查监听器是否在异步回调中创建,并保存、调用其停止函数。
速查:需要响应变化后“做事情”时用 watch;只需要得到一个派生值时用 computed。