前端-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 |
这五条问题对应工程化的五个支柱,这篇笔记就按这个顺序讲:
- 一致性:代码风格与格式由工具决定,不由人决定(ESLint + Prettier + EditorConfig)。
- 可复现:依赖可复现、构建可复现(锁文件 + CI,见 工具-03-包管理器)。
- 可追溯:提交信息规范化,能自动生成版本号与变更日志。
- 有门禁:类型检查、Lint、测试在合并前自动跑,坏代码进不了主干。
- 可观测:线上性能与错误能被量化、能被告警,而不是等用户投诉。
一句话定义
前端工程化 = 把人的约定变成机器的检查。凡是「靠自觉」的规则,最终都会失效;凡是「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,会遇到两个麻烦:
- 规则数量爆炸:纯格式规则有上百条,配置与维护成本极高。
- 与编辑器格式化冲突: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 | 否 | 破坏性变更、关联 Issue | BREAKING CHANGE:、Closes #128 |
常用 type 取值:
| type | 含义 | 对应语义化版本变化 |
|---|---|---|
feat | 新功能 | MINOR(1.2.0 → 1.3.0) |
fix | 修 bug | PATCH(1.2.0 → 1.2.1) |
perf | 性能优化 | PATCH |
refactor | 重构(不改外部行为) | 不变 |
docs | 只改文档 | 不变 |
test | 增删改测试 | 不变 |
build | 构建系统或依赖变更 | 不变(也可能 PATCH) |
ci | CI 配置变更 | 不变 |
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 究竟打开了什么
| 选项 | 效果 | 不开会怎样 |
|---|---|---|
strictNullChecks | null / undefined 不再隐式属于所有类型 | user.name 在 user 可能为 null 时也不报错,运行时报 Cannot read properties of null |
noImplicitAny | 推断不出类型时报错,而不是默认 any | 拼错属性名不报错,类型系统形同虚设 |
strictFunctionTypes | 函数参数按逆变检查 | 回调签名不兼容时静默通过 |
strictBindCallApply | 检查 bind / call / apply 的参数 | 参数个数与类型错误无法被发现 |
strictPropertyInitialization | 类属性必须在构造函数中初始化 | 实例属性为 undefined,访问时才崩 |
noImplicitThis | this 推断为 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(核心网页指标),也是搜索引擎排名的输入之一。它们的共同点是:都以真实用户的体验为准,而不是实验室数据。
| 指标 | 全称 | 衡量什么 | 好 | 需要改进 | 差 |
|---|---|---|---|---|---|
| LCP | Largest Contentful Paint | 视口内最大元素的渲染时间(「主要内容多久看到」) | s | s | s |
| INP | Interaction to Next Paint | 用户交互到下一帧绘制的延迟(「点了多久有反应」) | ms | ms | ms |
| CLS | Cumulative Layout Shift | 意外布局偏移的累计分数(「内容会不会乱跳」) |
评估标准取 第 75 百分位(p75):即 75% 的访问都要达标,而不是平均值——平均值会被少数极快或极慢的样本带偏。
几个关键量级要先建立直觉:
- 大多数设备的目标帧率是 ,所以每帧预算大约是:
浏览器自己的渲染、样式计算、合成也要占用时间,留给 JavaScript 的通常只有 左右。任何执行超过 的任务都称为长任务(long task),会阻塞主线程、推迟交互响应,直接推高 INP。
- LCP 的四个阶段耗时可以这样拆解:
要优化就要先确认卡在哪一段:TTFB 高说明是网络与服务端问题(见 前端-04-浏览器与HTTP),资源加载高说明是体积问题,渲染高说明是主线程被 JavaScript 占满。
5.2 定位瓶颈:Lighthouse 与 Performance 面板
Lighthouse 做的是「实验室」诊断(固定网络与设备模型,可复现,但不等同于真实用户):
- 打开 DevTools → Lighthouse 面板。
- 勾选 Performance + Accessibility + Best Practices + SEO。
- 设备选 Mobile(移动端 CPU 与网络远差于桌面,问题更容易暴露)。
- 点击 Analyze page load,等待约 30 秒。
- 先看 Opportunities 一节——它直接列出「省下多少毫秒」,是性价比最高的入口。
- 再看 Diagnostics,例如「避免巨大的网络负载」「最小化主线程工作」。
Performance 面板做的是「我这次操作的细节」(可录制任意交互,不只是首屏):
- 打开无痕窗口(避免插件污染结果),DevTools → Performance。
- 点击齿轮,把 CPU 降速设为 4x——用你 3 GHz 的机器测性能,等于自欺欺人。
- 点击 ● 录制,执行你要分析的操作(比如「打开筛选面板」),停止录制。
- 从上往下读火焰图:
- 最上面一行是 Frames:出现红色三角表示这一帧超时掉帧。
- 中间是 Main 轨道:横条越宽表示占用主线程越久;带红色角的横条就是长任务。
- 点击任意横条,底部 Bottom-Up 面板按「自身耗时」排序,直接告诉你是哪个函数最贵;Call Tree 则显示调用链。
- 如果想看「谁触发了它」,用 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)从左到右是时间轴,每一行是一次请求。读图的顺序:
- 先看有没有红色的 4xx / 5xx。有就别急着优化速度,先把接口修对。
- 看
Size列与底部汇总:总传输量多少?哪些请求最大?单个资源超过 1 MB 基本就是问题。 - 看
Time列排序:点一下列头按耗时降序,最慢的几条就是优化目标。 - 看瀑布图的形状:
- 多个请求串成一条链(前一个的响应里有后一个的地址)→ 请求瀑布,属于依赖链问题,考虑并行或服务端聚合。
- 大量请求同时开始、同时结束 → 可能是并发数限制(HTTP/1.1 下同域名通常 6 个连接)。
- 请求开始得很晚,前面有一大段空白 → 被 JS 或其他资源阻塞了。
- 看单条请求的 Timing 分栏(悬停或点开
Timing):
Queueing/Stalled:排队或被浏览器限制(连接数满、磁盘缓存检查)。DNS Lookup/Initial connection/SSL:建连开销,preconnect能省掉这一段。Waiting (TTFB):服务端处理时间。这一项高的话前端无能为力,要找后端。Content Download:真正传输内容的时间,体积大就会长。
- 右键请求 →
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 Storage | Service 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/
动手顺序(每一步都能独立生效,不必一次做完):
npm create vite@latest起项目,git init并提交一次基线。- 装 Prettier,跑一次
--write,单独提交(这次提交只有格式改动,否则后面所有 diff 都不可读)。 - 装 ESLint +
typescript-eslint+eslint-config-prettier,npx eslint .跑到零 error。 - 打开
tsconfig.json的strict,修完类型错误。 - 装 Husky + lint-staged + commitlint,配好三个钩子。
- 写
ci.yml,在 GitHub 上把check设为 required status check。 - 接入错误监控 + Source Map 上传,并写一条能在测试环境触发的错误验证全链路。
- 补 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.jsonscripts,以及 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 之后的钩子写法也有变化。本篇的命令与配置以官方最新文档为准,落地前请对照官方文档确认当前版本语法。