Vue / 系统课时
项目复盘与排障清单
项目复盘与排障清单
本节把综合项目从“能运行”提升到“可长期维护”:用类型、性能、安全和可维护性四条审查线找出系统性风险,再把常见故障按证据顺序定位,最终沉淀成仓库里的固定检查项和排障入口。
学习目标
- 用统一工程门禁快速确认类型、规范、测试和构建状态。
- 从类型、性能、安全与可维护性四个维度识别高风险问题。
- 按“现象—证据—根因—修复—回归”的顺序处理常见线上故障。
先跑一遍工程门禁
复盘先看可重复的机器证据,再看主观代码印象。项目至少应暴露 typecheck、lint、test:unit 和 build 四个脚本;如果仓库使用其他工具,也应映射到稳定脚本名,确保本地与 CI 的入口一致。
set -e
npm run typecheck >/dev/null
printf '%s\n' 'typecheck: ok'
npm run lint >/dev/null
printf '%s\n' 'lint: ok'
npm run test:unit >/dev/null
printf '%s\n' 'unit test: ok'
npm run build >/dev/null
printf '%s\n' 'build: ok'预期输出:
typecheck: ok
lint: ok
unit test: ok
build: ok任一步失败都应先解决再继续复盘。类型检查失败说明契约已经不一致;Lint 失败通常暴露危险写法或团队约束破坏;测试失败意味着行为存在回归;生产构建失败则说明当前提交无法交付。
用四条审查线复盘
四条审查线不是平均用力,而是优先找“能扩大事故半径”的问题。可以按下表快速定位证据来源。
| 审查线 | 重点证据 | 高风险信号 |
|---|---|---|
| 类型 | vue-tsc、Props/Emits、接口响应类型 |
大量 any、连续类型断言、前后端字段靠猜 |
| 性能 | Network、Performance、构建产物 | 首屏大包、重复请求、路由未懒加载、长列表无分页 |
| 安全 | 登录流程、权限守卫、模板输出 | 仅前端鉴权、敏感信息进仓库、无约束 v-html |
| 可维护性 | 目录边界、Composable、Store、组件职责 | 巨型组件、跨层直接改状态、重复请求逻辑、隐式副作用 |
类型层面优先消除“编译器被绕过”的位置。少量边界断言可以接受,但如果 API 数据进入系统后仍长期保持 any,错误会一路扩散到组件、Store 和表单。对接口响应应在边界完成类型收窄,并让组件只依赖已经确认的领域类型。
性能层面先找大头:路由级代码分割、重复 API、无必要的全量响应式对象、长列表渲染和超大依赖。不要在没有证据时先做微优化;应先用浏览器 Network 与 Performance 面板确认“加载慢、交互慢还是请求慢”。
安全层面要明确前端权限只能改善体验,真正授权必须由服务端完成。前端还应避免把密钥写进 VITE_* 环境变量,因为此类变量会被打包进客户端;对 v-html 输入必须确认内容来源可信并经过可靠净化。
可维护性层面关注变化成本。页面组件应主要负责编排,复用状态和副作用收敛到 Composable 或 Store,API 访问统一进入请求层。一个改动如果需要同时修改多个无关组件,通常说明边界已经泄漏。
按证据顺序排障
常见故障不要从“可能是某某框架 Bug”开始猜。先复现,再收集浏览器控制台、Network、路由状态、接口响应和构建信息,最后才进入源码。下面的流程图把入口信号和后续证据链放在同一张图里。

可以把最常见的现象压缩成下面几条处理路径:
| 现象 | 第一证据 | 常见根因 |
|---|---|---|
| 部署后白屏 | Console + Network | base 配置错误、旧 HTML 引用新旧混合资源、静态资源 404 |
| 刷新深层路由 404 | 服务器访问结果 | 未配置 SPA fallback 到 index.html |
| 登录后反复跳转 | 401 响应 + 路由守卫 | Token/Cookie 失效、守卫条件互相重定向、用户信息未恢复 |
| 菜单与权限不一致 | Route Meta + Store | 动态路由重复注入、退出后未清理、前端角色映射错误 |
| 开发正常而生产失败 | 构建日志 + 环境变量 | 大小写路径、编译期变量缺失、生产分支代码未被开发环境覆盖 |
处理时保持固定顺序:先稳定复现;再记录可见错误和失败请求;随后确认路由、状态与环境配置;接着用源码映射定位到具体代码;最后只做能解释证据的最小修复,并补自动化回归测试。这样能避免一次改动同时引入多个变量,让故障从“猜”变成可验证的因果链。
把清单沉淀进仓库
复盘的价值不在会议记录,而在下一次提交能自动阻止同类问题。建议把工程门禁放进 CI,把高频排障项写入 docs/troubleshooting.md,并在 Pull Request 模板中加入类型、性能、安全和回归验证勾选项。
最终交付应满足三个条件:新成员能用一组固定脚本判断项目是否可构建;线上出现白屏、路由 404、登录循环或权限异常时能按证据链定位;复盘发现的高风险问题已经转化为测试、静态检查、文档或 CI 门禁,而不是只存在于个人经验里。