Vue / 系统课时

项目复盘与排障清单

项目复盘与排障清单

本节把综合项目从“能运行”提升到“可长期维护”:用类型、性能、安全和可维护性四条审查线找出系统性风险,再把常见故障按证据顺序定位,最终沉淀成仓库里的固定检查项和排障入口。

学习目标

  • 用统一工程门禁快速确认类型、规范、测试和构建状态。
  • 从类型、性能、安全与可维护性四个维度识别高风险问题。
  • 按“现象—证据—根因—修复—回归”的顺序处理常见线上故障。

先跑一遍工程门禁

复盘先看可重复的机器证据,再看主观代码印象。项目至少应暴露 typecheck、lint、test:unit 和 build 四个脚本;如果仓库使用其他工具,也应映射到稳定脚本名,确保本地与 CI 的入口一致。

bash
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'

预期输出:

text
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、路由状态、接口响应和构建信息,最后才进入源码。下面的流程图把入口信号和后续证据链放在同一张图里。

Vue 管理后台从现象到根因的排障路径

可以把最常见的现象压缩成下面几条处理路径:

现象 第一证据 常见根因
部署后白屏 Console + Network base 配置错误、旧 HTML 引用新旧混合资源、静态资源 404
刷新深层路由 404 服务器访问结果 未配置 SPA fallback 到 index.html
登录后反复跳转 401 响应 + 路由守卫 Token/Cookie 失效、守卫条件互相重定向、用户信息未恢复
菜单与权限不一致 Route Meta + Store 动态路由重复注入、退出后未清理、前端角色映射错误
开发正常而生产失败 构建日志 + 环境变量 大小写路径、编译期变量缺失、生产分支代码未被开发环境覆盖

处理时保持固定顺序:先稳定复现;再记录可见错误和失败请求;随后确认路由、状态与环境配置;接着用源码映射定位到具体代码;最后只做能解释证据的最小修复,并补自动化回归测试。这样能避免一次改动同时引入多个变量,让故障从“猜”变成可验证的因果链。

把清单沉淀进仓库

复盘的价值不在会议记录,而在下一次提交能自动阻止同类问题。建议把工程门禁放进 CI,把高频排障项写入 docs/troubleshooting.md,并在 Pull Request 模板中加入类型、性能、安全和回归验证勾选项。

最终交付应满足三个条件:新成员能用一组固定脚本判断项目是否可构建;线上出现白屏、路由 404、登录循环或权限异常时能按证据链定位;复盘发现的高风险问题已经转化为测试、静态检查、文档或 CI 门禁,而不是只存在于个人经验里。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目复盘与排障清单

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通