前端开发规范

前端开发规范，涵盖代码细节、工程化、协作流程等维度，结合实际场景补充具体规则和示例。

一、HTML 规范

1. 文档结构与元信息

DOCTYPE 与命名空间 ：必须以 <!DOCTYPE html> 开头，html 标签需指定 lang（如 zh-CN 对应中文，en 对应英文），避免 xmlns 等冗余命名空间（HTML5 已废弃）。
HTML 复制代码
```
<!DOCTYPE html>
<html lang="zh-CN"> 

```

head 标签顺序 ：按「关键优先级」排序：meta charset（必须首行，避免乱码）→ title → meta:viewport → meta（SEO/安全相关）→ link（样式）→ script（异步脚本放底部）。

HTML 复制代码

<head>
<meta charset="UTF-8">
<title>首页 - 某某平台</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<meta name="keywords" content="前端, 规范">
<meta name="description" content="详细的前端开发规范文档">
<meta http-equiv="X-UA-Compatible" content="IE=edge"> <!-- 兼容IE -->
<link rel="stylesheet" href="base.css">
</head>

2. 语义化深度规范

细分标签使用场景：
- <figure> + <figcaption>：包裹图片/图表+说明（如 figure > img + figcaption）；
- <time>：标记时间（需加 datetime 属性，如 <time datetime="2025-11-08">2025年11月8日</time>）；
- <address>：标记联系信息（仅用于页面作者/机构联系方式）；
- <dialog>：标记对话框（配合 open 属性控制显示，如 <dialog open>确认删除？</dialog>）。

表单语义化：

用 <fieldset> 包裹关联表单元素，<legend> 描述分组标题；
label 必须通过 for 与 input 的 id 关联（或直接包裹 input），提升点击区域；
优先使用语义化输入类型（type="email"/tel/number），而非通用 text。

HTML 复制代码

<form>
    <fieldset>
    <legend>用户信息</legend>
    <div>
      <label for="username">用户名：</label>
      <input type="text" id="username" name="username">
    </div>
    <div>
      <label>
        <input type="checkbox" name="agree"> 同意协议
      </label>
    </div>
    </fieldset>
</form>

3. 性能与兼容性

避免冗余标签 ：不嵌套无意义的父级（如 <div><span>文本</span></div> 可简化为 <span>文本</span>，除非有样式需求）。
图片优化：
- 必加 width/height 属性（避免布局偏移 CLS）；
- 优先使用 webp 格式，配合 picture 标签做降级：
  HTML 复制代码
```
<picture>
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="示例图" width="200" height="150">
</picture>
```

二、CSS/SCSS 规范

1. 命名体系（BEM 扩展）

命名空间：在 BEM 基础上增加前缀，区分组件类型：
- c-：通用组件（c-button、c-card）；
- m-：模块（m-header、m-footer）；
- u-：工具类（u-mt10 即 margin-top:10px）；
- is-/has-：状态（is-active、has-error）。示例：c-button__icon--large（组件-按钮的图标元素-大尺寸修饰符）。
禁止样式污染 ：页面级样式需加页面前缀（如 page-home__title），避免影响全局；组件样式通过 CSS Modules 或 scoped（Vue）隔离。

2. 选择器与权重

权重优先级 ：禁止使用「标签+ID」（div#box）或「多层类嵌套」（.a .b .c .d），权重控制在 (0,2,0) 以内（即最多 2 个类选择器，如 .a.b 或 .a .b）。
伪类/伪元素使用：
- 伪类（:hover/:focus）用于状态，伪元素（::before/::after）用于装饰性内容（需加 content: ''）；
- 必写 :focus 样式（无障碍要求，如 outline: 2px solid #165DFF）。

3. SCSS 语法规范

嵌套限制：最多嵌套 2 层（避免编译后生成冗余选择器）：

SCSS 复制代码

.c-card {
    padding: 16px;
    &__title { // 1层嵌套
        font-size: 18px;
        &--bold { // 2层嵌套（允许）
        font-weight: bold;
        }
    }
    // &__content .item { 错误（3层嵌套） }
}

变量与混合宏：
- 全局变量集中管理（如 _variables.scss 定义 $color-primary: #165DFF）；
- 重复逻辑用 @mixin（带参数），而非复制代码：
  SCSS 复制代码
```
@mixin flex-center {
    display: flex;
    justify-content: center;
    align-items: center;
}
.c-button { @include flex-center; }
```

4. 响应式与适配

断点规范：统一使用移动优先策略，断点命名与值：

