w wyl123ly 的博客
MD

前端-09-前端工程化与调试

61 KB 2026.10.11 原文件

前端-09-前端工程化与调试

这篇讲什么

一个项目从「能跑」到「敢让十个人一起改、敢在凌晨发版」,中间要补的不是框架知识,而是工程化与调试能力:

代码规范与自动格式化、提交信息规范、类型检查门禁、性能指标与优化、DevTools 高效用法、线上错误监控。

读完你应该能为一支小团队配出一套完整的质量门禁,并在浏览器里用 10 分钟定位一个模糊的「页面卡」问题。

一、工程化到底解决什么问题

先看一个具体场景,它几乎是每个前端团队都会经历的。

小张一个人写一个后台管理系统,代码全在 main.js 里,改完直接 FTP 上传到服务器。某天业务扩张,团队来了四个人:

时间出现的问题根本原因
第 1 周Git diff 里全是空格与缩进改动,真正的逻辑改动只有两行编辑器缩进配置不统一,没有格式化工具
第 2 周张三的机器上能跑,李四的机器上 Cannot find module依赖只写在 package.json 的 dependencies 里但没锁版本,且有人手动 npm install xxx 后忘了提交
第 3 周上线后发现用的是三个月前的 dist 目录构建与部署靠手工拖文件,没有 CI
第 4 周用户反馈「白屏」,没人知道是谁改坏的、错在哪一行上报的是压缩混淆后的堆栈,没有 Source Map,也没有监控
第 5 周git log 里全是「修改」「更新」「fix」提交信息没有约定,无法自动生成 CHANGELOG

这五条问题对应工程化的五个支柱,这篇笔记就按这个顺序讲:

  1. 一致性:代码风格与格式由工具决定,不由人决定(ESLint + Prettier + EditorConfig)。
  2. 可复现:依赖可复现、构建可复现(锁文件 + CI,见 工具-03-包管理器)。
  3. 可追溯:提交信息规范化,能自动生成版本号与变更日志。
  4. 有门禁:类型检查、Lint、测试在合并前自动跑,坏代码进不了主干。
  5. 可观测:线上性能与错误能被量化、能被告警,而不是等用户投诉。

一句话定义

前端工程化 = 把人的约定变成机器的检查。凡是「靠自觉」的规则,最终都会失效;凡是「CI 会打回」的规则,才会真正被执行。

二、代码规范:ESLint、Prettier 与提交时格式化

2.1 ESLint 解决什么问题

ESLint 是可插拔的 JavaScript/TypeScript 静态检查器。它把源码解析成 AST(抽象语法树),然后让一组规则去「匹配」这棵树,命中就产出一条诊断(error / warn / off 三档)。

关键区分:ESLint 管的是可能出错的写法(正确性、潜在 bug、最佳实践),而不是「好不好看」。常见规则举例:

规则作用为什么值得开
no-unused-vars禁止声明未使用的变量未使用变量往往是重构残留,也会掩盖真正的拼写错误
no-undef禁止使用未声明的变量手滑写成 usrName 时立刻报错,而不是运行时才 ReferenceError
eqeqeq要求用 === 而非 ==规避 == 的隐式类型转换,见 [[JavaScript-01-基础语法与类型]]
no-floating-promises(TS 版)禁止未处理的 Promise漏写 await 是异步代码最常见的 bug,见 [[JavaScript-04-异步编程]]
react-hooks/exhaustive-deps检查 Hook 依赖数组完整性依赖漏写会导致闭包捕获旧值,见 [[前端-07-React]]
vue/multi-word-component-names组件名必须多单词避免与原生标签(如 <Header>)冲突,见 [[前端-06-Vue]]
no-console生产代码禁止 console.log用规则强制,比靠 Code Review 提醒可靠

最小可用配置(扁平配置,ESLint v9 起的默认格式,以官方最新文档为准):

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      // 报错级别:error 会让 CI 失败,warn 只提示
      "no-unused-vars": "error",
      eqeqeq: ["error", "always"],
      "no-console": ["warn", { allow: ["warn", "error"] }],
    },
  },
  {
    // 只检查业务源码,别把构建产物也扫一遍
    ignores: ["dist/**", "node_modules/**", "coverage/**"],
  },
];

命令行执行:

npx eslint .                                  # 检查
npx eslint . --fix                            # 自动修复能修的规则
npx eslint . --format json --output-file eslint-report.json  # 供 CI 注释到 PR 上

2.2 为什么还需要 Prettier,二者如何分工

如果把「缩进用几个空格」「行宽多少」「尾随逗号」这类规则也交给 ESLint,会遇到两个麻烦:

  1. 规则数量爆炸:纯格式规则有上百条,配置与维护成本极高。
  2. 与编辑器格式化冲突:ESLint 的格式化能力远弱于专门的格式化器,且无法保证「幂等」(格式化两次结果不同)。

Prettier 是有明确立场的格式化器(opinionated formatter):它几乎不提供风格选项,直接把代码解析成 AST 再按固定风格打印。因为它丢弃了原格式,所以结果是唯一且幂等的——同一个文件无论谁格式化,字节级一致。这正是团队协作最想要的性质。

分工口诀

ESLint 管「写错了」,Prettier 管「写丑了」。

正确性、潜在 bug、框架最佳实践 → ESLint;缩进、换行、引号、行宽 → Prettier。

二者职责不重叠,因此不应该互相配置对方的规则。

// .prettierrc.json —— 有意保持极简
{
  "semi": true,
  "singleQuote": false,
  "printWidth": 100,
  "trailingComma": "all"
}
npx prettier . --write          # 就地格式化
npx prettier . --check          # 只检查,CI 用这个(不通过就退出码非 0)

2.3 eslint-config-prettier 处理冲突

历史上 ESLint 内置了大量格式规则(indent、quotes、semi…)。如果它们与 Prettier 的结论不一致,就会出现「ESLint 说这里要这样,Prettier 保存后又改回去」的死循环。

eslint-config-prettier 的作用就是关掉所有与 Prettier 冲突的 ESLint 规则(它不启用任何规则,只做关闭)。在扁平配置里作为最后一项引入,确保它的「关闭」覆盖前面的「开启」:

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettier from "eslint-config-prettier";

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: { eqeqeq: "error" },
  },
  // 必须放最后:只关闭冲突规则,顺序错了就不生效
  prettier,
];

三个高频误解

- eslint-plugin-prettier 不是必需的。它把 Prettier 当作一条 ESLint 规则来跑,会让 Lint 变慢、报错信息变差。官方推荐的做法是「分开跑、各管各的」。

- Prettier 不做类型检查,也不理解业务语义;它格式化语法合法的代码,语法错误时直接报错退出。

- eslint-config-prettier 必须放数组最后一项,因为它靠「后覆盖前」来关闭冲突规则。

2.4 提交时自动格式化:pre-commit 钩子与 lint-staged

只在 CI 里检查有一个体验问题:开发者提交完才发现格式不对,再改一次、再推一次,来回浪费十几分钟。

