前端工程化 / 系统课时

建立诊断基线

建立诊断基线

排查 Vite 问题前,先把“当时究竟运行了什么”固定下来。一个合格的诊断基线应同时包含环境版本、精确命令、完整日志、网络请求和最小复现步骤,避免只凭截图或口头描述猜测根因。

学习目标

  • 能一次性记录操作系统、Node.js、包管理器、Vite 与代码版本。
  • 能保存启动调试日志和关键网络请求,避免证据在重启后丢失。
  • 能把复杂项目压缩成他人可以重复执行的最小复现。

先冻结环境与命令

诊断记录必须能回答三个问题:在哪个目录执行、使用了哪些版本、执行了哪条完整命令。下面的脚本会把这些信息写入 diagnostics/environment.txt,并保留无法读取 Git 提交时的降级结果。

bash
mkdir -p diagnostics
{
  echo "time=$(node -p 'new Date().toISOString()')"
  echo "cwd=$(pwd)"
  echo "os=$(uname -a)"
  echo "node=$(node --version)"
  echo "npm=$(npm --version)"
  echo "vite=$(npm exec -- vite --version)"
  echo "git=$(git rev-parse --short HEAD 2>/dev/null || echo N/A)"
  echo "command=npm run dev -- --debug"
} > diagnostics/environment.txt
cat diagnostics/environment.txt

预期输出

text
time=<TIME>
cwd=<PATH>
os=<OS_INFO>
node=v<NODE_VERSION>
npm=<NPM_VERSION>
vite=vite/<VITE_VERSION> <PLATFORM>-<ARCH> node-v<NODE_VERSION>
git=<ID>
command=npm run dev -- --debug

不同 Vite 版本的版本行格式可能略有差异,但文件中至少应包含时间、目录、Node.js、npm、Vite、提交号和完整命令。不要只记录“执行了 npm run dev”,因为附加的 --host、--mode、--debug 或 root 参数都可能改变结果。

保存完整启动日志

复现问题时使用调试模式,并同时把标准输出与错误输出写入文件。启动后完成一次复现,再按 Ctrl+C 停止进程;这样既保留终端观察体验,也能留下可搜索的原始日志。

bash
npm run dev -- --debug 2>&1 | tee diagnostics/vite-debug.log

预期输出

text
VITE v<VITE_VERSION>  ready in <TIME> ms
➜  Local:   http://localhost:<PORT>/
<DEBUG_LOG_LINES>

日志内容会随版本、插件和项目配置变化,不应删减“看起来无关”的前后文。停止进程后,可执行 test -s diagnostics/vite-debug.log && echo 'log captured';看到 log captured 才表示文件确实写入了内容。

记录网络请求

页面异常不等于构建异常。应在浏览器开发者工具的 Network 面板中启用保留日志,重新加载页面,并记录失败请求的 URL、状态码、响应头、响应体、发起者和耗时。涉及重定向、代理或跨域时,最好导出 HAR 文件。

还可以用 curl 独立验证开发服务器是否能返回 HTML。将 <PORT> 替换成终端实际端口后执行:

bash
curl -i http://127.0.0.1:<PORT>/

预期输出

text
HTTP/1.1 200 OK
Content-Type: text/html
<OTHER_HEADERS>

<!doctype html>
<html

若浏览器失败而 curl 成功,应重点检查浏览器缓存、扩展、Service Worker 或前端运行时错误;若两者都失败,则优先查看服务器日志、代理和监听地址。

写出最小复现步骤

最小复现不是删除几段代码,而是保留触发问题所需的最少条件。先复制项目到临时目录,再逐步移除无关页面、插件和依赖;每删除一项都重新验证,直到再删一项问题就消失。

bash
cat > diagnostics/repro.md <<'EOF'
# 最小复现

1. 安装依赖:npm ci
2. 启动命令:npm run dev -- --debug
3. 访问地址:http://127.0.0.1:<PORT>/<PATH>
4. 操作步骤:<STEP_1>;<STEP_2>
5. 实际结果:<ACTUAL_RESULT>
6. 预期结果:<EXPECTED_RESULT>
7. 首次出现版本:<VERSION_OR_COMMIT>
EOF
cat diagnostics/repro.md

预期输出

text
# 最小复现

1. 安装依赖:npm ci
2. 启动命令:npm run dev -- --debug
3. 访问地址:http://127.0.0.1:<PORT>/<PATH>
4. 操作步骤:<STEP_1>;<STEP_2>
5. 实际结果:<ACTUAL_RESULT>
6. 预期结果:<EXPECTED_RESULT>
7. 首次出现版本:<VERSION_OR_COMMIT>

提交复现前,应从空目录重新执行一次文档中的步骤。若必须依赖本机全局包、未提交文件或私有环境变量,说明复现还不完整;敏感变量只保留键名和是否存在,不要写入真实值。

证据包验收

一个可交接的诊断目录至少应包含 environment.txt、vite-debug.log、网络截图或 HAR、repro.md,以及必要时的精简项目。文件名应稳定,日志保持原始顺序,所有动态值注明采集时间。

交给他人前再检查:问题能否重复出现;命令能否直接复制;端口、路径和分支是否明确;预期结果与实际结果是否分开;令牌、Cookie、内网域名和个人路径是否已经脱敏。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立诊断基线

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

登录哪都通