SCSS 复制代码

// 从小到大：xs(手机) → sm(平板) → md(小屏桌面) → lg(大屏桌面)
$breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 1200px
);
@media (min-width: map-get($breakpoints, md)) { /\* 中等屏幕样式 \*/ }

单位使用：
- 布局尺寸用 rem（根字体默认 16px，1rem=16px）或 vw（移动端）；
- 内边距/边框用 px（避免缩放模糊）；
- 字体大小用 rem（便于全局调整）。

三、JavaScript/TypeScript 规范（增强版）

1. 变量与类型

类型约束 ：优先使用 TypeScript，明确变量类型（避免 any）：

TypeScript 复制代码

// 正确：指定类型
const username: string = '张三';
const userList: User\[] = \[{ id: 1, name: '张三' }];

// 错误：隐式any
// const data = fetchData(); // 应改为 const data: Data = fetchData();

对象/数组声明：
- 用字面量声明（const obj = {} 而非 new Object()）；
- 数组初始化指定类型（const arr: number[] = [] 而非 []）；
- 禁止修改原数组/对象（用 map/filter 替代 for 循环修改，用扩展运算符复制：const newObj = { ...obj }）。

2. 函数设计

参数规范：

最多 3 个参数（超过用对象聚合）：

JavaScript 复制代码

// 正确
function getUser({ id, name, age }) { /\* ... \*/ }
getUser({ id: 1, name: '张三' });

// 错误（参数过多）
// function getUser(id, name, age, gender, address) { ... }

必传参数放前，可选参数放后，可选参数用 ? 标记（TS）。

返回值：
- 函数必须有返回值（无意义返回 void）；
- 异步函数必须返回 Promise，且明确 resolve/reject 类型。

3. 异步处理

错误捕获：

async/await 必须用 try/catch 包裹（或用统一错误处理函数）；

Promise 链式调用必须加 catch，禁止丢失错误：

JavaScript 复制代码

// 正确
async function fetchData() {
    try {
        const res = await axios.get('/api/data');
        return res.data;
    } catch (err) {
        console.error('请求失败：', err);
        throw err; // 向上传递错误
    }
}

// 错误（未捕获错误）
// axios.get('/api/data').then(res => res.data);

并发控制：
- 并行请求用 Promise.all（全部成功）或 Promise.allSettled（允许部分失败）；
- 限制并发数（如用 p-limit 库，避免请求风暴）。

4. 模块化与依赖

导入导出：
- 优先用 export default 导出单个组件/类，export 导出工具函数集合；
- 导入路径：相对路径用 ./（同目录）、../（父目录），绝对路径配置别名（如 @/utils 指向 src/utils）；
- 禁止循环依赖（A 依赖 B，B 依赖 A）。
依赖管理：
- 第三方库优先用 peerDependencies（如 UI 组件库），避免重复安装；
- 工具函数优先封装到 utils，避免重复代码（如 formatDate、deepClone）。

四、工程化与工具链（增强版）

1. ESLint + Prettier 配置

核心规则 （.eslintrc.js）：

JavaScript 复制代码

module.exports = {
    extends: [
        'eslint:recommended',
        'plugin:react/recommended', // React项目
        'plugin:vue/vue3-essential', // Vue项目
        'prettier' // 关闭与Prettier冲突的规则
    ],
    rules: {
        'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn', // 生产环境禁止console
        'no-unused-vars': ['error', { vars: 'all', args: 'after-used' }], // 禁止未使用的变量
        'indent': ['error', 2, { SwitchCase: 1 }], // 缩进2空格
        'quotes': ['error', 'single'], // 单引号
        'semi': ['error', 'always'] // 强制分号
    }
};

Prettier 配置 （.prettierrc）：

JSON 复制代码

{
    "printWidth": 100, // 每行最多100字符
    "tabWidth": 2, // 制表符宽度2
    "singleQuote": true, // 单引号
    "trailingComma": "all", // 末尾逗号（如数组最后一项）
    "arrowParens": "always" // 箭头函数参数必加括号（(x) => x）
}

2. Git 工作流与提交规范

分支策略（Git Flow 简化版）：
- main：生产环境代码，禁止直接提交；
- develop：开发主分支，从 main 创建，用于集成功能；
- feature/xxx：功能分支（从 develop 创建，完成后合并回 develop）；
- fix/xxx：修复分支（从 develop 创建，修复后合并回 develop）；
- release/v1.0.0：发布分支（从 develop 创建，测试通过后合并到 main 和 develop）。

