企业官网建设流程全解析

简介：《前端开发规范手册》是一份面向互联网行业前端开发者与团队协作场景的标准化指南，围绕代码一致性与最佳实践展开，适用于希望提升代码质量、降低维护成本、改善多人协作效率的读者。手册系统覆盖HTML语义化与注释规范、CSS字体排印与BEM模块组织、JavaScript代码风格与jQuery最佳实践，并给出结构样式行为分离、统一缩进、UTF-8编码等基础约定，兼具指导性与实操性。资源为1个PDF文件，压缩包大小1.45MB，轻量易用，便于随时查阅与团队内部分享。目前已有196人学习下载，适合前端初学者建立规范意识，也适合团队作为内部培训参考。手册还包含性能优化（内联关键CSS、压缩合并、缓存利用）与移动端响应式设计、Autoprefixer等工具链建议，可直接对照落地，帮助开发者在实际项目中形成统一、可维护的前端工程基线。

1. 前端开发规范手册：不是摆设，是给团队的一劳永逸的后悔药

任何一个前端团队，只要超过三个人，就一定会遇到同一类问题：A写的代码缩进是两个空格，B写的代码缩进是四个空格；A说组件props要写注释，B说写了也没人看；A用CSS Modules，B用styled-components，C直接用全局类名。Code Review 的时候，一半时间不是在讨论逻辑，而是在争论风格。前端开发规范手册这种东西，看起来只是一份PDF，实际上是团队的技术宪法——它把“哪种写法是对的”这件事从口头争论变成了一纸文书，让新人在入职第一天就能对齐基线。

这本手册解决的不是某一个bug，而是“每一个bug”背后的混乱根源。它适合所有正在经历“代码越来越乱、评审越来越累、新人上手越来越慢”的开发团队。如果你一个人写项目，规范可以存在脑子里；但只要引入协作者，规范就需要从脑子里搬到纸上。问题从来不是要不要规范，而是规范怎么写得可执行、怎么让人愿意执行。这篇笔记就把我这些年整理前端开发规范手册的思路、结构和踩坑全部摆出来，照做即可。

2. 把规范拆成四层：风格、结构、工程、流程，PDF 才能从纸面落到代码

市面上能找到的很多前端规范文档，通病是“什么都写，什么都没写透”。CSS 写了一大章，TypeScript 只提了一句“用严格模式”；命名规范铺了一整页，Git 提交却一个字没提。用的时候才发现：该查的查不到，查到的不解决问题。我一般会把前端开发规范手册拆成四个独立层次来写，每一层对应不同的落地工具和审查方式，这样读者打开手册就知道去哪一章找答案。

2.1 风格层：格式化交给工具，不要用人工检查 style

代码风格（缩进、引号、分号、换行）是团队争吵最多的部分，但也是最不值得人工投入的部分。别说谁的空格更优雅——这种属于“编辑器玄学”，纯靠自觉一定有人漏。规范的第一层内容应该很薄：写明“代码风格由 Prettier 统一负责，禁止手工微调”，然后把.prettierrc的核心参数贴出来，作为唯一事实来源。

一个我长期使用且没引发过争议的配置基座是这样的：

{ "printWidth": 100, "tabWidth": 2, "semi": false, "singleQuote": true, "trailingComma": "all", "arrowParens": "always", "endOfLine": "lf" }

这一层的逻辑很简单：不需要在 PDF 里写“函数参数超过三个就换行”这种话，Prettier 会自动处理。规范手册只需要约定三个事情——使用 Prettier、使用这份配置、CI 里跑prettier --check。附上.prettierrc文件和命令行片段，让任何一个人都能在五分钟内把编辑器设成同一个效果。人工评审只关心逻辑，不关心空格，这是风格层最重要的定位。

2.2 结构层：组件与文件划分的约定，决定项目能否长期维护

风格之上是结构。组件的文件划分、目录职责界限、命名规则，这些决定了你加一个页面时到底要动多少个文件。结构层写不好，项目几天就会长成一坨千层饼。规范在这层要做的是“定边界”，不是“定写法”。

文件级结构通常是这么约定的：

• src/components只放可复用的基础/业务组件，不允许出现页面级逻辑
• src/pages或src/views按路由切页面，页面组件只做组装，不写复杂业务函数
• src/hooks放自定义 hook，命名一律use开头
• src/utils放纯函数工具，禁止引入react/vue等框架依赖