更好的做法是在本地提交那一刻就自动修好。这需要两个工具配合:

  • Husky:管理 Git 钩子,把钩子脚本纳入版本控制(.husky/ 目录跟着仓库走,队友克隆后自动生效)。
  • lint-staged:只对本次暂存(staged)的文件跑命令。全量跑 ESLint 在几千文件的项目里要几十秒,只跑改动的几个文件通常不到 1 秒。
# 一次性安装(约 5 分钟配完,之后团队一直受益)
npm install -D husky lint-staged
npx husky init
// package.json
{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier . --write",
    "typecheck": "tsc --noEmit"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css,scss,html}": ["prettier --write"]
  }
}
# .husky/pre-commit —— 由 husky init 生成,内容换成下面这行
npx lint-staged
# .husky/commit-msg —— 校验提交信息格式
npx --no -- commitlint --edit "$1"

钩子失败时不要养成 --no-verify 的习惯

git commit --no-verify 会跳过所有钩子。它应该是应急手段(例如线上热修复),而不是日常操作——一旦成为习惯,门禁形同虚设。CI 上仍需重复跑一遍这些检查,因为本地钩子可被绕过。

2.5 EditorConfig:跨编辑器的最后一块拼图

Prettier 只管它能识别的文件类型;.editorconfig 管编辑器层面的通用设置(缩进风格、行尾、文件末尾空行、字符集),几乎所有主流编辑器都原生或通过插件支持它。

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.md]
# Markdown 里行尾双空格是「硬换行」语法,不能被裁掉
trim_trailing_whitespace = false

三层配置的关系,记住这张表就够了:

工具管什么何时生效能否自动修
EditorConfig编辑器行为(缩进、行尾、编码)你按下 Tab 的那一刻是
Prettier代码的最终排版保存 / 提交 / CI是
ESLint代码正确性与最佳实践保存 / 提交 / CI部分

三、提交规范:Conventional Commits

3.1 为什么提交信息要规范化

git log 是团队唯一一份不需要额外维护的开发历史。但它的价值取决于信息质量:

  • 出线上事故时,git log --oneline v1.2.0..v1.3.0 是快速锁定嫌疑改动的第一手段。
  • 版本号与 CHANGELOG 可以从提交信息自动推导,不需要人肉维护。
  • CI 可以按类型分流:feat 跑完整测试 + 部署预发,docs 只跑文档构建。
  • git log 里如果全是「修改」「更新」,上面三件事一件都做不了。

3.2 格式

<type>(<scope>): <subject>

<body>

<footer>
字段必填说明示例
type是改动类别,决定版本号如何递增feat、fix
scope否影响范围(模块、页面、包名)(user-api)、(checkout)
subject是一句话说明做了什么,用祈使句、不加句号add sms login
body否为什么这样改、有什么取舍;每行不超过 72 字符见下方示例
footer否破坏性变更、关联 IssueBREAKING CHANGE:、Closes #128

常用 type 取值:

type含义对应语义化版本变化
feat新功能MINOR(1.2.0 → 1.3.0)
fix修 bugPATCH(1.2.0 → 1.2.1)
perf性能优化PATCH
refactor重构(不改外部行为)不变
docs只改文档不变
test增删改测试不变
build构建系统或依赖变更不变(也可能 PATCH)
ciCI 配置变更不变
chore杂项(脚手架、配置)不变
revert回滚某次提交PATCH
style纯格式改动(空格、分号)不变

真实示例:

feat(auth): 支持手机号 + 验证码登录

原登录页只有密码方式,海外用户反馈接收短信失败率高,
因此同时保留密码登录入口,通过 tab 切换。

删除旧的 /login/password 表单提交逻辑,
统一改走 /api/v2/auth。

BREAKING CHANGE: 移除 POST /api/v1/login,请改用 /api/v2/auth。
Closes #128

3.3 commitlint:让规范成为门禁

规范写在文档里没人看,写成钩子才会被执行:

npm install -D @commitlint/cli @commitlint/config-conventional
// commitlint.config.js
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    // 放开默认的 100 字符限制
    "header-max-length": [2, "always", 120],
    // scope 限定为业务模块,避免写成 "fix(stuff)"
    "scope-enum": [
      2,
      "always",
      ["auth", "user-api", "checkout", "ui", "deps", "ci", "docs"],
    ],
  },
};
# 手动校验一条提交信息(不需要真的提交)
echo "feat(auth): 支持手机号登录" | npx commitlint

# 交互式生成合规提交信息(不想记格式时很省事)
npx commitizen init cz-conventional-changelog --save-dev --save-exact

3.4 语义化版本与自动 CHANGELOG

语义化版本(Semantic Versioning, SemVer) 把版本号定义为 MAJOR.MINOR.PATCH:

  • MAJOR:不兼容的 API 变更(对应 BREAKING CHANGE)。
  • MINOR:向后兼容地新增功能(对应 feat)。
  • PATCH:向后兼容地修 bug(对应 fix)。

由于 Conventional Commits 的 type 与 SemVer 的递增规则一一对应,工具就能全自动完成「读提交 → 定版本 → 改 package.json → 写 CHANGELOG → 打 tag → 发 Release」整条链路。主流工具是 release-please、semantic-release 与 changesets,选一个即可,不要同时上两个。

自动 CHANGELOG 的本质

它不是「AI 写文档」,而是一次纯机械的分组:把 fix 列进「Bug Fixes」、feat 列进「Features」、带 BREAKING CHANGE 的提到最前面。

因此它对格式极其敏感——只要有人写 update,那一条就会从 CHANGELOG 里消失。

package.json 中的 version 字段与 Git tag 必须一致,否则 npm 发布会出现「tag 与版本对不上」的错误。分支策略与 PR 流程见 工具-05-GitHub与GitLab协作,CI 侧如何把这些检查串成流水线见 工具-08-CICD入门。

四、类型检查与质量门禁

4.1 为什么 tsc --noEmit 是 CI 的第一道门

构建工具(Vite、esbuild、SWC)为了速度,只做类型擦除,不做类型检查——它们把 : string 直接删掉,从不验证你传进去的是不是真的 string。这意味着:即使代码有类型错误,vite build 依然会成功产出 dist,错误留到运行时爆发。见 前端-08-构建工具-Vite与Webpack。

所以 CI 必须单独跑一次类型检查:

npx tsc --noEmit                 # 只做类型检查,不输出文件,也不会污染 dist
npx tsc --noEmit --extendedDiagnostics  # 看每个文件耗时,排查 CI 为什么慢
npx tsc --noEmit --incremental   # 用 .tsbuildinfo 缓存,大项目能快数倍
// tsconfig.json —— 与门禁相关的关键项
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,

    "skipLibCheck": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

4.2 strict 究竟打开了什么

选项效果不开会怎样
strictNullChecksnull / undefined 不再隐式属于所有类型user.name 在 user 可能为 null 时也不报错,运行时报 Cannot read properties of null
noImplicitAny推断不出类型时报错,而不是默认 any拼错属性名不报错,类型系统形同虚设
strictFunctionTypes函数参数按逆变检查回调签名不兼容时静默通过
strictBindCallApply检查 bind / call / apply 的参数参数个数与类型错误无法被发现
strictPropertyInitialization类属性必须在构造函数中初始化实例属性为 undefined,访问时才崩
noImplicitThisthis 推断为 any 时报错回调里的 this 指向不明

