简介《前端工程师手册》是一份面向初中级前端开发者的系统知识合集内容由浅入深覆盖HTML/CSS基础语义化、盒模型、定位、浮动、常见布局、JavaScript核心作用域、闭包、原型继承、事件机制以及进阶话题Promise、异步流程控制、设计模式、模块化管理并延伸至jQuery源码、前端自动化、SPA、动画、性能优化、移动端H5优化和面试题集锦基本勾勒出前端工程师日常所需的知识版图。资源为1个PDF文件体积5.06MB便于阅读和检索目前已获266人浏览学习。文档目录组织清晰附录还提供图书和视频教程参考适合系统复习或按需查阅尤其对接手复杂页面布局、异步编程与前端工程化的读者有直接帮助。1. 前端工程师手册.pdf把散落的知识收敛成一份可交付基线带新人的时候我踩过一个很深的坑给他开了十几篇资料他看完印象模糊遇到问题还是回来问。反过来一份 80 页的《前端工程师手册.pdf》丢给他他能在需要时定位到那一页然后带着问题来找我讨论而不是等我从零讲。所以这个标题真正在讲的不只是一份文档而是一种工作习惯把散在收藏夹里的链接、群里随口讲的原理、每次排查问题的结论收敛成一份能交付、能检索、能长期维护的知识基线。它解决的是「不是没资料而是资料太多、无法形成判断」的问题。适合三类人要带新人、又被重复问题缠身的前端小组负责人准备做知识复盘的资深开发想把一年经验整理成体系的进阶工程师。接下来我会按「骨架 → 构建 → 交付 → 避坑 → 验证」这条路径把做这份手册的完整过程讲清楚。2. 先立骨架前端工程师手册的章节怎么定才不会落灰很多人做手册第一步就错了按技术栈列目录HTML、CSS、JavaScript、React、工程化各开一章。这样写出来像工具书三个月后没人翻因为读者遇到问题时不会说「这是个 React 问题」他会说「页面为什么加载这么慢」。所以手册的目录应该模拟人脑的检索方式按问题域组织而不是按 API 组织。下面这套方法是我带过几届前端之后沉淀下来的。2.1 用「问题域」而不是「技术栈」搭章节骨架做法很简单先写问题再分章节。找个下午把近三个月团队里被问过的问题、你自己排查过的问题全部写成一页纸每个问题只写一行不要分类。写完之后拿出一版候选章节把每个问题归进去。候选章节不需要一次到位我手头这版长期没动过浏览器原理、语言与运行时、工程化与构建、性能优化、安全与网络、团队协作与规范。归类时你会发现几个规律。按技术栈列目录时「性能」没有家但按问题域列目录时它排在前面。归类不进去的行要么是收藏夹凑数的冷门问题要么说明缺一个章节。冷门问题直接删缺章节就补。这张问题清单最后丢进仓库作为下一版手册的选题池。下面是我第一次跑这个动作时的部分归类结果结构上给你做个参照| 被问过的问题 | 归入章节 | 是否高频 | | 页面加载慢白屏好几秒 | 性能优化 | 是 | | 上线后样式还是旧的清缓存没用 | 工程化与构建 | 是 | | 接口报跨域前后端各执一词 | 安全与网络 | 是 | | 正则写得太复杂没人看得懂 | 语言与运行时 | 是 | | 组件拆太碎状态改一处崩一片 | 语言与运行时 | 否降优先级 |注意表格里的「否降优先级」这行说明归类不只是分桶还要做一次价值排序。高频问题进正文章节低频问题先挂到章节末尾的「待整理」区不删除但也不给篇幅。这样第一版手册的体量能控制在团队愿意读完的范围而不是变成一部几百页的百科全书。补充一个颗粒度判断一个章节预计超过 20 页说明颗粒度太大拆不足 3 页先合并到相近章节等长起来再独立。这条规则帮我砍掉过「CSS 杂谈」这种注定写不满的章节。2.2 每章统一一套模板目标、概念、示例、检查清单章节骨架定了下一个问题是每章写出来的样子。不同人写章节风格差异极大有人写成教程有人写成笔记新人在同一本手册里同时看到两种标准他会不知道该信哪种。我的做法是给每一章套同一个五段式模板本章目标、核心概念、可运行示例、检查清单、参考占位。模板写成 Markdown 放在手册仓库里新章节复制后改内容格式不允许换。!-- 章节模板新章节复制这份骨架后再填内容 -- ## 章节编号浏览器如何把 URL 变成页面 本章目标读完能用 5 分钟讲清一次完整导航过程。 适用对象前端新人排障时需要定位是哪一段出问题。 ### 核心概念 - 导航从输入 URL 到请求发出前发生了什么 - 渲染HTML、CSS、JavaScript 的解析与合成 ### 可运行示例 放一段最小演示代码能本地直接跑。 ### 检查清单 - [ ] 我能说出必经的 6 个阶段 - [ ] 我能指出卡住时看哪个面板 ### 参考占位 每章最多 5 条写标题与来源不写收藏夹链接。这个模板的核心理念是「可核对」。检查清单让读者自己判断是否掌握而不是读完就走。- [ ]这种 Markdown 任务列表不是摆设将来可以用脚本统计哪些章节长期处于未完成状态据此判断是内容没写透还是读者根本不关心这部分。导出 PDF 时我建议保留未完成项让读者看到手册的边界比假装什么都覆盖了更诚实。参数说明其实没几个关键是「参考占位」只写标题和来源不放链接。链接会被分享得乱七八糟标题却能在团队内部形成统一指代你说「浏览器那章的参考 3」所有人都知道是哪条。PDF 里这些占位短小不会打乱版面。2.3 章节骨架示例与内容份额决策表把上面的规则落成一张章节决策表就长这样| 章节 | 核心问题 | 第一版篇幅建议 | 交付物 | | 01 浏览器原理 | 从输入 URL 到页面显示经历了什么 | 812 页 | 阶段流程图 排查点表 | | 02 语言与运行时 | this、闭包、事件循环这些卡壳点 | 1015 页 | 概念卡片 最小示例 | | 03 工程化与构建 | 依赖、缓存、打包、部署的高频坑 | 1218 页 | 命令速查 配置样例 | | 04 性能优化 | 加载慢和交互卡分别怎么定位 | 1015 页 | 检查清单 指标表 | | 05 安全与网络 | 跨域、XSS、CSRF、鉴权怎么兜底 | 610 页 | 风险清单 处理步骤 | | 06 团队协作与规范 | 代码评审看什么、发布怎么避险 | 48 页 | 评审清单 |我一般建议第一版只做 01、02、03 三个章节04 到 06 靠检查清单先撑住。原因很现实新人第一个月被问住的基本集中在浏览器、运行时和工程化安全与协作属于「出事了才看」的章节可以等手册被用起来之后再补。这张表同时是排期表每个迭代从表里拎一个章节升级到正式内容版本页上记录升级时间。骨架定稿前还有最后一道工序拿给团队里的 A同学看请他提出「最想找但目录里没有的问题」把这些问题回填到表里。这个动作不要省骨架是给人检索用的只有真正要被检索的人参与过目录才长在他们的思维习惯上。骨架定稿后下一步就可以开始写了怎么组织源文件怎么用一条命令把 Markdown 变成可以交付的 PDF放到下一章讲。3. 从 Markdown 到 PDF一行命令产出手册的构建方法骨架定了以后要解决的是「用什么格式写、怎么变成 PDF」。我见到的常见做法是源文件用 Markdown转换走命令行最后落成一个 PDF 文件。这样做的直接好处是 git 能 diff。改了一个字提交记录里能看出改的是哪一行换成 Word 或在线文档diff 要靠人眼对着两份文件找早晚翻车。3.1 为什么源文件用 Markdown转换命令走命令行选型理由排序第一纯文本能进版本管理能回滚第二构建可重复任何人拿到仓库都能产出同一份 PDF第三不依赖某个具体排版软件的许可或在线状态。在线文档导出 PDF 样式不受控同一份文档在不同浏览器里另存结果不一样目录和书签还经常丢掉。如果团队里已经有人用在线文档写手册迁移成本是真实存在的我通常建议不要一次迁移而是从下一版开始用新格式写旧章节按需移植。下面这张取舍表供你判断自己的路线| 转换路线 | 适合场景 | 主要缺点 | | 先转 HTML 再转 PDF | 需要精细控制样式输出固定模板 | 配置项多中文字体要显式指定 | | 直接用 Markdown 转 PDF | 快速出初稿、内部评审 | 书签和页眉页脚支持较弱 | | 文档站点渲染后导出 PDF | 手册长期维护需要全文检索 | 引入额外框架维护成本高 |我个人走第一行Markdown 先转 HTML再用能识别 CSS 的引擎出 PDF。原因只有一个CSS 里能写分页规则这是「书签、页码、避免代码块跨页」这些交付质量的基础。3.2 最小构建脚本从多个 Markdown 合成一份 PDF目录结构固定成manual/一个文件夹assets/manual.css管样式dist/管输出。构建脚本放在仓库根目录每次发布只跑它。#!/usr/bin/env bash # 从 manual/ 目录的多个 Markdown 合成一份带书签的 PDF # 用法进入手册仓库根目录执行 bash build-manual.sh cd $(dirname $0) mkdir -p dist pandoc \ --from markdown \ --to html5 \ --standalone \ --toc \ --toc-depth2 \ --number-sections \ --metadata title前端工程师手册 \ --metadata langzh-CN \ --cssassets/manual.css \ manual/00-intro.md \ manual/01-browser.md \ manual/02-runtime.md \ manual/03-engineering.md \ manual/04-performance.md \ manual/05-security.md \ manual/06-collaboration.md \ -o dist/前端工程师手册.pdf这段命令可以拆成三部分看输入是 manual 目录下按编号排列的 Markdown 文件转换参数控制目录、编号、元数据和样式输出是 dist 目录下的 PDF。--standalone表示生成完整的 HTML 文档而不是片段缺少它CSS 可能不会进入最终文档。--metadata title会把标题写进 PDF 元数据没有这个字段时阅读器标题栏显示的是第一个源文件名很难看。参数表如下| 参数 | 作用 | 建议值 | |--toc| 生成目录页 | 固定开 | |--toc-depth2| 目录只收两级标题 | 2三级标题让目录溢出 | |--number-sections| 自动给章节编号 | 固定开 | |--metadata langzh-CN| 声明文档语言 | zh-CN | |--css| 指定打印样式 | 路径指向 assets/manual.css |构建失败时先看 stderr不要整篇重排。报字体相关错误先跑fc-list :langzh确认系统里有没有中文字体报文件路径错误检查 manual 目录下的文件名是否和命令一致。还有一类失败是脚本执行完、PDF 也生成了但书签是空的那多半是--toc没生效或者源文件标题层级不规范放到避坑章节细说。3.3 参数调法的实际影响目录深度、章节编号与文档元数据有同事问过我--toc-depth到底设 2 还是 3。我的判断是目录页是给「找人」用的不是给「读」的收两级标题足够第三级标题留在 PDF 书签面板里阅读时随时可以展开。如果团队里有人习惯从目录判断手册覆盖面可以备一份内部评审版把--toc-depth改成 3对外发布版保持 2。两个版本用同一个源只是参数不同不值得为这个维护两份内容。--number-sections开了之后正文标题和目录里的编号由工具统一生成章节移动时不用手工改编号。注意如果源文件标题里已经手写了「1.1」「1.2」就不要再开自动编号否则会出现「1.1 1.1」这种重复。langzh-CN这个元数据容易被忽略。它影响阅读器的语言识别、拼写检查也影响某些阅读器的朗读发音更重要的是部分 PDF 提取工具依赖它做中文文本层的正确处理。虽然只多一行我建议默认写上。3.4 源文件命名与 front matter 约定文件名用NN-英文短名.md比如01-browser.md。两个数字保证合并顺序稳定中文文件名在某些命令行环境里排序不可预期容易打乱章节。每章开头写三行 front matter 性质的字段status、updated、owner。status取draft或done构建脚本可以据此决定是否把章节收进正式版。# 只把 status 为 done 的章节拼进构建列表 for f in manual/[0-9][0-9]-*.md; do if grep -q ^status: done $f; then echo $f fi done这段脚本的思路是遍历 manual 目录下所有编号开头的 Markdown用 grep 检查每章开头有没有status: done有才输出。输出的文件列表交给合章命令使用。逻辑说明[0-9][0-9]匹配两位数字前缀避免把模板文件或 README 扫进去grep -q只返回匹配结果不打印内容。这样草稿章节不会混进正式 PDF同时保留在仓库里继续改不会丢。参数调整如果你希望把草稿章节作为附录打出来把判断反过来单独拼一个「附录列表」即可。4. 让 PDF 像正经手册书签、页眉页脚、版本页怎么落地命令能出 PDF 只是第一步。手册和一堆打印纸的区别在书签、页码、版本页。没有书签的 PDF 翻起来像扫描件没有版本页的手册改了三版之后没人知道手上是哪版。这一章把交付质量的三件事讲清楚书签层级怎么来、版本页怎么放、页眉页脚怎么控制。4.1 书签层级靠标题结构自动映射 PDF 大纲PDF 的书签不是手绘的它来自源文件的标题层级H1 映射成一级书签H2 映射成二级书签以此类推。所以写源文件时的标题纪律直接决定交付的作品质量。最常见的坏习惯是跳级H1 下面直接出现 H3书签面板里就出现一个大目录项下面挂着孙级中间少一层观感混乱也不利于快速定位。手动检查太容易漏我在构建前跑一个小脚本扫一遍#!/usr/bin/env python3 # 检查 Markdown 标题是否跳级生成 PDF 前兜底 import re import sys last 0 for line in sys.stdin: m re.match(r^(#{1,6})\s, line) if not m: continue level len(m.group(1)) if last and level last 1: print(f跳级警告: {line.strip()} (前一层级 {last})) last level逻辑说明逐行读 Markdown用正则匹配行首的#个数作为标题层级只要当前层级比上一次记录的层级深超过 1就输出警告。last保存上一次标题的层级level last 1是跳级的判定条件。跑法是把章节文件喂进 stdin比如python3 check-heading.py manual/01-browser.md。注意这个脚本针对单文件跨文件时每个文件的第一个 H1 都是 1符合多章合成的期望。书签做没做对验证方式是打开 PDF 的大纲面板看两级结构是否完整再抽查一个三级标题能否在书签树里展开。这一步不要跳过我看过太多「目录页排得漂亮、书签面板空空如也」的 PDF问题通常出在转换引擎默认不生成书签需要手动开启对应选项。4.2 版本页与变更记录让手册能追溯手册封面之后、目录之前放一页「版本与更新记录」。这是一份要持续更新的清单不是做样子。我用的表格精简成五列够用也不用维护太多| 版本 | 日期 | 变更摘要 | 变更人 | 影响章节 | | V1.0 | 2024-11-01 | 初版发布 | 某开发者 | 全部 | | V1.1 | 2024-11-15 | 补充跨域处理步骤 | A同学 | 05 安全与网络 | | V1.2 | 2024-12-01 | 重构性能章节检查清单 | 某开发者 | 04 性能优化 |版本号约定V 年份 月 序号比如 V1.2 指的是本年度第二个小版本。为什么不用 V2、V3 这种看似简单的编号因为 V 后面跟序号时升级语义容易膨胀大家会为「这个改动算 2.0 还是 1.1」争论按年月排正文里提到「V1.2 改了性能清单」时所有人都知道前后顺序和大致时间。版本页放在封面后还有一层原因PDF 被打印、被转发之后版本页是最先被看到的信息层。读者拿到文件先翻版本页确认自己看的是最新版如果这条信息缺失他只能靠文件名的副本编号猜那就伤了信任。实操细节建议在版本页放一条 git 短哈希。构建脚本里加一行git rev-parse --short HEAD把输出填进版本页对应字段。排查问题时把 PDF 里的哈希和 git log 对照能立刻知道这份手册来自哪次提交是不是混进了未发布的改动。4.3 页眉页脚与打印样式用 CSS 控制 PDF 的皮相页眉页脚在 Markdown 源文件里没法写它是 PDF 的皮相由打印样式控制。我维护的assets/manual.css只放和打印相关的规则平时预览页面完全不引用这份样式。/* assets/manual.css控制打印输出样式 */ page { size: A4; margin: 2cm 1.8cm 2.2cm 1.8cm; top-center { content: 前端工程师手册; } bottom-center { content: 第 counter(page) 页 / 共 counter(pages) 页; } } pre { page-break-inside: avoid; background: #f5f5f5; padding: 0.8em; } table { border-collapse: collapse; } td, th { border: 1px solid #ddd; padding: 0.4em 0.6em; }逻辑说明page块定义打印页面size: A4指定纸张margin控制四边留白top-center和bottom-center是运行页眉与页脚counter(page)是当前页counter(pages)是总页数。pre的page-break-inside: avoid让代码块尽量不跨页表格的边框样式让章节决策表这类表格在打印时整齐一点。参数注意page里的 margin boxes 不是所有渲染引擎都支持。有的引擎只认margin直接忽略top-center而且不会报错。所以导出之后要翻一页确认页眉页脚真的出现没出现要么换引擎要么接受「无页眉页脚」作为内部评审版对外交付版另行处理。中文字体也在这份 CSS 里指定写法是font-family指到本机已安装的 CJK 字体具体怎么排查放下一章。5. 生成手册 PDF 的避坑清单五个最容易翻车的现场从需求到交付翻车点集中在书签、字体、分页和版本管理。每一处都像玄学配置明明写了输出却没有视觉上正常复制出来却是乱码。下面按「现象 → 原因 → 解决」写五条都是我实际栽过、也帮同事填过的坑。5.1 书签与目录中文乱码、目录点不动现象 1PDF 打开后书签面板里中文标题全部变成方框或空白正文看着正常。原因书签文本生成时没有使用支持中文的字体或者字体未嵌入阅读器只能拿本地字体硬渲染。解决构建前先跑fc-list :langzh确认系统里有可用的 CJK 字体在打印样式里显式指定该字体让转换引擎在生成书签时也使用它。生成后再到书签面板抽查三个章节标题别只看目录页。中文字体缺失还有一副面孔本机打开正常把 PDF 发给别人那边打开中文全是方块而正文排版完全不乱。这多半是字体没有嵌入 PDF只在本机字体库里找到了对应关系。判断嵌入是否成功有一个不用装工具的办法一本 80 页纯文字手册正常嵌入中文字体的 PDF 体积通常会在几 MB 上下如果只有一两百 KB字体大概率没有进去需要去生成引擎里找字体嵌入选项。提示书签面板里能展开几层决定了这份 PDF 能不能当手册用。生成后先数层级再决定要不要对外发。现象 2目录页里每个条目都显示正常但点它不跳转。原因转换产物只保留了目录文本没有生成链接注解常见于先转图片再合成 PDF 的路线或某些简化导出工具默认关闭内部链接。解决换用支持链接的 HTML 到 PDF 引擎生成后点击目录里任意三条验证跳转。点不动就重跑构建不要手工给目录补链接——手工补的版本在下次构建时又会被覆盖等于白干。5.2 分页与字体代码块被切断、能看不能搜现象 3一个代码块正好落在页尾被硬生生劈成两半上半页一两行下半页剩半段。原因默认分页规则按行切块级元素没有保留整体性。解决在打印样式里给pre加page-break-inside: avoid第 4 章的 CSS 里已经有这一条。如果代码块实在太长不要硬撑主动拆成两段每段开头加一行注释说明这一段在做什么。这样即使分页断在注释附近读者也知道这一块属于哪个主题。这个现象还有个变种表格跨页时第二页没有表头读者不知道每列是什么。解决方式是给表格头设置跨页重复或者干脆在表格前加一句「下表列含义以首行为准」。分页控制不是只调page-break-inside一个属性凡是可能跨页的元素都要过一遍。现象 4PDF 的中文能看见但选中复制出来是乱码全文搜索也搜不到某个词。原因嵌入的字体没有携带完整的字符映射表阅读器只知道字形不知道字符编码严格说这份 PDF 的文本层是坏掉的本质上是「图像式文本」。解决生成后用命令行工具把文本提取出来验证。搜索一段确定存在的中文搜不到就换字体和引擎组合不要只看视觉正常就交付。这个坑最隐蔽因为它不影响阅读只影响检索而检索恰恰是手册的核心价值。5.3 版本与流水线交付旧文件是最隐蔽的坑现象 5手册里「上次说好的改动」一直没出现版本页明明写着 V1.2内容却还是 V1.1。原因改的是 Markdown没有重跑构建或者跑完脚本输出被写到了别的目录团队拿到的还是旧文件。PDF 文件名没变光看文件名无法分辨。解决把构建脚本定为唯一交付入口约定「发布 重跑脚本 版本页加一行 提交代码」。生成后看版本页里的短哈希用git log --oneline对照确认这份 PDF 来自最新提交。这个动作十秒钟做完但能挡住团队里大部分「更新了但没人看到」的抱怨。最后一个提醒前述所有坑最好的排查手段不是在阅读器里肉眼验证而是把「解压文本、搜索关键词、检查大纲层级」固化成一个验证脚本塞进构建流水线的末尾。实现不复杂但能把人工抽查从「偶尔做」变成「每次做」这条我放在下一章细说。6. 让手册活起来用提问驱动验证手册的每一章6.1 用「十五分钟检索」验证手册手册交付的第一天不要先看「读得懂看不懂」先测检索。给 A同学 5 个真实问题比如「为什么线上样式还是旧的」「跨域到底怎么解决」让他在 PDF 里找答案单题不超过 15 分钟。计时结果就是手册的体检报告3 分钟找到说明章节命名和目录命中找不到说明章节口径和实际提问不匹配。把失败题目收集成下个迭代的候选章节比拍脑袋猜「读者会想看什么」可靠得多。这个验证方法有个前提问题必须来自真实工作而不是从目录里倒推出来的。从目录倒推的问题答案当然在目录里测不出检索死角。我会提前一周让团队把「被问过但一时答不上来」的问题丢进一个共享文档测试当天直接从中抽题这样每一题背后都站着一次真实求助。6.2 把 PDF 当作评审基线手册成型之后我的习惯是每周做一次 diff review不重读全篇只看这周的增删顺便把版本号更新。手册也会跟着发布流水线走——每次版本发布构建脚本重新产出 PDF版本页自动追加一行。这样手册不是「写完了放那」而是持续维护的产品。提醒一句别把「持续更新」做成「频繁重写」。稳定比新鲜重要一周一版以内可以一天一版只会让团队不再读它。我早年的做法是收藏夹里存几百个链接自认为知识在手上后来发现链接会失效收藏夹也不会主动告诉我哪些过期了。把知识收敛进一份带版本、带书签、能搜索的 PDF 之后团队里新同学第一次独立排查问题真的会去翻手册而不是问我那个瞬间我觉得这份格式选对了。希望这些做法能帮到你。本文还有配套的精品资源点击获取