组件命名这里有个容易被忽略的细节——组件文件大小写规范必须和框架约定一致。React/Vue 的官方建议是 PascalCase，ESLint 的vue/component-name-in-template-casing规则也默认要求 PascalCase。如果项目里同时存在button.tsx和ButtonCard.tsx，说明规范没被执行，ESLint 也没配到位。这一层在 PDF 里要配一张表格：目录、允许放什么、禁止放什么、审查方式是什么。

2.3 工程层：构建配置、环境变量与第三方依赖的择优标准

工程层是前端开发规范手册里“最容易被跳过，实际影响最大”的部分。依赖管理、环境变量命名、构建配置基座，不在这里写清楚，项目没到三个月就会陷入“每个模块引入自己的祈祷”的窘境。比如 axios 封装，A 模块直接axios.get，B 模块自己包了一层拦截器，C 模块把fetch又引了一遍——代码评审看到这种分布头皮都发麻。

规范的做法是约定唯一请求入口，具体到文件：

// src/api/http.ts // 全项目唯一的 HTTP 客户端出口 // 业务代码禁止直接 import axios，只允许 import 此模块 import axios from 'axios' export const http = axios.create({ timeout: 15000, }) http.interceptors.request.use((config) => { // 统一注入 token 与 traceId return config }) http.interceptors.response.use( (response) => response.data, (error) => { // 统一错误提示与 401 重定向 return Promise.reject(error) }, )

工程层要写在 PDF 里的不只是这一段代码，而是背后的决策规则：什么情况下允许新增依赖（需要有替代方案对比、包体积评估、维护活跃度检查），什么情况下禁止再引一个库（能用原生 fetch 解决的，不允许引 axios 的二次封装等）。这样评审的时候遇到“新引入一个 npm 包”的 MR，你就有据可查：“先看规范第三章——新依赖要有理由、有对比、有体积记录”。

2.4 流程层：分支、提交、评审，Code Review 不靠自觉靠定义

流程层定义代码在进入主线之前经历什么。这一层写得越实，后面临时吵架越少。核心共识是三件事：分支模型、提交信息格式、MR/PR 的最小定义。

分支模型直接选行业最常见的一套，不要自创。main保护，feature/*开发，release/*发版，hotfix 走独立短分支。提交信息强制 conventional commits，这是唯一能让团队历史不必重写的方式，也是自动生成 changelog 的原材料。

提交规范的关键不是写出“写得好”的提交信息，而是把它变成不可绕过的关卡。这层需要的是一条命令，然后写进 husky 钩子：

{ "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS", "pre-commit": "lint-staged" } } }

配合.commitlintrc.json：

{ "extends": ["@commitlint/config-conventional"] }

流程层的 PDF 只需要一页内容配一条命令——因为剩下的都交给钩子执行了。

3. HTML 与 CSS 的规范细化：类名、层级与样式隔离的落地细则

绝大多数的前端规范手册都会在 CSS 部分写很多“样式必须使用变量”这种原则，然后整本手册里除了一个变量定义示例再没有别的。这样写是害人——读者看了标题以为知道了，进了项目依然无从下手。HTML 与 CSS 的规范需要非常具体：类名怎么取、作用域怎么划分、样式隔离机制选哪种，这些都得有可以被代码检查工具捕捉的约定。

3.1 类名命名方案：从 BEM 到有边界的语义化命名

类名命名是前端团队最耗精力的争论点之一。我给团队选型时，一般不直接上完整版 BEM，因为完整 BEM 在 React/Vue 组件化开发里显得冗长。更实用的是一个简化版 BEM（也常被称为“准BEM”），保留 Block-Element-Modifier 的关键语义，但不强制在标记里出现双下划线。

这套命名能不能被强制执行？不能完全靠 ESLint 自动查，但可以靠两条硬措施落地：一是 Code Review 时把“类名是否符合 BEM 规则”列为一票否决项；二是在开发时用一个简单的自定义规则脚本查非法字符（例如不允许出现驼峰类名、不允许元素名裸奔）。CSS-in-JS 项目的命名策略本质同理，只不过把类名的物理位置换成了组件名，规则核心依旧是对应关系可推导。

3.2 样式作用域：为什么必须放弃裸写全局样式

样式隔离不是“要用 CSS Modules 还是 styled-components”的问题，而是“在约定下写出来的代码，换到另一个组件里不会互相污染”的底线问题。纯全局样式表一旦超过 500 行，类名冲突是必然事件。规范在这块的选型逻辑我一般这样定：

• Vue 项目默认<style scoped>，附加lang="scss"，CSS Modules 按需启用
• React 项目默认 CSS Modules，*.module.scss文件命名；不用 styled-components，原因是为了保持设计走查时样式检索的直接性
• 全局样式只允许放 reset 与 CSS 变量，不允许在全局文件里写组件样式

一个重要边界要讲清楚：scoped 和 CSS Modules 都不是绝对隔离。:deep()（Vue）或:global()（CSS Modules）可以在子组件内部改变样式，所以规范里要约定：穿透样式只在 UI 库的覆盖场景下允许，且必须紧挨着对应组件书写，禁止在全局样式里做 UI 库主题深度覆写。

3.3 布局与响应式断点：把 Breakpoint 写死，比让每个开发者自由发挥强十倍

响应式最怕的不是断点不够，而是每个人写的断点值都不一样。A 用 768px，B 用 767px，C 用 576px——结果同一页面在不同宽度下出现三个完全不同的行为。规范里必须写死断点变量名与取值，以一种“谁都不许改”的姿态。

CSS 变量的写法：

:root { /* 响应式断点 —— 任何组件不允许私自定义新的断点 */ --breakpoint-sm: 576px; --breakpoint-md: 768px; --breakpoint-lg: 992px; --breakpoint-xl: 1200px; }