老项目如何平滑迁移到 strict

不要一次性打开然后面对几千个报错。先开 strict: true,用 exclude 把待整改目录(如 src/legacy/**)排除在外,再按目录逐个搬回来。

更精细的做法是用 // @ts-expect-error 逐行标注并附上 Issue 号,让「待还的技术债」在代码里可见。

4.3 vue-tsc:SFC 模板里的类型谁来查

普通 tsc 不认识 .vue 单文件组件——它看到的是「一个文件里有 <template>、<script>、<style> 三段」,不符合 TypeScript 的语法。vue-tsc 是 tsc 的包装器,先用 Vue 编译器把 SFC 展开成等价 TS,再调用 tsc 做检查。它能发现例如「给 <UserCard> 传了不存在的 prop」这类模板层错误——这类错误 tsc 完全看不见。

// package.json
{
  "scripts": {
    "typecheck": "vue-tsc --noEmit --project tsconfig.app.json",
    "typecheck:watch": "vue-tsc --noEmit --watch"
  }
}

4.4 把门禁串起来

一个够用的 GitHub Actions 工作流(ci 触发条件、矩阵、缓存等细节见 工具-08-CICD入门):

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      # npm ci 严格按 package-lock.json 安装,比 npm install 更适合 CI
      - run: npm ci
      # 顺序有意从快到慢:便宜的检查先失败,省 CI 时间
      - run: npx prettier . --check
      - run: npx eslint .
      - run: npm run typecheck
      - run: npm run test -- --run
      - run: npm run build

门禁的顺序原则

按「耗时从短到长」排列。格式检查通常 2 秒,Lint 10 秒,类型检查 30 秒,测试可能 3 分钟。

便宜的检查放前面,失败的 PR 在 10 秒内就得到反馈,不用白等三分钟。

三个门禁都必须设为 PR 的 required status check,否则「红色的叉」可以被无视。

五、性能优化实战

5.1 指标:LCP / INP / CLS

这三个指标是 Core Web Vitals(核心网页指标),也是搜索引擎排名的输入之一。它们的共同点是:都以真实用户的体验为准,而不是实验室数据。

指标全称衡量什么好需要改进差
LCPLargest Contentful Paint视口内最大元素的渲染时间(「主要内容多久看到」) s s s
INPInteraction to Next Paint用户交互到下一帧绘制的延迟(「点了多久有反应」) ms ms ms
CLSCumulative Layout Shift意外布局偏移的累计分数(「内容会不会乱跳」)

评估标准取 第 75 百分位(p75):即 75% 的访问都要达标,而不是平均值——平均值会被少数极快或极慢的样本带偏。

几个关键量级要先建立直觉:

  • 大多数设备的目标帧率是 ,所以每帧预算大约是:

浏览器自己的渲染、样式计算、合成也要占用时间,留给 JavaScript 的通常只有 左右。任何执行超过 的任务都称为长任务(long task),会阻塞主线程、推迟交互响应,直接推高 INP。

  • LCP 的四个阶段耗时可以这样拆解:

要优化就要先确认卡在哪一段:TTFB 高说明是网络与服务端问题(见 前端-04-浏览器与HTTP),资源加载高说明是体积问题,渲染高说明是主线程被 JavaScript 占满。

5.2 定位瓶颈:Lighthouse 与 Performance 面板

Lighthouse 做的是「实验室」诊断(固定网络与设备模型,可复现,但不等同于真实用户):

  1. 打开 DevTools → Lighthouse 面板。
  2. 勾选 Performance + Accessibility + Best Practices + SEO。
  3. 设备选 Mobile(移动端 CPU 与网络远差于桌面,问题更容易暴露)。
  4. 点击 Analyze page load,等待约 30 秒。
  5. 先看 Opportunities 一节——它直接列出「省下多少毫秒」,是性价比最高的入口。
  6. 再看 Diagnostics,例如「避免巨大的网络负载」「最小化主线程工作」。

Performance 面板做的是「我这次操作的细节」(可录制任意交互,不只是首屏):

  1. 打开无痕窗口(避免插件污染结果),DevTools → Performance。
  2. 点击齿轮,把 CPU 降速设为 4x——用你 3 GHz 的机器测性能,等于自欺欺人。
  3. 点击 ● 录制,执行你要分析的操作(比如「打开筛选面板」),停止录制。
  4. 从上往下读火焰图:
  • 最上面一行是 Frames:出现红色三角表示这一帧超时掉帧。
  • 中间是 Main 轨道:横条越宽表示占用主线程越久;带红色角的横条就是长任务。
  • 点击任意横条,底部 Bottom-Up 面板按「自身耗时」排序,直接告诉你是哪个函数最贵;Call Tree 则显示调用链。
  1. 如果想看「谁触发了它」,用 Bottom-Up 里的 self time 排序 + Source 跳转到源码行。

先量化,再优化

没有测量就优化,等于凭感觉改代码。正确的顺序永远是:

测量 → 找到最大的那一项 → 只改它 → 再测量 → 确认收益 → 记录基线。

优化前把基线数字(如「LCP 4.2 s」)写进 PR 描述,评审时才有依据判断这次改动是否值得合并。

5.3 常见优化清单

图片:通常占页面总字节的一半以上
<!-- 1. 首屏外的图片延迟加载;务必写 width/height,
        否则图片加载完成时会把下方内容挤下去,直接恶化 CLS -->
<img
  src="/img/cover-800.webp"
  srcset="/img/cover-400.webp 400w, /img/cover-800.webp 800w, /img/cover-1600.webp 1600w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
  alt="产品封面"
/>

<!-- 2. 首屏 LCP 图片必须反过来:立即加载 + 高优先级,绝不能 lazy -->
<img
  src="/img/hero-1200.webp"
  width="1200"
  height="600"
  fetchpriority="high"
  alt="首页主视觉"
/>

要点:

  • srcset + sizes 让浏览器按视口宽度选文件,手机不会去下载 1600px 大图。
  • 格式优先 AVIF → WebP → JPEG/PNG,用 <picture> 提供回退。
  • 只有首屏之外的图片才 loading="lazy";对 LCP 元素用 lazy 会显著推迟 LCP。
字体:最容易造成「文字迟一秒才出现」
/* 1. 先用系统字体兜底,避免 FOIT(文字长时间不可见) */
@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-var.woff2") format("woff2-variations");
  font-display: swap;
  font-weight: 100 900;
  unicode-range: U+0000-00FF, U+4E00-9FFF;
}

body {
  font-family: Inter, system-ui, -apple-system, "Segoe UI", sans-serif;
}
  • 字体文件放同源并自身支持缓存,或至少加 preconnect 提前建连。
  • 用 unicode-range 做字形子集化:中文字体动辄数 MB,按常用字切子集后可以降到几十 KB。
  • 只 preload 首屏真正用到的那一个字体文件,preload 多了反而会挤占关键资源带宽。
