前端命名规范手册🎉 前端命名规范手册版本：1.2 | 适用于 JavaScript / TypeScript 项目（

🎉 前端命名规范手册
版本：1.2 | 适用于 JavaScript / TypeScript 项目（React/Vue/Node 兼容）

命名是代码的“第一文档”。好的命名让代码自解释，减少沟通成本。

🎯 目标

统一团队命名风格
提升代码可读性与维护性
避免歧义和误解
让新人快速理解项目结构

📏 一、通用原则（所有语言通用）

原则	说明
🔤 使用语义化名称	`userName` 比 `str1` 更清晰
🐫 使用驼峰命名法（camelCase）	默认规则
🧱 单词顺序：`[描述][主体][类型]`	`isLoadingUser`, `submitBtn`, `userInfoModal`
❌ 不要缩写除非通用	`btn` ✅，`usrNm` ❌
✅ 英文命名	禁止拼音或中英混杂

✅ 正确示例：

const userProfile = { ... };
function validateEmail() { ... }

❌ 错误示例：

const yonghu = 'zhangsan'; // 拼音
const getUserInfoByIdAndNameStr = ...; // 过长且混乱

🧩 二、按场景命名规范

1. 变量与常量

类型	规范	示例
普通变量	`camelCase`	`userName`, `isLoading`, `apiClient`
布尔值	加前缀 `is`, `has`, `can`, `should`	`isLoading`, `hasPermission`, `canEdit`, `shouldRefresh`
数字	明确单位或含义	`retryCount`, `timeoutMs`, `pageSize`
字符串	描述内容	`errorMessage`, `apiEndpoint`
常量	`UPPER_CASE_SNAKE`	`MAX_RETRY_COUNT`, `API_BASE_URL`
私有成员	前缀 `_`（约定）	`_cacheData`, `_init()`

2. 函数与方法

类型	命名建议	示例
普通函数	动词开头	`fetchUser()`, `validateForm()`, `showModal()`
异步函数	可加 `Async` 后缀（可选）	`fetchUserAsync()` 或直接用 `async` 关键字识别
事件处理函数	`handle + 事件名`	`handleClick`, `handleChange`, `handleSubmit`
回调函数	`on + 事件名`	`onClick`, `onSuccess`, `onError`
工具函数	清晰表达功能	`formatDate()`, `deepClone()`, `debounce()`

💡 小技巧：函数名应能回答“它做什么？”
👉 getUserById() → 获取用户；trimSpaces() → 去除空格

3. 类与构造函数

使用 PascalCase
名称为名词或名词短语

class User {}
class PaymentGateway {}
class ModalManager {}

⚠️ 不要用 IUser 开头（TypeScript 中不推荐接口加 I 前缀）

4. 接口与类型别名（TypeScript）

类型	规范	示例
接口	`PascalCase`，不用 `I` 前缀	`interface User {}` ✅，`interface IUser {}` ❌
类型别名	`PascalCase`	`type Status = 'active'	'inactive';`
泛型参数	单字母或有意义	`T`, `U`, `K extends keyof T`, `ResponseData`

5. 文件命名

场景	命名方式	示例
组件文件（React/Vue）	`PascalCase`	`UserProfile.vue`, `LoginForm.tsx`
工具函数文件	`camelCase` 或 `kebab-case`	`utils/helpers.js`, `formatDate.ts`
服务模块	`camelCase`	`apiClient.js`, `storageManager.ts`
样式文件	`kebab-case`（CSS/Sass）	`user-profile.scss`, `modal-style.css`
测试文件	与原文件同名 + `.test`	`getUser.test.ts`, `helpers.test.js`

💡 React 推荐：组件文件使用 PascalCase，其他使用 camelCase

6. 目录命名

目录	命名	说明
`src/components`	components	通用 UI 组件
`src/pages`	pages	页面级组件
`src/utils`	utils	工具函数
`src/services`	services	API 请求封装
`src/store`	store	状态管理
`src/types`	types	类型定义（TS）
`src/assets`	assets	静态资源
`src/styles`	styles	公共样式
`src/hooks`	hooks	自定义 Hook（React）

✅ 统一使用复数形式（如 components 而非 component）

7. CSS / SCSS / Tailwind 命名

方案一：BEM（适合传统 CSS）

/* Block */
.user-card {
  /* Element */
}

.user-card__avatar {
  /* Modifier */
}

.user-card--loading {
}

方案二：Tailwind + 语义类（推荐现代项目）