然后约定媒体查询的使用方式：在组件样式里必须使用断点变量（配合min-width/max-width的组合），禁止硬编码数值。这样后续调整断点时只需改一处全局变量，整个应用的响应式行为同步更新。做了这一步，全局搜@media就能快速发现谁在私自写死数值，评审效率提升明显。

3.4 状态类与样式优先级：避免用!important赌明天

!important在代码里出现的频次是团队健康度的一个信号。它不是完全不能用，但用之前你必须意识到一件事：它在告诉未来的维护者“我解决不了优先级问题，所以我直接掀桌子”。规范要明确禁止它作为常规手段，并给出替代路径。

常见替代方案：

同时在规范里补一条防微杜渐的规则：提交的代码里只要grep到!important，CI 直接报警。用一两行命令自动卡住，这条就再也不需要评审者肉眼看。

4. JavaScript 与 TypeScript 的部分：类型、状态、异步，规范要卡在编译器之前

JavaScript 规范是最容易写得又臭又长的部分。很多人会把“尽量用 const、不要用 var”“函数要有 JSDoc”这种话塞进去，但这些规范对团队效率的提升几乎为零。真正有效的 JS/TS 规范，要卡在三个点上：类型的覆盖度、状态管理的模式、异步操作的边界。核心逻辑是——人类能遵守的规则，工具必须能执行。

4.1 严格模式的非可选配置：TypeScript 的边界原则

任何有价值的前端开发规范手册，都不应该让 TypeScript 处于“开了但没完全开”的状态。strict: true是第一红线，但这里要给读者讲清楚为什么，而不是直接拍一行配置。

strict模式下最影响日常开发的是strictNullChecks。它强制你处理“这个值可能是 null”的情况，从而把一大类运行时空指针问题拖到编译期暴露。很多团队为了赶进度把strictNullChecks关掉，等于给 TS 这把枪卸了弹匣。规范里要写明：所有新项目必须strict: true；存量项目必须在两个迭代周期内平滑开启。同时附上一个临时过渡技巧——刚开严格模式时报错太多时，可用// @ts-nocheck做文件级临时豁免，但要留一条治理任务追踪，避免它变成永久的遮羞布。

下面是推荐配置模板：

{ "compilerOptions": { "strict": true, "noImplicitReturns": true, "noUnusedLocals": true, "noUnusedParameters": true, "noFallthroughCasesInSwitch": true, "forceConsistentCasingInFileNames": true } }

4.2 类型的最小隐含约定：不写 any 不等于不会写 any

规范里写“禁止 any”在实操中约等于屁话——因为总有场景你不知道怎么写类型。更有用的规范是给出“遇到类型难题时的处理阶梯”：从unknown收窄（type guard）、到interface定义最小结构、再到“不得不用 any 时必须写一行注释说明理由并挂上TODO”。