代码分割与路由懒加载
// 路由级懒加载:首屏只下载当前页面所需代码
const routes = [
  { path: "/", component: () => import("./pages/Home.vue") },
  { path: "/orders", component: () => import("./pages/Orders.vue") },
  {
    path: "/admin",
    // 魔法注释给 chunk 命名,构建产物里一眼能看出是哪个页面
    component: () => import(/* webpackChunkName: "admin" */ "./pages/Admin.vue"),
  },
];

// 组件级:重组件(图表、富文本编辑器)只在真正打开时才加载
const showEditor = ref(false);
const Editor = defineAsyncComponent(() => import("./components/RichEditor.vue"));

配合 Vite 的手动分包,把变动频率低的第三方库单独拆出来,让它们能被长期缓存:

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // 框架版本不变时,这个 chunk 的 hash 不变,用户无需重复下载
          vendor: ["vue", "vue-router", "pinia"],
          charts: ["echarts"],
        },
      },
    },
    // 超过 500 KB 的 chunk 会在构建时警告,提醒你考虑继续拆分
    chunkSizeWarningLimit: 500,
  },
};
preload / prefetch / preconnect / dns-prefetch
指令语义典型用法
preconnect提前完成 DNS + TCP + TLS 握手关键第三方域名(字体站、CDN、图片域名)
dns-prefetch只提前解析 DNS,开销极小兜底,覆盖 preconnect 不支持的旧环境
preload当前页面很快就会用到,高优先级提前下载首屏字体、首屏 LCP 图片、关键 CSS/JS
prefetch下一个页面可能用到,空闲时低优先级下载大概率要跳转的路由 chunk
<link rel="preconnect" href="https://cdn.example.com" crossorigin />
<link rel="dns-prefetch" href="https://cdn.example.com" />
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />
<link rel="prefetch" href="/assets/checkout-page.js" as="script" />

preload 的坑

preload 是强提醒:浏览器会以高优先级下载,无谓的 preload 会抢占关键资源带宽,反而拉高 LCP。

另外 as 属性必须写对(font、image、script、style、fetch),错了会导致下载两次。

字体 preload 必须带 crossorigin,否则会被当成不同源的第二次请求。

减少第三方脚本与拆分长任务

第三方脚本(统计、客服、埋点、广告)是性能杀手,因为它们不受你控制、经常同步加载、还各自动手改 DOM:

  • 一律加 defer;能延后的(客服气泡、A/B 实验)等到 requestIdleCallback 或首次交互后再加载。
  • 用 DevTools 的 Coverage 面板(Ctrl+Shift+P → Show Coverage)看有多少 JS/CSS 从未被执行。
  • 定期审计:一个上线一年的后台,第三方脚本从 2 个涨到 12 个是常态。

长任务用「切片」拆开,把主线程还给浏览器:

// 反面写法:一次性处理 5 万条数据,主线程卡住 1.5 秒,期间的点击全部排队
function renderAll(rows) {
  for (const row of rows) heavyRowRender(row);
}

// 正面写法 1:用 requestIdleCallback 在空闲时间分批处理
function renderInBatches(rows, batchSize = 200) {
  let index = 0;
  const step = (deadline) => {
    // 只要还有空闲时间,就继续做;否则让出主线程
    while (index < rows.length && deadline.timeRemaining() > 1) {
      heavyRowRender(rows[index++]);
    }
    if (index < rows.length) requestIdleCallback(step);
  };
  requestIdleCallback(step);
}
// 正面写法 2:把纯计算搬到 Web Worker,主线程完全不参与
// worker.js
self.onmessage = (e) => {
  const result = e.data.rows.map(computeExpensiveScore);
  self.postMessage(result);
};

// main.js
const worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
worker.postMessage({ rows });
worker.onmessage = (e) => updateChart(e.data);

若真要一次性处理超大数组,可用 scheduler.yield()(新 API,以官方最新文档为准)或返回 Promise 的 await new Promise(r => setTimeout(r, 0)) 主动让出。

缓存的收益要按「复访」来算

静态资源用内容哈希命名 + Cache-Control: public, max-age=31536000, immutable,HTML 用 no-cache(每次都校验)。这样第二次访问可以做到几乎零请求。细节见 前端-04-浏览器与HTTP 与 前端-08-构建工具-Vite与Webpack。

六、DevTools 高效用法

DevTools 有 20 多个面板,日常真正高频的只有六个。按「要解决的问题」来记:

6.1 Elements:结构与样式

操作快捷键用途
选中元素Ctrl+Shift+C直接点页面上任意元素,比在 DOM 树里找快 10 倍
编辑 HTML双击标签/属性临时改文案不用改代码
强制元素状态右键 → :hov → :hover / :focus / :active调试只在悬停时出现的下拉菜单,不用一直按着鼠标
动态类名右键 → Break on → attribute modifications抓住「谁把我的 class 删了」
事件监听右侧 Event Listeners查看该元素上绑了哪些监听器,并可跳转源码
无障碍树右侧 Accessibility检查是否有可访问名称、对比度是否达标

盒模型(Box Model) 是 CSS 调试的核心,见 前端-02-CSS基础。在 Elements 面板选中元素后,右下角会画出由外到内的四层:

┌──────────── margin(外边距:不响应点击,透明) ────────────┐
│ ┌────────── border(边框:参与尺寸计算) ──────────┐      │
│ │ ┌──────── padding(内边距:背景色会铺满) ────┐ │      │
│ │ │            content(内容:width/height)     │ │      │
│ │ └────────────────────────────────────────────┘ │      │
│ └────────────────────────────────────────────────┘      │
└──────────────────────────────────────────────────────────┘

调试时的两个关键问题:

  • 「为什么这个元素这么宽?」 看盒模型图上的数字:是内容撑开的,还是 padding 撑开的?同时看 Styles 面板里被划掉的声明——那说明它被更高优先级的规则覆盖了。
  • 「用了 box-sizing: border-box 后尺寸对不上?」 注意 border-box 会把 padding 和 border 计入 width,但不含 margin。

6.2 Console:不只是 console.log

Console 支持完整的 JS 表达式求值,还有一批内置快捷命令(无需声明即可使用):

命令作用场景
$0` | **当前选中**的元素 | 在 Elements 里点一下元素,回 Console 直接 `$0.dataset.id
$1` … `$4之前选中的元素对比两个元素的样式或位置
$('selector')document.querySelector 的缩写少打 20 个字符
$$('selector')document.querySelectorAll,返回真数组可直接 .map()
copy(obj)把值以 JSON 形式复制到剪贴板把接口返回的大对象贴进编辑器分析
table(arr)以表格展示数组/对象数组看接口列表数据,比展开对象清楚得多
dir(obj)以对象树形式输出查看原型链与不可枚举属性
monitorEvents(el, 'click')打印该元素上发生的所有事件排查「事件到底有没有绑上」
unmonitorEvents(el)停止监听用完记得关,否则刷屏
monitor(fn)每次函数被调用就打印参数追踪某个工具函数的调用时机
// 真实排查流程:为什么点击没反应?
const btn = $(".submit-btn");   // 元素存在吗?
monitorEvents(btn, ["click", "mousedown", "mouseup"]);
// 点击之后 Console 里一个事件都没打 → 说明根本没点到它
// → 回 Elements,看是不是被一个透明的浮层盖住了(position: fixed; inset: 0)