提交信息增强 ：除基础 type(scope): desc 外，复杂提交需加「详细描述」和「关联issue」：

Plain 复制代码

feat(login): 支持手机号验证码登录
*   新增验证码输入框组件

*   集成短信发送API

*   优化登录状态校验逻辑

Close #123（关闭issue 123）

3. 构建与部署

构建优化：
- 代码分割（splitChunks 提取公共库，如 react、vue）；
- 树摇（tree-shaking 移除未使用代码，需 ES 模块）；
- 图片压缩（image-webpack-loader）、CSS 提取（mini-css-extract-plugin）。

环境区分 ：配置 env.development/env.production/env.test，区分 API 地址、日志级别等：

JavaScript 复制代码

// 开发环境
VITE\_API\_BASE\_URL = '/api' // 本地代理
// 生产环境
VITE\_API\_BASE\_URL = '<https://api.example.com>'

五、框架特定规范（Vue3 + React）

1. Vue3 规范

单文件组件（SFC）结构：

Plain 复制代码

<template> <!-- 模板 --> </template>

<script setup lang="ts"> <!-- 逻辑（优先setup语法糖） --> </script>

<style scoped lang="scss"> <!-- 样式（scoped隔离） --> </style>

Composition API 规则：
- ref 用于基本类型，reactive 用于对象（避免 reactive 包裹基本类型）；
- 自定义钩子以 use 开头（如 useUserInfo）；
- 避免在 template 中直接使用 reactive 对象的属性（用 toRefs 解构）。

2. React 规范

组件设计：
- 优先用函数组件 + Hooks，避免 class 组件；
- 组件拆分：UI 组件（纯展示，如 Button）与容器组件（带逻辑，如 UserListContainer）分离；
- Hooks 规则：只在顶层调用，只在函数组件中调用（禁止条件判断内使用）。
Props 传递：
- 用 interface 定义 Props 类型（TS）；
- 非必要不传递 children（避免深层嵌套）；
- 大量 Props 用解构传递（<User {...userProps} />）。

1. 无障碍性

ARIA 属性：
- 动态内容用 aria-live（如通知：<div aria-live="polite">新消息</div>）；
- 表单错误提示关联 aria-describedby（如 <input aria-describedby="error-msg">）。
键盘导航 ：所有交互元素（按钮、菜单）必须可通过 Tab 聚焦，且有明显焦点样式（outline 或自定义样式）。

2. 性能优化

渲染优化：
- 避免频繁重排（如批量修改 DOM 前先脱离文档流）；
- Vue 用 v-memo 缓存静态节点，React 用 React.memo/useMemo 缓存组件/值。
资源加载：
- 非首屏 JS 用 dynamic import 懒加载（import('./HeavyComponent')）；
- 图片用 loading="lazy" 懒加载（<img src="large.jpg" loading="lazy">）。

七、协作与代码审查

Code Review checklist：
1. 代码是否符合规范（命名、格式、注释）；
2. 逻辑是否清晰（是否有冗余/重复代码）；
3. 边界情况是否处理（空值、异常、大数）；
4. 性能是否有优化空间（是否有不必要的 DOM 操作/请求）；
5. 是否包含测试用例（核心逻辑需覆盖）。
冲突处理 ：拉取代码前先 pull 最新 develop 分支，解决冲突时保留双方合理逻辑，避免暴力覆盖。

总结

规范的核心是「共识」与「落地」：

团队需共同制定规范（避免一刀切，保留合理灵活性）；
用工具（ESLint、husky 等）自动化约束，减少人工成本；
定期复盘迭代（根据项目反馈调整规则）。

通过细化规范，可显著降低沟通成本，提升代码可维护性，尤其适合多人协作的中大型项目。

前端开发规范

一、HTML 规范

1. 文档结构与元信息

2. 语义化深度规范

3. 性能与兼容性

二、CSS/SCSS 规范

1. 命名体系（BEM 扩展）

2. 选择器与权重

3. SCSS 语法规范

4. 响应式与适配

三、JavaScript/TypeScript 规范（增强版）

1. 变量与类型

2. 函数设计

3. 异步处理

4. 模块化与依赖

四、工程化与工具链（增强版）

1. ESLint + Prettier 配置

2. Git 工作流与提交规范

3. 构建与部署

五、框架特定规范（Vue3 + React）

1. Vue3 规范

2. React 规范

六、无障碍性（A11y）与性能

1. 无障碍性

2. 性能优化

七、协作与代码审查

总结