我一般推荐这个流程作为团队公开约定的部分，它由浅入深覆盖了几类场景：

// 1. 从接口数据返回时，优先定义响应 interface interface UserProfile { id: string name: string email: string } // 2. 对外部数据未知结构，先用 unknown 接收再收窄 const data: unknown = await response.json() // 3. 在无法完整收窄时，用自定义 type guard 代替直接断言 function isUserProfile(value: unknown): value is UserProfile { const item = value as Record<string, unknown> return typeof item?.id === 'string' }

这种写法在规范里体现的是“逼你在编译期做决定”，而不是“留到运行期让用户背锅”。另外约定一个申报机制：代码评审中发现新的 any，添加者要在评审描述里说明为什么逃过了这个阶梯。这个机制本身就能让 any 的滥用率大幅下降。

4.3 异步与副作用管理：Promise、事件与竞态边界

异步这块是前端翻车最密集的区域。规范要把“异步操作”的边界定义清楚：请求发出后组件卸载了怎么处理、竞态怎么防止、错误边界怎么兜。常见的坑是请求回来后发现组件已经卸载，React 里会直接报“Can't perform a React state update on an unmounted component”警告；Vue 里则表现为对已卸载实例赋值，新版 Vue 会静默失败，埋下更难排查的雷。

规范的推荐做法是用 AbortController 统一处理请求取消，代码层面这样约束：

// 组件内发起的异步操作，必须绑定可取消信号 // useEffect/onUnmounted 时取消未完成的请求 useEffect(() => { const controller = new AbortController() api.get('/list', { signal: controller.signal }) .then((data) => setData(data)) return () => controller.abort() }, [])

同时约好全局规则：异步数据流不允许直接用裸setTimeout模拟请求延时（应当用 mock 层）；多个并行请求用Promise.all保持统一错误处理；串行依赖请求必须用async/await，不写回调嵌套。这些条目不需要每个都解释原理，但需要在规范里占一页，原因是它们比 90% 的代码风格细节更能决定线上质量。

4.4 状态管理的选型原则：用最少工具解决 80% 的需求

前端状态管理在规范里不能写得像一篇选型论文，而要写“默认怎么选，什么时候必须换，换之前要过哪道闸”。默认约定是：组件内部状态用useState或 Vue 的ref；跨组件层级的状态用 Context/Provide-inject；状态体量达到多页面共享、存在复杂联动时要引入外部状态库。

规范在这里最重要的作用是防止状态管理工具泛滥。常见翻车现场是团队里有三个项目，一个用 Redux 一个用 MobX 一个用 Zustand——每个都有道理，但维护者来回切换时心态直接爆炸。所以规范要写死：新项目统一一个方案；老项目允许维持原状，但禁止在老项目里再引入另一种状态工具。同一仓库里出现两套状态库是可耻的，这条可以写进 Code Review 机器检查清单。

5. 把 PDF 变成执行力：规范落地的四个必配工具与三处高频翻车排查

手册写好了不代表规范落地了。太多团队把规范文档一传，然后半年后发现没人在看。前端开发规范手册的真正价值不在于“有手册”，而在于“手册里的每一个可自动化条目，都有工具在执行”。这一章写给带团队的人，也是整本手册里最关键的一章。

5.1 落地工具链：用 lint-staged 卡住提交前的最后一公里

纯靠 Code Review 让人遵守规范，等于让评审者兼职做编译器。规范化手册落地的核心思路是：能自动查的绝不人工看，把规范拆成自动检查和人工评审两层。自动检查层由 Husky + lint-staged 撑起来，这基本是当前前端工程的默认组合。

以 React + TS 项目为例，package.json中的约定可以这样配：

{ "lint-staged": { "src/**/*.{ts,tsx}": [ "eslint --fix", "prettier --write" ], "src/**/*.{scss,css}": [ "stylelint --fix", "prettier --write" ], "*.{json,md}": [ "prettier --write" ] } }

这套工具链的逻辑是：提交前只检查暂存区的文件改动，不把全量代码拖下水。每次提交都自动执行格式化与基础 lint，低级错误根本走不到评审人面前。CI 里再配一条eslint . && prettier --check .作为最后闸门，覆盖本地忘了装依赖或手动跳过 lint 的场景。