其他实用技巧:

  • 用 console.table() 而不是循环 console.log()。
  • 用 console.time("x") / console.timeEnd("x") 做粗粒度计时。
  • 用 console.trace() 打印调用栈,快速知道「谁调用了这个函数」。
  • 用 console.group() / console.groupEnd() 把日志分组,避免刷屏。
  • Log 级别过滤:console.warn / console.error 会在面板上显示不同图标,配合筛选框「Errors only」可只看错误。

6.3 Network:瀑布图怎么读

瀑布图(Waterfall)从左到右是时间轴,每一行是一次请求。读图的顺序:

  1. 先看有没有红色的 4xx / 5xx。有就别急着优化速度,先把接口修对。
  2. 看 Size 列与底部汇总:总传输量多少?哪些请求最大?单个资源超过 1 MB 基本就是问题。
  3. 看 Time 列排序:点一下列头按耗时降序,最慢的几条就是优化目标。
  4. 看瀑布图的形状:
  • 多个请求串成一条链(前一个的响应里有后一个的地址)→ 请求瀑布,属于依赖链问题,考虑并行或服务端聚合。
  • 大量请求同时开始、同时结束 → 可能是并发数限制(HTTP/1.1 下同域名通常 6 个连接)。
  • 请求开始得很晚,前面有一大段空白 → 被 JS 或其他资源阻塞了。
  1. 看单条请求的 Timing 分栏(悬停或点开 Timing):
  • Queueing / Stalled:排队或被浏览器限制(连接数满、磁盘缓存检查)。
  • DNS Lookup / Initial connection / SSL:建连开销,preconnect 能省掉这一段。
  • Waiting (TTFB):服务端处理时间。这一项高的话前端无能为力,要找后端。
  • Content Download:真正传输内容的时间,体积大就会长。
  1. 右键请求 → Save as HAR with content 可以把整段网络记录导出给同事分析。

常用筛选与开关:

  • Fetch/XHR 只看接口,Img 只看图片,JS / CSS 只看静态资源。
  • 勾选 Disable cache(调试缓存问题时必开,否则看到的是缓存结果)。
  • 勾选 Preserve log(跳转页面后日志不丢,排查登录跳转必备)。
  • 节流(Throttling)选 Slow 4G,模拟弱网。

6.4 Sources:四种断点

断点类型怎么设什么时候用
行断点在行号上点击最常用:想知道这一行执行时变量的真实值
条件断点右键行号 → Add conditional breakpoint,写表达式循环里只想在第 847 次迭代停下来,或 userId === 'u_123' 时停
日志点右键行号 → Add logpoint,写 'id=' + user.id不暂停执行也能打日志,比加 console.log 干净(不用改代码、不会忘记删)
DOM 断点Elements → 右键元素 → Break on → subtree / attribute / node removal追查「谁在偷偷改这个 DOM」
XHR/Fetch 断点Sources → 右侧 XHR/fetch Breakpoints → 填 URL 片段想知道某个接口是谁发的、参数从哪来
事件监听器断点Sources → Event Listener Breakpoints → 勾 click / keydown事件处理逻辑不明时,一有点击就停

调试技巧:

  • Call Stack 面板双击任意栈帧可跳到对应源码;Async 折叠项可以追进 await 之前的异步调用链。
  • Scope 面板显示当前作用域链上的所有变量(Local / Closure / Global),比在 Console 里猜变量名高效。
  • Watch 表达式适合盯住一个复杂表达式,每步都自动求值。
  • 在 Sources → Snippets 里可以把常用调试代码存成片段,跨项目复用。
  • Overrides(覆盖)允许把线上 JS/CSS 文件映射到本地副本,改完刷新即生效——排查线上问题而不必走一次发布流程。

配置 Source Map 才能在断点里看到原始源码而不是压缩后的代码:

// vite.config.js
export default {
  // 打成独立 .map 文件,不内联进 JS,避免首屏体积增大
  build: { sourcemap: true },
};

6.5 Application:存储与缓存

区域看什么关键点
Local Storage / Session Storage键值对、大小同步 API,容量约 5 MB,不要存大对象
Cookies域名、路径、HttpOnly、Secure、SameSite、过期时间HttpOnly 的 Cookie 在 JS 里读不到,这是防 XSS 窃取 token 的关键
Cache StorageService Worker 缓存的内容PWA 更新不生效时先来这里看
IndexedDB结构化大数据存离线数据、附件;在 DevTools 里可直接浏览
Service Workers注册状态、Update on reload调试时勾 Bypass for network 可临时绕过缓存
Storage「Clear site data」一键清空排查「清缓存后就好了」类问题的答案
Frames → 顶部当前页面被谁嵌在 iframe 里排查嵌入与跨域问题

缓存问题的一半都是「你以为清了但没清」

Ctrl+F5 只清当前页面的 HTTP 缓存。Service Worker 缓存、Cache Storage、IndexedDB 都不会被清掉。

遇到「代码明明改了页面却没变」,先到 Application → Storage → Clear site data 全清一遍,再判断是不是真的没生效。

6.6 其他值得知道的面板

  • Rendering(Ctrl+Shift+P → Show Rendering):Paint flashing 高亮重绘区域、Layout Shift Regions 高亮 CLS 发生位置。优化重排重绘时的第一站,见 前端-04-浏览器与HTTP。
  • Coverage:显示每个 JS/CSS 文件「已执行比例」。0% 的文件就是死代码,可直接删。
  • Memory:Heap snapshot 对比两次快照的差值可以定位内存泄漏——对象数量持续增长而从不减少,就是泄漏点。
  • Device Toolbar(Ctrl+Shift+M):切设备与网络条件,也可自定义 UA 测服务端渲染差异。

七、错误监控

7.1 捕获全局错误

没有任何监控的线上环境,用户报「白屏」时你只能猜。前端有两类全局错误必须都接:

// 1. 同步运行时错误 + 资源加载失败,都会走 window.onerror
//    注意:跨域脚本的错误默认会被浏览器隐藏为 "Script error.",见下方说明
window.addEventListener("error", (event) => {
  // 资源加载失败(img/script/link)不冒泡到 window,只能在捕获阶段拿到
  const target = event.target;
  if (target && (target.tagName === "IMG" || target.tagName === "SCRIPT")) {
    report({
      type: "resource",
      url: target.src || target.href,
      tag: target.tagName,
    });
    return;
  }

  report({
    type: "error",
    message: event.message,
    source: event.filename,
    line: event.lineno,
    column: event.colno,
    stack: event.error?.stack,
  });
}, true); // ← 必须以捕获阶段监听,否则拿不到资源错误

// 2. 未被 catch 的 Promise 拒绝,不会触发上面的 error 事件,必须单独监听
window.addEventListener("unhandledrejection", (event) => {
  const reason = event.reason;
  report({
    type: "unhandledrejection",
    message: reason?.message ?? String(reason),
    stack: reason?.stack,
  });
});