<!-- 不要写无意义的 div -->
<div class="flex flex-col gap-4 p-6 bg-white rounded-lg shadow">
  <h3 class="text-lg font-bold text-gray-800">用户信息</h3>
  <p class="text-sm text-gray-600">加载中...</p>
</div>

✅ 建议：HTML 结构要有语义，不要堆砌无意义的 div

8. Git 分支命名

类型	格式	示例
新功能	`feat/功能名`	`feat/user-login`
Bug 修复	`fix/问题描述`	`fix/header-overflow`
文档更新	`docs/修改内容`	`docs/readme-update`
样式调整	`style/layout-tweak`	`style/button-margin`
发布版本	`release/vX.X.X`	`release/v1.2.0`
主分支	`main` 或 `master`	`main`

9. 提交信息（Commit Message）

格式：<type>(<scope>): <description>

type	说明	示例
`feat`	新功能	`feat(login): add social login`
`fix`	修复 bug	`fix(header): hide on mobile)`
`docs`	文档变更	`docs: update contribution guide`
`style`	格式调整（不影响逻辑）	`style(code): format with prettier`
`refactor`	重构	`refactor(api): split user service)`
`perf`	性能优化	`perf(list): virtual scroll added`
`test`	测试相关	`test(auth): add token expiry check`
`chore`	构建或工具变更	`chore(deps): upgrade eslint config`

✅ 推荐配合 Commitlint 自动校验

🚫 三、禁止使用的命名方式

类型	错误示例	问题
拼音命名	`yonghu`, `zhuce`	无法协作，难维护
缩写不明	`tmp`, `val`, `obj`, `data1`	没有意义
单字母变量	`let a = 1;`	仅限循环计数器可用（如 `i`, `j`）
匈牙利命名法	`strName`, `bLoading`	已过时
中文注释+英文代码混合	`// 用户信息 var userInfo = ...`	不专业
文件名含空格或特殊字符	`my file.js`, `index(2).js`	兼容性差

✅ 四、优秀命名示例对比

场景	❌ 差命名	✅ 好命名
加载状态	`loading`	`isLoading`, `isFetchingUser`
按钮点击	`click()`	`handleLoginClick()`
验证函数	`check()`	`validateEmailFormat()`
存储令牌	`save(t)`	`setAuthToken(token)`
获取用户	`get(u)`	`fetchUserById(userId)`
配置对象	`config`	`apiRequestConfig`

🧰 五、工具辅助建议

1. ESLint 检查命名（推荐规则）

// .eslintrc.js
rules: {
  "camelcase": ["error", { "properties": "always" }],
  "@typescript-eslint/naming-convention": [
    "error",
    {
      "selector": "variable",
      "format": ["camelCase", "UPPER_CASE"]
    },
    {
      "selector": "function",
      "format": ["camelCase"]
    },
    {
      "selector": "interface",
      "format": ["PascalCase"],
      "custom": {
        "regex": "^I[A-Z]",
        "match": false
      }
    }
  ]
}

安装插件：@typescript-eslint/eslint-plugin

2. VS Code 插件推荐

插件	作用
ESLint	实时提示命名错误
Prettier	自动格式化
Error Lens	内联显示错误
Todo Tree	高亮 TODO 注释

📚 六、附录：命名速查表（打印贴桌用）

类型	命名规范	示例
变量	`camelCase`	`userName`
布尔值	`is/has/can/should`	`isLoading`
常量	`UPPER_CASE`	`API_TIMEOUT_MS`
函数	动词开头	`fetchData()`
事件处理	`handleXxx`	`handleClick()`
回调属性	`onXxx`	`onClick`
类/接口	`PascalCase`	`class User {}`
组件文件	`PascalCase`	`Header.tsx`
普通文件	`camelCase` 或 `kebab-case`	`utils.js`, `auth-helper.ts`
Git 分支	`feat/xxx`, `fix/xxx`	`feat/settings-page`

💌 结语

“There are only two hard things in Computer Science: cache invalidation and naming things.”
— Phil Karlton

虽然命名很难，但只要坚持以下三点，就能持续进步：

每次命名前多想 3 秒钟：“别人能看懂吗？”
Code Review 时重点看命名是否清晰
建立团队共识文档，定期回顾优化

📥 下一步建议：

我可以为你生成：

一份可下载的 PDF 版《前端命名规范手册》
VS Code 智能提示配置包（含命名检查）
团队定制版模板（带公司 Logo 和技术栈）

只需告诉我：

“我要 React 版” 或 “我们是 Vue 团队”

我就能一键输出完整资料包！🚀