5.2 规范检查规则：三档约束保证不把团队逼疯

规范条目要有优先级，否则全是一票否决的情况下，团队会觉得动代码就要闯十道关卡，反面情绪会直接把规范逼成废纸。我一般将规则分为三档：

这样分档的意义在于给团队成员明确信号：哪些是不能触碰的底线，哪些是可以逐步改善的方向。全是一条条“必须”，等于没有“必须”。

5.3 避坑实录：规范落地最常见的三处翻车现场

现象一：lint-staged 明明配了，但 CI 还是一片红

原因大概率是 lint-staged 没有覆盖到新增文件类型，或者 CI 用的命令和本地不一致——最常见的是本地读.eslintrc，而 CI 上因为NODE_ENV不同导致 ESLint 走了不同的 parser 配置。

解决：把 CI 校验命令写进统一的 npm scripts，推荐做法是在package.json里定义"lint:ci": "eslint . && prettier --check ."，本地和 CI 执行同一条命令。另外在 lint-staged 里加上--no-stash参数，可以解决部分钩子执行时暂存区文件变形的问题。

现象二：规定了命名规则，但老代码满屏违反，新人不确定听谁的

这是每个写规范的人都会撞上的“历史包袱问题”。全量重构不现实，不清理又让新人以为规范是装饰品。

解决：规范要从“目标态”和“迁移态”两个视角来写，明确声明“存量代码允许逐步迁移，新增代码必须合规”。同时给历史目录挂一条例外路由，例如在 ESLint 配置里用overrides对src/legacy/**做降级检查，等该目录代码变动超过 70% 后再摘除豁免。这比一句“以后都按规范走”可靠得多。

现象三：stylelint 一直没接进构建链路，样式规范全靠自觉

CSS 类名、属性顺序、颜色格式等规则如果没有工具把关，最终必然演变成每个组件一套手感。常见情况是stylelint装了，但没有配置stylelint-config-standard，也没有接入 lint-staged。

解决：stylelint在规范里的优先级要跟 ESLint 同等。给出最简配置：

{ "extends": ["stylelint-config-standard"], "rules": { "declaration-block-no-duplicate-properties": true, "color-named": "never", "unit-blacklist": ["px"] } }

unit-blacklist处理的是主题化场景中禁止新写死 px 的问题；如果项目里不是全面主题化，这条可以不加。但 stylelint 本身必须接入，否则前端开发规范手册里的 CSS 章节就是无牙老虎。

5.4 规范文档版本化：手册也要跟着代码演进

一个容易忽略的执行细节是版本管理。把前端开发规范手册.pdf放在共享网盘里，是“永远没人知道现在用的是哪一版”的开始。规范应该有明确的版本号，并且跟随仓库生命周期迭代。

常见的做法是在仓库根目录放一个docs/standards/目录，按年份和重大变更打版本标签。配合 CHANGELOG，任何人打开手册第一眼看到“变更记录”，就知道这份规范还活没活着。否则一旦遇到争议，双方各拿各的 PDF 版本互杠，又回到没有规范的状态。

6. 增量治理：规范手册要像代码一样做 Code Review

最后一章的价值观是——规范不是写出来的，是一轮一轮改出来的。前端技术栈演进快，规范手册如果三年不动，里面三分之一的条目就过时了。我给团队的约定是：每个季度拿出半天做规范评审，像评审代码一样评审手册本身。

评审的重点不是文笔，而是三个问题：哪些条目已经没有代码支撑（例如项目已经不用 jQuery 了，但规范还在禁止 jQuery 插件）；哪些高频重复问题还没写进规范（可以从前一个季度的 Code Review 记录里搜高频词）；哪些工具链升级让旧规则变得多余（比如全面上了 TypeScript 后，“必须写 JSDoc”的规则就可以删掉）。每次修订都对应一个 commit，提交信息写清楚变更原因。这样规范手册本身就变成了一个有提交历史的项目，而不是一份孤零零的 PDF。

这种做法的副作用很直接：团队不会再把规范当成外部强加的条条框框，而是把它当作一个“有生命的文档”。我自己带团队的教训是——规范最怕的不是不完善，而是没人认领。只要有一个负责人（通常是前端 lead 或资深前端）定期推动它的更新和执行，这份 PDF 才能真正成为项目里的资产。希望帮到你。

本文还有配套的精品资源，点击获取