// 3. 框架层兜底:组件渲染中抛出的错误(比全局钩子更早、更精确)
// Vue
app.config.errorHandler = (err, instance, info) => {
  report({ type: "vue", message: err.message, stack: err.stack, info });
};

// React:用 Error Boundary 包住路由出口
class ErrorBoundary extends React.Component {
  state = { hasError: false };
  static getDerivedStateFromError() { return { hasError: true }; }
  componentDidCatch(error, info) {
    report({ type: "react", message: error.message, stack: error.stack, componentStack: info.componentStack });
  }
  render() { return this.state.hasError ? <Fallback /> : this.props.children; }
}

跨域脚本会变成 "Script error."

当脚本来自其他源且响应里没有 Access-Control-Allow-Origin 时,浏览器出于安全考虑会隐藏错误的详细信息,只给你一句无用的 Script error.,行列号也是 0。

解决办法:给脚本标签加 crossorigin="anonymous",同时让 CDN 返回 Access-Control-Allow-Origin: *。静态资源放自己域名下最省事。

7.2 Error 对象与堆栈

Error 的 message 只是给人看的描述,真正有诊断价值的是 stack:

TypeError: Cannot read properties of undefined (reading 'name')
    at renderUser (http://localhost:5173/src/user.ts?t=1730000000000:42:15)
    at Array.map (<anonymous>)
    at UserList.setup (http://localhost:5173/src/UserList.vue:31:5)

堆栈的读法是从下往上:最早被调用的在下面,出错的那一帧在最上面。上面这条读作「UserList.setup 调用了 map,map 调用 renderUser,在 renderUser 的 42 行访问 undefined.name 时崩了」。

自定义错误时保留正确的堆栈:

// 用 class 继承,堆栈与 name 都会正确
class ApiError extends Error {
  constructor(message, { status, url, traceId } = {}) {
    super(message);
    this.name = "ApiError";
    this.status = status;
    this.url = url;
    this.traceId = traceId; // 后端返回的链路 ID,前后端日志可以对上
  }
}

// 用 cause 保留原始错误,避免在重新抛出时丢失根因
try {
  await submitOrder(payload);
} catch (err) {
  throw new ApiError("下单失败", { status: 502, cause: err });
}

// 错误实例自身的字段也要上报,否则只有一句 message 无法排查
window.addEventListener("unhandledrejection", (e) => {
  const err = e.reason;
  report({ name: err?.name, message: err?.message, stack: err?.stack, status: err?.status, traceId: err?.traceId });
});

7.3 Source Map 在生产环境的取舍

生产代码经过压缩、混淆、tree-shaking,堆栈里的 a.b.c 和 t=1730000000000 完全不可读。Source Map 就是把压缩代码映射回源码的索引,问题是:它同时也完整暴露了你的源码。三种策略:

策略做法优点风险
公开托管.map 与 JS 一起部署,结尾保留 //# sourceMappingURL=浏览器 DevTools 直接可读,零额外设施任何人打开 DevTools 就能看到全部源码,包括注释、接口路径、内部逻辑
仅上传不公开(推荐)构建时产出 .map 并上传到监控平台(如 Sentry),部署产物里删掉 .map 且去掉 sourceMappingURL 注释堆栈在监控平台里是可读源码,外部拿不到需要构建脚本配合
完全不产出关闭 sourcemap无泄漏风险线上错误基本无法定位
// vite.config.js —— 「仅上传不公开」的配置
export default {
  build: {
    // 产出独立 .map 文件,但部署前需要删除
    sourcemap: true,
  },
};

// vite.config.js —— 「完全不产出」,只想要体积最小
// export default { build: { sourcemap: false } };
# 构建后把 .map 上传给监控平台,再删掉它们,最后部署 dist
npx @sentry/cli sourcemaps upload ./dist --release "$GIT_SHA"
find ./dist -name "*.map" -delete
# 也要去掉 bundle 末尾的 sourceMappingURL 注释,否则浏览器会去请求已删除的文件(404 噪声)
find ./dist -name "*.js" -exec sed -i '/sourceMappingURL/d' {} +

三个必须记住的点

1. sourceMappingURL 注释要一起删。只删 .map 文件会留下一堆 404 请求,还会让 DevTools 报警告。

2. Release 版本号必须唯一且稳定(一般用 Git commit SHA)。上传的 map 与线上的 JS 靠它对应,对不上就还原不出源码。

3. --release 值前后端要一致,否则前端堆栈映射不上后端日志里的 traceId。

7.4 第三方监控接入思路

不必自建上报服务,主流方案(Sentry、阿里 ARMS、腾讯 RUM、Fundebug 等)都是同一个套路:

// 统一的上报出口:所有错误都经过这里,方便加公共字段、过滤与限流
const REPORT_URL = "/api/monitor/error";
const queue = [];
const lastSent = new Map(); // 错误指纹 → 上次上报时间
let timer = null;

function report(payload) {
  // 去重:同一个错误 60 秒内只上报一次,否则一个渲染循环里的异常能刷出上万条
  const key = `${payload.message}|${payload.source}:${payload.line}`;
  const now = Date.now();
  if (now - (lastSent.get(key) ?? 0) < 60_000) return;
  lastSent.set(key, now);

  queue.push({
    env: import.meta.env.MODE, // 排查时第一眼要知道是哪个环境
    release: __GIT_SHA__,      // 与 Source Map 的 --release 对应
    userIdHash: getUserIdHash(), // 用户标识用哈希,不能是手机号或邮箱
    route: location.pathname,
    ua: navigator.userAgent,
    ts: now,
    ...payload,
  });

  // 批量合并:2 秒内的错误打包成一次请求
  if (!timer) {
    timer = setTimeout(() => {
      timer = null;
      navigator.sendBeacon?.(REPORT_URL, JSON.stringify(queue.splice(0, 20)));
    }, 2000);
  }
}

选型时对比这几点(具体能力以各家官方文档为准):

  • 是否支持 Source Map 自动还原(这是最核心的能力)。
  • 采样与配额:免费额度多少、超限后是丢弃还是计费。
  • SDK 体积:监控脚本本身不能成为新的性能负担,注意它会被算进你的 JS 体积。
  • 是否有 Performance 与 Session Replay:出错时能看到用户的操作录像或性能轨迹,定位效率差好几倍。

7.5 上报脱敏

监控数据里经常无意带上敏感信息,而监控平台往往是权限最宽松的系统——一次上报疏漏就等于一次数据泄露。

// 1. 页面 URL 里的 query 可能含 token、手机号,上报前一律剥离
function sanitizeUrl(url) {
  try {
    const u = new URL(url, location.origin);
    return `${u.origin}${u.pathname}`; // 只留路径,丢掉全部 query 与 hash
  } catch {
    return String(url).split("?")[0];
  }
}

// 2. 堆栈里可能嵌入了带敏感值的源码片段,做一层模式替换
const SENSITIVE_PATTERNS = [
  /[\w.+-]+@[\w-]+\.\w+/g,                        // 邮箱
  /\b1[3-9]\d{9}\b/g,                            // 中国大陆手机号
  /\b\d{17}[\dXx]\b/g,                           // 身份证号
  /\b(?:\d[ -]*?){13,19}\b/g,                    // 银行卡号
  /\b(?:token|password|secret|api[_-]?key)=[^\s&"']+/gi, // 键值形式的凭据
];

function sanitize(text) {
  return SENSITIVE_PATTERNS.reduce((acc, re) => acc.replace(re, "[REDACTED]"), String(text ?? ""));
}

// 3. Request Body 默认不上报;确实需要时只保留白名单字段名
// 4. 用户名、用户 ID 用不可逆哈希或内部 ID,不要上报手机号/邮箱
// 5. 输入框内容一律不采集,包括 Session Replay 的 input 值(正式环境务必开启屏蔽)

三条红线

- 绝不采集密码、验证码、身份证号、银行卡号、完整手机号。

- 绝不上报完整请求体与响应体(其中常含 token 与隐私字段)。

- Session Replay 在正式环境必须开启输入框遮罩,否则等于把用户填写的表单录下来存到第三方。

八、可观测性:Core Web Vitals 采集

线上真实的 LCP / INP / CLS 只能靠浏览器自己的性能观测 API 采集,而不是 Lighthouse。

// 通用的指标采集骨架:PerformanceObserver 观察性能条目,回调里拿到数据
function observe(type, callback, extra = {}) {
  try {
    const po = new PerformanceObserver((list) => {
      // 取最后一条:指标可能被多次更新(LCP 会在页面生命周期内持续修正)
      const entries = list.getEntries();
      callback(entries[entries.length - 1], entries);
    });
    po.observe({ type, buffered: true, ...extra }); // buffered: 拿到注册之前就已产生的条目
    return po;
  } catch {
    return null; // 旧浏览器不支持该 type,静默降级
  }
}

let lcpValue = 0;

// LCP:largest-contentful-paint。注意元素是「视口内最大的内容元素」,
// 图片、视频封面、背景图、大块文本都可能成为 LCP 元素。
observe("largest-contentful-paint", (entry) => {
  lcpValue = entry.startTime;
  // element 可以帮助判断到底是哪个元素拖慢了 LCP(Chrome 支持)
  sendMetric("LCP", Math.round(lcpValue), {
    element: entry.element?.tagName,
    url: entry.url,
  });
});

// 交互延迟:event 条目的 duration 反映「点击到下一帧绘制」的延迟
let worstInp = 0;
observe("event", (entry) => {
  // 只统计真实交互,忽略 mouseover/scroll 这类非交互事件
  if (["click", "keydown", "pointerdown"].includes(entry.name)) {
    worstInp = Math.max(worstInp, entry.duration);
  }
}, { durationThreshold: 40 }); // 只上报超过 40ms 的交互,降低噪声

// CLS:累计布局偏移。hadRecentInput 为 true 表示是用户主动操作导致的位移,不计入
let clsValue = 0;
observe("layout-shift", (entry) => {
  if (!entry.hadRecentInput) clsValue += entry.value;
});

// 离开页面时统一上报:用 visibilitychange 而不是 unload
// (unload 在移动端常被跳过,且会阻塞 bfcache)
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState !== "hidden") return;
  sendMetric("INP", Math.round(worstInp));
  sendMetric("CLS", Number(clsValue.toFixed(4)));
});

