1. 为什么前端编码规范如此重要记得刚入行时我接手过一个维护项目。打开代码库的瞬间各种命名风格混搭、缩进方式随机、组件组织混乱的场景让我至今难忘。那次经历让我深刻认识到没有规范的代码就像没有交通规则的城市道路看似能走实则危机四伏。一套完整的前端编码规范应该像DNA一样贯穿项目的整个生命周期。它不仅仅是代码风格的统一更是团队协作的基石、项目可维护性的保障。特别是在现代前端工程中随着框架多样化和工程化复杂度提升规范的重要性愈发凸显。2. 基础语法规范从根基开始2.1 命名约定的艺术变量命名是代码可读性的第一道门槛。我们团队坚持驼峰命名法camelCase用于普通变量和函数帕斯卡命名法PascalCase用于构造函数和类全大写加下划线SCREAMING_SNAKE_CASE用于常量私有成员以下划线开头_privateMethod// 好的命名示例 const MAX_RETRY_COUNT 3; class UserProfile { constructor() { this._token ; } getProfile() { // ... } }特别注意避免使用拼音缩写和单字母变量名除非是循环中的临时变量如i2.2 代码格式的黄金法则缩进坚持使用2个空格不是Tab这是现代前端生态的共识行宽建议不超过100字符超出部分合理换行分号虽然JS可以自动插入但我们强制显式书写引号统一使用单引号JSX属性用双引号空行方法之间2行逻辑块之间1行// 规范的格式示例 function fetchData(url, params) { return axios.get(url, { params, headers: { X-Requested-With: XMLHttpRequest } }) .then((res) { if (res.status 200) { return res.data; } throw new Error(Request failed); }); }3. 框架专项规范React Vue 双轨制3.1 React 组件开发七原则组件结构一个文件只导出一个组件与样式文件同名Props设计优先使用原始类型复杂对象需定义PropTypes状态管理useState用于局部状态全局状态必须走ReduxHooks使用自定义Hook必须以use前缀命名性能优化memo包裹函数组件useMemo/useCallback避免重复计算副作用处理useEffect必须明确依赖项清除函数不能省略TS集成interface定义组件props禁止使用any类型// React组件规范示例 interface ButtonProps { type?: primary | default; onClick: (e: React.MouseEvent) void; } const Button: React.FCButtonProps memo(({ type default, onClick, children }) { const className btn btn-${type}; return ( button className{className} onClick{onClick} {children} /button ); }); Button.propTypes { type: PropTypes.oneOf([primary, default]), onClick: PropTypes.func.isRequired };3.2 Vue 3 组合式API最佳实践script setup新项目必须使用script setup语法响应式处理ref用于基本类型reactive用于对象Props定义使用defineProps宏进行类型声明组件通信自定义事件必须defineEmits声明样式作用域scoped CSS是默认选择深度选择器慎用TS支持defineProps和defineEmits必须带泛型参数!-- Vue单文件组件规范示例 -- script setup langts interface Props { modelValue: string; placeholder?: string; } const props definePropsProps(); const emit defineEmits{ (e: update:modelValue, value: string): void; }(); const handleInput (e: Event) { const target e.target as HTMLInputElement; emit(update:modelValue, target.value); }; /script template input :valuemodelValue :placeholderplaceholder inputhandleInput / /template style scoped input { border: 1px solid #ddd; padding: 8px 12px; } /style4. 工程化规范从构建到部署4.1 项目目录结构标准现代前端项目推荐采用功能导向的目录结构src/ ├── assets/ # 静态资源 │ ├── fonts/ # 字体文件 │ └── images/ # 图片资源 ├── components/ # 公共组件 │ └── Button/ # 组件独立目录 │ ├── index.tsx │ ├── style.module.scss │ └── types.ts ├── hooks/ # 自定义Hook ├── pages/ # 页面组件 │ └── Home/ │ ├── components/ # 页面私有组件 │ ├── services/ # API服务 │ └── store/ # 状态管理 ├── router/ # 路由配置 ├── store/ # 全局状态 ├── styles/ # 全局样式 ├── utils/ # 工具函数 └── main.ts # 应用入口关键点同类型文件集中管理避免在多个目录重复出现相同类型文件4.2 ESLint Prettier 配置模板.eslintrc.js基础配置module.exports { env: { browser: true, es2021: true, }, extends: [ eslint:recommended, plugin:react/recommended, plugin:typescript-eslint/recommended, prettier, ], parser: typescript-eslint/parser, parserOptions: { ecmaFeatures: { jsx: true, }, ecmaVersion: latest, sourceType: module, }, plugins: [react, typescript-eslint, import], rules: { react/react-in-jsx-scope: off, import/order: [ error, { groups: [ builtin, external, internal, parent, sibling, index, ], newlines-between: always, }, ], }, };.prettierrc配置示例{ printWidth: 100, tabWidth: 2, useTabs: false, semi: true, singleQuote: true, trailingComma: es5, bracketSpacing: true, jsxBracketSameLine: false, arrowParens: always }4.3 Git工作流规范分支策略main受保护分支只接受PR合并dev日常开发分支feature/xxx功能开发分支fix/xxx问题修复分支提交信息格式type(scope): subject // 空行 body // 空行 footer常用typefeat新功能fixbug修复docs文档变更style代码格式refactor代码重构test测试相关chore构建/工具变更Hooks配置 在.husky/pre-commit中添加#!/bin/sh . $(dirname $0)/_/husky.sh npm run lint-staged5. 高级规范与性能优化5.1 组件设计模式容器与展示分离容器组件处理数据逻辑展示组件专注UI渲染复合组件 通过Context提供共享状态如Tabs Tabs.List Tabs.Tab / /Tabs.List Tabs.Panels Tabs.Panel / /Tabs.Panels /TabsRender Props 适用于复杂交互逻辑复用MouseTracker {({ x, y }) ( div当前鼠标位置{x}, {y}/div )} /MouseTracker5.2 性能优化清单代码分割const LazyComponent React.lazy(() import(./LazyComponent));图片优化使用WebP格式实现懒加载响应式图片srcsetBundle分析 在package.json中添加scripts: { analyze: source-map-explorer build/static/js/*.js }关键CSS提取 使用critters-webpack-plugin自动提取首屏关键CSS6. 规范落地与团队协作6.1 规范执行策略新人入职清单阅读规范文档我们使用GitBook维护完成ESLint/Prettier配置通过示例项目测试Code Review要点命名一致性检查组件复杂度评估单个文件不超过300行重复代码检测类型安全验证对TS项目自动化工具链scripts: { prepare: husky install, lint: eslint --ext .js,.jsx,.ts,.tsx src, format: prettier --write \src/**/*.{js,jsx,ts,tsx,css,scss}\, lint-staged: lint-staged }, lint-staged: { *.{js,jsx,ts,tsx}: [ eslint --fix, prettier --write ], *.{css,scss}: [ prettier --write ] }6.2 常见问题解决方案历史项目改造分阶段引入规范使用eslint --fix自动修复基础问题新增代码严格遵循规范多框架共存制定框架间通用规范如命名、目录结构框架特定规则使用不同ESLint配置通过Monorepo管理共享代码规范更新机制每季度review一次规范重大变更需团队投票通过CHANGELOG记录变更在长期实践中我们发现规范的生命力在于持续演进。我们团队维护着一个规范问题记录表每次遇到因规范缺失导致的问题都会记录下来在季度review时集中讨论解决方案。这种自下而上的规范演进方式比单纯制定规则更有效。