几个必须知道的坑:

  • LCP 只在页面「真正加载完」之前有效。用户点击后 LCP 就不再更新,所以单页应用(SPA)内部路由切换不会产生新的 LCP。
  • CLS 必须排除 hadRecentInput。用户点了「展开」导致的内容位移不算问题,如果不过滤,数据里会混入大量假阳性。
  • SPA 的 INP 只统计最差的一次交互(p98 左右的高分位值),所以一个偶发的长任务就会拉高整页分数——这正是它比「平均响应时间」更有价值的地方。
  • 一定要带维度上报:页面路径、设备类型、网络类型、国家、版本号。只看一个全局平均值,无法定位问题;按维度分组后往往一眼能看出「只有安卓低端机慢」。
  • 对照组很重要:改动前后各观察一周,确认 p75 真的下降,而不是被流量波动掩盖。

自建采集成本不低(要考虑采样率、上报量、聚合查询),如果只是要一个数,用现成的 RUM 服务更快;但如果要按业务维度深挖,自建更自由。

九、新项目起步清单

把一个新前端仓库做成「团队可用」,下面这份清单可以直接复制使用:

my-project/
├── .editorconfig                 # 编辑器统一缩进/行尾/编码
├── .prettierrc.json / .prettierignore
├── eslint.config.js              # Lint 规则(含 eslint-config-prettier 在最后)
├── commitlint.config.js          # 提交信息规范
├── tsconfig.json                 # strict + noEmit(CI 用)
├── vite.config.js                # 构建、分包、sourcemap
├── package.json                  # scripts: dev/build/lint/typecheck/test
├── package-lock.json             # 必须提交,保证依赖可复现
├── .husky/pre-commit             # npx lint-staged
├── .husky/commit-msg             # npx commitlint --edit
├── .github/workflows/ci.yml      # 格式 + Lint + 类型 + 测试 + 构建
├── .env.example                  # 环境变量模板(不含真实密钥)
└── src/

动手顺序(每一步都能独立生效,不必一次做完):

  1. npm create vite@latest 起项目,git init 并提交一次基线。
  2. 装 Prettier,跑一次 --write,单独提交(这次提交只有格式改动,否则后面所有 diff 都不可读)。
  3. 装 ESLint + typescript-eslint + eslint-config-prettier,npx eslint . 跑到零 error。
  4. 打开 tsconfig.json 的 strict,修完类型错误。
  5. 装 Husky + lint-staged + commitlint,配好三个钩子。
  6. 写 ci.yml,在 GitHub 上把 check 设为 required status check。
  7. 接入错误监控 + Source Map 上传,并写一条能在测试环境触发的错误验证全链路。
  8. 补 Core Web Vitals 采集,记录第一版性能基线数字。

最后一条建议

这套配置的全部价值都在「自动化」上。如果每次都要靠人在 Code Review 里提醒「这里少个分号」「提交信息写清楚点」,那说明配置没生效——回去把规则加进 CI,让机器去说。

常见坑

代码规范

- 只配 Lint 不配 CI:本地钩子可以被 --no-verify 绕过,CI 才是唯一可靠的门禁。

- eslint-config-prettier 放错位置:它必须最后一项,否则被后续配置重新打开冲突规则。

- prettier --write 与 --check 混用:CI 里必须是 --check,用 --write 会把不合规代码「改好」然后静默通过。

- 忽略文件没配:把 dist/、node_modules/、自动生成的类型文件也格式化,导致构建产物被改动、PR diff 爆炸。

类型检查

- 以为 vite build 会检查类型:不会。它只做类型擦除,必须单独跑 tsc --noEmit。

- 把 skipLibCheck: true 当成万能药:它跳过的是 node_modules 里 .d.ts 的检查,不是你的业务代码。

- 用 any 消掉报错:any 会让错误在下游以运行时崩溃的形式重新出现,比原本的报错更难查。宁可写 unknown + 收窄。

- .vue 文件里类型不报错就以为没问题:.vue 的模板部分要靠 vue-tsc 才会被检查。

调试

- 忘了开 Disable cache:改了代码看到的是缓存结果,白白怀疑人生半小时。

- 以 console.log 为唯一手段:它改代码、要删、生产环境要担心泄漏,条件断点和日志点更干净。

- 只看平均耗时:性能问题通常集中在 p95/p99,平均值会把它藏起来。

- 在 3 GHz 的台式机上测移动端性能:务必用 CPU 4x/6x 降速或真机。

错误监控

- 只监听 window.onerror:Promise 拒绝走 unhandledrejection,资源加载失败需要捕获阶段监听。

- 跨域脚本没加 crossorigin:只能拿到 Script error.,等于没有监控。

- Source Map 直接公开部署:源码可被任何人下载。应「上传给监控平台后从产物中删除」。

- 上报里带敏感信息:URL query、请求体、输入框内容都可能含隐私数据,必须脱敏。

练习题

练习 1:把格式规则从 ESLint 迁到 Prettier

某项目在 ESLint 里配置了 indent: ["error", 2]、quotes: ["error", "double"]、semi: ["error", "always"],同时又用 Prettier,导致保存时格式反复横跳。请说明原因,并给出修复后的 eslint.config.js 结构(用文字或代码描述都行)。

提示:想清楚「谁负责排版」,以及 eslint-config-prettier 的引入位置。

练习 2:设计门禁流水线

团队规定:格式必须统一、Lint 必须零 error、类型必须通过、单元测试必须全绿、构建必须成功。请写出对应的 package.json scripts,以及 CI 中这些步骤的执行顺序,并说明为什么是这个顺序。

提示:考虑「便宜的检查先失败」这一原则,以及 npm ci 与 npm install 在 CI 中的区别。

练习 3:读一条提交信息,定一个版本号

当前版本是 2.3.4。这一批合并进主干的提交有:

fix(cart): 修正优惠券重复叠加、feat(search): 支持拼音搜索、docs: 补充部署说明、refactor(api): 拆分请求层,另有一条 feat(auth)!: 移除 v1 登录接口。

下一个版本号应该是多少?CHANGELOG 里哪些条目会出现在最前面?

提示:! 与 footer 里的 BREAKING CHANGE: 等价。

练习 4:从瀑布图找到 LCP 瓶颈

你在 Mobile + Slow 4G 下测得:LCP = 4.8 s,而 TTFB 只有 200 ms。Network 面板显示首屏有一个 2.4 MB 的 hero.png,且它的请求在时间轴上开始得很晚(前面有一大段空白)。请给出至少三条优化措施,并说明每条针对 LCP 四个阶段中的哪一段。

提示:转换格式、调整尺寸、改用 fetchpriority、检查它是否被 loading="lazy" 拖后了。

练习 5:写一个安全的上报出口

请写一个 reportError(err, context) 函数,要求:去掉 URL 中的 query、把邮箱与手机号替换为 [REDACTED]、同一错误 60 秒内只上报一次、用 sendBeacon 批量发送。

提示:用 URL 解析剥离 query,用正则做替换,用 Map 记录每个错误指纹的上次上报时间。

FAQ

ESLint 和 TypeScript 的类型检查是不是重复了?

不重复,它们看的是不同层次的问题。

TypeScript 检查类型是否正确(string 传给了 number 参数);ESLint 检查类型正确但写法有问题的代码(await 漏写、== 误用、Hook 依赖不全、console.log 忘删)。

有些规则确实需要类型信息(称为 type-aware rules,如 no-floating-promises),它们由 typescript-eslint 提供,会比纯语法规则慢一些,但收益值得。两者都要跑。

为什么我的项目 npm run build 成功了,线上却报 undefined is not a function?

三个常见原因,按概率排序:

1. 类型错误没被 CI 拦住。构建工具只做类型擦除,不检查类型;必须单独跑 tsc --noEmit。

2. 依赖版本不一致。本地装的是 ^1.2.0 解析到 1.5.0,CI 或服务器装到了别的版本。用锁文件 + npm ci 解决。

3. 环境差异。浏览器版本、polyfill、环境变量不同。先在出问题的环境打开 Console 看第一行错误,再看堆栈。

性能优化应该先做哪一件?

先测量,再改最大的一项。经验上首屏优化的收益排序大致是:①减小关键资源体积(图片、字体、JS 首包)→ ②减少关键路径上的请求数(合并、内联关键 CSS、preload)→ ③延后非关键 JS(defer、路由懒加载、第三方脚本)→ ④缓存与 CDN。

但具体项目里哪一项最大必须实测。同时注意别只盯 LCP:为了 LCP 把内容提前渲染出来却不知道尺寸,很可能把 CLS 从 0 抬到 0.3,那是拆东墙补西墙。

线上错误那么多,怎么排优先级?

按「影响用户数 × 严重程度」排序:

- 影响用户数:用错误指纹聚合后的独立用户数(不是触发次数),一个死循环能刷出十万条但只影响一个人。

- 严重程度:白屏 / 主流程中断 > 功能不可用 > 样式异常 > 控制台警告。用户无法完成下单的错误,优先级永远高于一个错位的图标。

- 再看新增趋势:新版本发布后某类错误突然从 0 涨到每天几百条,那是这次发版引入的回归,应立刻回滚或热修。

相关笔记

  • 前端-04-浏览器与HTTP —— 渲染流程、重排重绘、缓存与跨域,是理解 LCP/CLS 与 Network 面板的前提
  • 前端-05-TypeScript —— 类型系统与 tsconfig 的完整讲解,本篇只讲它在门禁里的用法
  • 前端-08-构建工具-Vite与Webpack —— 代码分割、分包策略与 Source Map 的构建侧配置
  • 工具-05-GitHub与GitLab协作 —— 分支策略、Pull Request 与 Code Review 流程
  • 工具-08-CICD入门 —— 把本篇的门禁步骤串成流水线
  • 工具-03-包管理器 —— 锁文件、语义化版本与依赖可复现性
  • 工具-07-调试技巧 —— 语言无关的通用调试方法论

参考来源

  • MDN Web Docs(中文)—— Web 性能与调试相关指南:<https://developer.mozilla.org/zh-CN/docs/Learn_web_development/Extensions/Performance>
  • ESLint 官方文档 —— 规则、扁平配置与命令行用法:<https://eslint.org/docs/latest/>
  • Prettier 官方文档 —— 配置项、CLI 与 eslint-config-prettier 的配合说明:<https://prettier.io/docs/>
  • Vite 官方文档 —— 构建配置、代码分割与 Source Map:<https://vite.dev/guide/>
  • TypeScript 官方文档 —— tsconfig 各编译选项与 strict 系列:<https://www.typescriptlang.org/tsconfig/>

版本敏感提示

ESLint 的扁平配置(eslint.config.js)从 v9 起成为默认格式,旧项目可能仍在用 .eslintrc.*;Husky 在 v9 之后的钩子写法也有变化。

本篇的命令与配置以官方最新文档为准,落地前请对照官方文档确认当前版本语法。