企业官网建设流程全解析

接手一个老项目的头三天，往往不是看业务逻辑，而是在各种命名里玩猜谜游戏。变量叫data1、data2，函数叫handle、init，组件一个叫UserCard一个叫UserInfo，文件一会儿order.ts一会儿orderDetail.ts。你能跑通，但每次改需求都像在雷区里走路。我待过的几个团队都有过这种阶段，后来大家痛定思痛，把变量、函数、组件、文件的命名规则拉齐成一套标准，维护成本肉眼可见地降下来了。

前端命名规范这件事，看起来是风格问题，本质上是认知负担问题。团队协作时，代码不仅是写给机器跑的，更是写给人看的。一个命名混乱的项目，新人上手要两周，规范清晰的项目，两天就能开始改需求。这篇内容我结合自己做过的中型后台项目、跨端组件库和多部门协作的前端工程，把命名这件事从四个维度拆开讲清楚——变量、函数、组件、文件，每条规则都会说为什么这么定，也会附上反面案例和迁移策略。

1. 为什么多数团队的命名守则最后都变成废纸

很多团队不是没定过规范，而是定了规范之后三个月就没人看了。我在某公司做前端负责人时，翻过团队早期的一份《前端编码规范》，写得挺全，变量要用小驼峰，组件用大驼峰，文件用中划线。但代码里完全是另一回事。原因很简单：规则太笼统，只给了格式，没给语义标准。比如变量要小驼峰，那userInformation和userInfo算不算都符合规范？都符合，但两个人写出来就是两种风格。真正的规范必须管到“语义层”，而不只是“语法层”。

另一个让规范失效的原因是缺乏强制性。靠代码评审去约束命名，评审人自己都记不住那么多规则，最后只能凭感觉。我后来想明白一件事：命名规范要能落地，必须满足三个条件——规则数量少且有优先级、每条规则都有明确的正反例、关键规则能用工具自动检查。这也是我在这篇文章里反复强调的，所有规则都应该能回答“我为什么这么写”和“我不这么写会怎样”，否则就是纸面规范。

还有一个现实情况是存量代码问题。老项目里几千个文件全是不规范命名，你不可能要求开发在改需求时顺便把所有相关命名都重构掉。正确的做法是把存量代码和新增代码分开管理：新增代码严格执行规范，存量代码分批迁移，按模块、按页面逐步清理，而不是搞一刀切。我下文会专门讲存量迁移的策略，这里先建立起一个共识——规范是给团队用的工具，不是给开发者增加负担的教条。

2. 变量命名的分类规则：名词短语、布尔语义与缩写边界

变量名在代码里承担的角色是“数据描述”，它应该像一个名词短语，让人一看就知道里面装的是什么。很多混乱命名就是从这里开始的，有的人喜欢用单个字母，有的人喜欢堆砌名词，还有的人把动词放进变量名里，这些都是常见问题。

2.1 用名词短语描述“数据是什么”，而不是“数据怎么来的”

变量命名最容易犯的错误是把“过程”写进名字里。比如getUserListResult、loadingData、formatDateString这类变量，名字里带了动词，读起来就像函数名。变量名应该回答“这个值是什么”，而不是“这个值怎么得到的”。用户列表就是users或者userList，加载状态就是isLoading，格式化后的日期就是formattedDate。

我习惯用三个层级去定义变量名：数据本体、数据状态、数据变体。数据本体直接对应业务概念，比如orders、products、userProfile；数据状态描述加载、提交、错误等生命周期，比如isSubmitting、hasError；数据变体指同一份数据的不同形态，比如sortedOrders、filteredProducts、rawResponse。这三个层级覆盖了日常开发中的大部分变量场景。如果一个变量不属于任何层级，往往它就不应该存在于代码里。

2.2 布尔变量必备前缀系统：is / has / can / should

布尔变量是重灾区。命名规范里必须强制布尔变量使用前缀，四个前缀按语义划分——is表示状态判断、has表示拥有关系、can表示能力权限、should表示条件倾向性。这样flag、status、check这种抽象布尔名就彻底不能用了。有人觉得前缀是多余，但代码里if (isUserActive)和if (userActive)的可读性差距是实打实的。

还要注意一类容易漏掉的布尔变量——HTML属性透传、组件 props 里的布尔参数、接口返回的布尔字段。组件 props 用布尔前缀在父组件使用时特别明显：:is-disabled、:has-footer、:can-edit。接口返回的布尔字段在DTO层就定好语义，后端给的ifxxx也别直接透传到前端组件里，先在转换层改名为规范的前缀形式。

2.3 缩写边界：通用缩写直接放行，领域缩写单独定义

缩写不是不能有，但必须有边界。btn、img、req、res这类通用缩写，团队里人人都懂，可以正常使用。usr、pwd、val这种属于模糊缩写，不同人理解不同，必须禁止。ConfigInfo和ConfigData这类一眼看不出差别的命名，属于“伪缩写”，也应该清理掉。

领域内部的缩写则需要一个约定。我在接手的某支付后台项目里，trans被两个人分别理解成“交易”和“翻译”，这就是没有领域缩写清单的结果。建议团队里维护一份缩写白名单，覆盖业务高频词，遇到不在名单里的词一律写全称。缩写越多，沟通成本就越高，这个度要把握好。

2.4 循环变量和临时变量的“窄作用域”原则

for (let i = 0; i < 10; i++)里的i完全没问题，因为它作用域只有三行。真正的问题是有同事把index、temp、item用在高作用域里，甚至函数入参直接叫args、data。临时变量有个黄金法则：作用域越小，命名越短；作用域越大，命名越长。回调函数里的参数至少要有业务含义，比如users.forEach((user) => ...)而不是users.forEach((item) => ...)。

关于map、filter、reduce这类高阶函数的回调参数，有一个更细的问题。回调参数名要对齐数组元素本身的语义，orders.map((order) => ...)是对的，list.map((item) => ...)是勉强，arr.map((el) => ...)是不及格。你在filter里写的参数名，实际上是在告诉读代码的人“这个集合里装的到底是什么”。

2.5 数值变量与字符串变量：带单位或带格式

这类变量推荐用后缀明确语义，是“带单位的数字”还是“格式化后的字符串”。比如timeoutMs明确单位毫秒，maxFileSizeMb明确单位兆；formatDate是函数，formattedDateStr是字符串变量。有个真实案例：某同事写了一个setTimeout(fn, wait)，wait是秒还是毫秒全靠猜，后来改成waitMs后问题立刻消失。类型系统无法表达单位时，只能靠命名去补充，这属于规范层面的兜底。

3. 函数命名的动词系统：从行为语义到返回约定

函数命名的核心跟变量正好相反——变量描述“是什么”，函数描述“做什么”。所以函数名的第一个词必须是一个动词，这能强制开发者思考函数的行为，而不是给函数起一个模糊的名字。很多混乱命名都出在动词边界不清上，下面我把高频场景全部列出来。

3.1 动词开头的强制约定与常见反例

函数命名规则可以直接落实到动词级别：行为函数用get/set/create/update/delete开头，状态查询用is/has/can开头，数据处理用format/parse/transform开头，事件处理用handle/on开头。这些动词形成了一个命名系统，读代码时看到动词前缀，基本就能猜到函数类型。

反例主要出现在几个地方。一是doXxx系列，doSave、doUpdate这种命名说明开发者自己都没想清楚这个函数的行为边界；二是init/initData/initConfig满天飞，不同模块的初始化逻辑全叫init，排查时只能逐个点开；三是名词开头的函数，比如userList()，既不像变量又不像函数，读代码时心智负担极重。函数名里出现名词不是问题，但名词开头一定是问题——行为函数必须动词开头。

3.2 get / fetch / query 的语义边界

这三个词都在“获取”，但侧重点完全不同。get用于同步获取、内存缓存或直接返回数据，fetch用于跨端请求或异步拉取远程数据，query用于带条件的复杂查询。如果函数是从接口拿数据，就叫fetchUserList；如果是组件里拿已加载的数据，就叫getCurrentUser；如果是带筛选条件查列表，就叫queryOrders。混用这三个词的团队，代码里经常出现getData一会儿是同步一会儿是异步的情况，这是特别典型的隐藏问题。

3.3 布尔返回值函数：统一用 is / has / can / should 开头

跟布尔变量对应，返回布尔值的函数也有一套统一前缀。is表示状态判断、has表示是否包含、can表示是否具备能力、should表示行为建议。这样if (isUserVip(user))、if (hasPermission(role, 'edit'))读起来非常顺。不少同事喜欢用checkXxx命名这类函数，check这个词是歧义词——你根本不知道它返回的是布尔值、状态对象还是抛异常，应该尽量避免。布尔返回函数和布尔变量使用同一套前缀系统，规则链完整，学习成本反而更低。

3.4 事件处理函数命名：handle 与 on 的搭配规范

事件处理函数容易出现两个极端：一种是全部叫handleClick，另一种是全部叫onClick。我用的规则是——组件内部函数用handle开头，组件对外暴露的事件回调 props 用on开头。内部按钮点击是handleSubmit，父组件传入的 props 是onSubmit。子组件内部再调用onSubmit，代码读出来就是“内部处理完、对外通知”，职责清晰。

如果组件有多个同类型事件源，handle后面要带上具体目标：handleUserSelect、handleSearchInput、handleModalClose，禁止出现handleClick1、handleClick2这种纯数字后缀。事件处理函数里如果逻辑复杂，拆出来的辅助函数命名继续遵循本节规则，形成一条完整的函数命名链。

3.5 回调与高阶函数：参数名要说出“集合里的元素是什么”

这里有一个常见的认知死角。两个函数嵌套调用时，内部回调的参数名容易被忽略，比如list.map((item) => transform(item))。一旦列表多套两层，item就完全失去语义。高阶函数参数的主体是集合里的元素，命名至少要具体到业务实体。函数返回函数的场景更要注意，比如createValidator(rules)返回的是校验函数，变量名就叫validator；如果返回的是一组规则，就叫validateRules。命名在回调链中同样适用。

4. 组件命名的三层规则：文件名、组件名与目录职责

组件命名跟变量、函数不同，它同时存在于三个地方：组件文件名、组件注册名（或组件名定义）、组件在父级里的引用名。这三处命名必须对齐，否则维护时会出现“找组件靠猜”的情况。以下是组件命名的完整规则。

4.1 组件名统一 PascalCase，文件名与组件名保持一致

组件名的规则相对简单：PascalCase，即每个单词首字母大写。但这里有一个执行细节。组件的文件名也要跟组件名保持一致，UserProfileCard.tsx里导出的就是UserProfileCard。很多团队文件名用中划线，组件名用 PascalCase，虽然能用，但会导致全局搜索时你需要记住两个版本。我建议干脆统一改为组件文件也用 PascalCase 命名，Vue 单文件组件和 React 组件都适用这一规则。

还要提醒一点：组件名前缀要有业务域约束。不要所有组件都叫CommonXxx、BaseXxx，通用组件的命名粒度要细分到用途上，比如CommonTable、BaseUpload、LayoutHeader。业务组件直接用业务名词，OrderStatusTag、UserPermissionModal，让人能通过名字直接定位到业务模块。

4.2 组件文件中“非组件导出”的命名边界

一个组件文件里除了组件本身，还经常导出辅助函数、常量、类型定义。这些导出的命名是否需要跟组件名对齐，答案是分情况看。辅助函数按第3节的函数命名规则正常命名，常量按变量规则，类型定义则统一用ComponentNameProps的格式，比如UserProfileCardProps。这样命名最大的好处是所有跟组件相关的类型都在一个文件里聚拢，引用时的路径和名称完全一致。

有一种例外：index.ts作为聚合出口时，它本身不命名组件，只负责 re-export 同目录下其他组件。在这种文件里，导出名必须保持与源文件一致，不允许做任何改名导出。我有一次在某项目里见到export { default as Card } from './UserProfileCard'，这个操作直接破坏了关联性，谁用谁知道有多难受。

4.3 组件内部状态、事件与 props 的统一约定

组件内部变量的命名要延续变量规则，同时增加组件特有的约定。组件的 props 解构出来直接用原字段名；useState的状态用count/setCount这种成对命名；组件内部的派生数据，比如filteredUsers、totalPrice，要体现出“这是从 props 或 state 计算出来的”。如果组件里出现const [visible, setVisible] = useState(false)，这个visible就语义不明，换成isModalVisible或isDropdownOpen更好。

组件内部函数遵循第3节的事件系统。这里要特别注意一个高频错误：在组件内部定义了一个叫onClick的函数，用于处理组件内部逻辑。这违反了“内部用 handle、对外用 on”的约定，会让读代码的人搞不清楚这个函数到底是内部行为还是对外接口。统一坚持handle内部、on对外的约定不动摇。

4.4 目录化组件：index 文件与相关组件聚合

一个页面或功能模块往往有多个组件，我采用目录化组织。目录名用小写中划线，比如user-profile/；该目录下放主组件UserProfile.tsx、子组件UserAvatar.tsx、类型文件types.ts、样式文件index.module.css等。index.ts文件只做聚合导出，把UserProfile输出给外部引用，其他文件保持相对独立。

目录化组织里最容易被忽略的是types.ts和constants.ts的文件内命名。类型定义文件里的类型命名用 PascalCase，常量文件里的常量用 UPPER_SNAKE_CASE。这两个文件虽然不属于组件命名范畴，但它们是组件目录的一部分，命名规范不能出现断层。我见过一个目录里types.ts里导出的类型叫user_type，另一个叫UserType，这就是典型断层问题。

5. 文件系统的模块化命名：配置、常量、类型与工具函数的归属

文件命名规范是团队协作的最后一个大项。它的规则比组件命名更细，因为文件不仅包含组件，还有 hooks、工具函数、类型定义、路由页面、样式文件等。文件命名的核心逻辑是：让文件的路径和名称直接反映“模块职责边界”。

5.1 单文件规则：小写中划线为主，两类文件用特殊格式

常规文件统一使用小写中划线，order-list.tsx、use-auth.ts、http-client.ts。这条规则的好处是文件系统对大小写不敏感的环境（比如部分 Windows 和 macOS 默认配置）下不会有歧义。但有两类文件例外：组件文件用 PascalCase（见第4节），常量文件用 UPPER_SNAKE_CASE（如API_ENDPOINTS.ts、APP_CONFIG.ts），类型定义文件可用中划线（如user-types.ts）。这种差异不是随意定的，组件文件需要跟组件名对齐，所以用 PascalCase；常量文件需要被全局检索，所以用大写下划线；其他场景全部走小写中划线是默认路径。

文件命名也要避免无意义堆叠。order-list-new.tsx、order-list-final.tsx、order-list-2.tsx这类版本后缀文件是重大隐患。文件应该通过内容管理版本，而不是通过文件名管理版本。如果真要在文件名里体现差异，请用业务语义词，比如order-list-pending.tsx和order-list-completed.tsx。

5.2 hooks 命名：use 前缀与小写中划线的固定搭配

React 生态里自定义 hooks 有一个硬性约定：use开头。这个规则不能破。文件名use-user.ts内部导出useUser，use-auth.ts导出useAuth。不要出现getUser.js、userStore.js这类旧命名。Vue 3 的 composables 函数，同样建议use开头。

hooks 内部返回的变量名也要同步规范。useUser返回一个对象，建议解构命名与返回字段保持一致，const { userInfo, isUserLoading, refreshUser } = useUser()，而不是取个别名const { userInfo: info } = useUser()。这里跟组件导出的“禁止改名”原则一脉相承，文件、函数、返回值三者命名保持一致，链条越短越好找。

5.3 配置、常量、类型文件：按模块维度聚合还是全局聚合？

我处理过的一个关键决策是：常量、类型、工具函数到底应该按模块放在各自目录下，还是全部塞进全局src/constants、src/types、src/utils？我的结论是分级处理。全局共享的基础常量放src/constants，模块内部使用的常量放对应模块目录下的constants.ts；类型同理，全局共享类型放src/types，模块内类型放types.ts。工具函数则要小心，utils.ts这种文件很容易变成一个杂货铺，超过100行的工具文件就必须考虑按用途拆分成多个文件，比如format.ts、validate.ts、request.ts。

5.4 路由页面、布局文件与样式的命名细化

路由页面文件在框架约定下命名相对固定，pages/user/list.tsx、pages/login/index.tsx，这类文件的命名要跟路由路径一致，避免出现页面文件叫userListPage.tsx但路由路径是/user/list的错位。布局组件用layout.tsx或app-layout.tsx，避免跟业务组件重名。样式文件命名建议跟随组件或页面文件：组件UserProfile.tsx对应样式UserProfile.module.css，页面order-list.tsx对应order-list.module.css。用 CSS Modules 时，类名建议统一 camelCase，比如userAvatar，而非user-avatar，这样在 JSX 里引用时不需要引号字符串，直接styles.userAvatar即可。

5.5 工具文件拆分与“公共目录”清理解析

src/utils和src/components里的“公共”目录，是我在无数项目里看到的命名重灾区。common.ts、components/index.ts、utils/index.ts——这些文件没法通过名称判断内容，靠打开去读。

我的建议是公共目录下也要按业务域建子目录或子文件，utils/format.ts、utils/validate.ts、utils/request.ts；components/ui/button.tsx、components/business/user-card.tsx。这样做的目标只有一个——文件名和高频搜索词能对齐。当你想找一个格式化时间的函数时，你搜format就能定位，而不是打开一个几百行的common.ts翻半天。这看起来是小事，对团队协作效率的影响非常大。

6. 用 Lint 与 CLI 把命名规范固化成机器人检查项

规则讲完了，最重要的问题是落地。我在前面说过，没有强制的规范等于没有规范。这里的强制不是靠人肉评审，而是靠代码工具链。以下是我在项目里实际用过的几层落地手段。

6.1 ESLint 规则：variable / function / component 命名自动校验

ESLint 的naming-convention规则可以覆盖变量、函数、参数、类属性等几乎所有命名格式。下面是一段实际生效的配置示例，针对 TypeScript 项目，@typescript-eslint/naming-convention负责语义前缀检查和格式检查。

"@typescript-eslint/naming-convention": [ "error", { "selector": "variable", "format": ["camelCase", "UPPER_CASE"], "leadingUnderscore": "allow" }, { "selector": "function", "format": ["camelCase"], "leadingUnderscore": "forbid" }, { "selector": ["typeLike", "interface"], "format": ["PascalCase"] }, { "selector": "booleanVariable", "format": ["camelCase"], "prefix": ["is", "has", "can", "should", "allow", "disable"] } ]

需要注意booleanVariable这个 selector 是 TypeScript ESLint 的扩展能力，原生 ESLint 对布尔变量做前缀约束需要结合@typescript-eslint/no-unnecessary-condition之类规则配合。实际配置时，建议先在项目里开启warn跑一个月，统计违规数量，再逐步调整为error。一旦调成error，合并请求时必须修复命名才能通过检查，防止规范执行变形。

6.2 文件系统命名检查：组件文大小写与目录路径规范

ESLint 管不到文件名和目录名，这一步我用一条小脚本在 CI 阶段跑。脚本的逻辑很简单：扫描项目中所有.tsx/.ts文件，检查组件文件是否 PascalCase 命名，非组件文件是否小写中划线。扩展名与文件类型是否匹配，同时也检查目录是否小写中划线。

import os import re import sys COMPONENT_EXT = {".tsx", ".jsx"} REGULAR_EXT = {".ts", ".js"} issues = [] for root, dirs, files in os.walk("src"): dirs[:] = [d for d in dirs if not d.startswith(".") and d not in {"node_modules"}] for filename in files: ext = os.path.splitext(filename)[1] if ext not in COMPONENT_EXT | REGULAR_EXT: continue base = os.path.splitext(filename)[0] if ext in COMPONENT_EXT and not re.match(r"^[A-Z][a-zA-Z0-9]*$", base): issues.append(f"组件文件应为 PascalCase: {os.path.join(root, filename)}") elif ext in REGULAR_EXT and not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", base): issues.append(f"普通文件应为小写中划线: {os.path.join(root, filename)}") for issue in issues: print(issue) if issues: sys.exit(1)

这段脚本覆盖不了所有历史包袱，但它负责新增文件的门禁。在 CI 的检查环境下跑，新提交的文件不合规就直接失败，存量不合规文件先放行。很多团队用 ESLint 只查了代码内命名，整个文件名的合规被忽略了，补上这个空档是完整的落地链路之一。

6.3 代码评审清单：四个维度的命名自检模板

即使有了自动化工具，评审环节还是需要人工判断语义是否准确。我在团队里推行过一张评审清单，每次 MR 都按清单自查，线上问题明显减少。清单的核心就是四个问题：

• 变量名是否回答了“这个值是什么”？布尔是否带is/has/can/should前缀？
• 函数名是否以动词开头？返回布尔值的函数是否能直接用于if语句？
• 组件名是否 PascalCase 且与文件名一致？目录是否能反应该组件所在业务域？
• 文件路径是否能反应该模块的职责？是否存在temp、test、old、new这类临时文件？

这张清单要贴在团队 Wiki 首页，不用背，评审前过一遍就行。超过20行代码的 MR，逐条对答案并不困难。习惯养成之后，规范就内化到肌肉记忆里了，评审时聊的是业务逻辑，而不是命名问题。

6.4 存量代码的迁移策略：模块切分与增量推进

如果项目里已经有大量不规范命名，你需要用一套不冲突的迁移策略。我把项目按业务模块切成若干“迁移批次”，每个批次对应一个目录或一条业务链路。迁移时按顺序来做：先移组件文件和目录，再改文件名与组件名，最后清理文件内部的变量和函数命名。每次迁移只动一个模块，改完立刻自测并提交 MR。

迁移过程中有一个绝对的纪律：不要在改需求时顺手重构命名。混在一起改，出问题了分不清是逻辑改错了还是重构改错了。要么只改业务，要么只做重构，拆分干净。我在某项目中用这种方法把一个500+文件的老前端工程逐步迁移完，耗时三个月，全程没有出现一次因为重构引发线上问题的情况。增量推进比一次性大重构安全得多，收益也稳定得多。

6.5 规范文档的最终形态：一页纸原则

在推行命名规范多年之后，我最终把团队规范压缩到一页纸。这一页纸上不写理由，只写规则和反例。理由都在这篇文章和团队 Wiki 里，规则本身只需可快速查询。最终版本长这样：

• 变量：camelCase + 名词短语；布尔加is/has/can/should；单位加后缀。
• 函数：camelCase + 动词开头；布尔返回值函数用is/has/can/should；事件处理内部用handle，对外 props 用on。
• 组件：PascalCase + 文件名一致；目录小写中划线；组件相关类型XxxProps。
• 文件：小写中划线；组件文件 PascalCase；常量文件 UPPER_SNAKE_CASE；hooks 用use前缀。

一页纸能贴到显示器旁边，或者在 IDE 里设成随手能打开的文件。规范能不能活下去，关键不在于写得多么详尽，而在于它有多容易被查询和被强制执行。超过一页纸的规范文档，说实话，我刚入职时都不会全读完。

7. 我踩过的一些真实坑与改进体会

最后分享几个跟命名有关的真实踩坑经历，这些体会比规则本身更有价值。

我在一个跨端项目里曾经统一过一套命名方案，但当时只定了组件名和文件名规则，没有管变量命名。结果三个月后，变量层面的混乱开始反噬组件层：一个组件里出现了isShow、visible、display三个意思完全相同的布尔变量。表面上是组件内部变量问题，根因是变量规范缺失导致团队各写各的。后来我们在 lint 里加了布尔前缀检查，这类问题在一个迭代内就被压住了。

还有一个让我印象深刻的案例。某同事在业务代码里写了一个函数叫getData，返回的是用户基本信息，但调用方看到getData完全不敢确认数据的业务含义，于是自己又包了一层fetchUserBasicInfo。两个函数同时存在，到后来连原作者都分不清该调哪个。这种问题本质上是函数名没有落到业务域导致的。后来我们强制函数名里必须体现至少一个业务实体名，比如fetchUserBasicInfo，连User都不敢写，那说明函数本身职责就不明确。

关于命名规范还有一个常见误区——认为命名规范会拖慢开发速度。我的体验恰恰相反，一旦形成了肌肉记忆，写代码时的决策成本大幅下降，反而更快。真正拖慢速度的是每个变量都在纠结怎么写、每个函数都在猜测已有代码的语义，那种不确定性才是浪费时间的大头。

如果你正在从零开始建规范，我的建议是先抓四个点：变量加布尔前缀、函数加动词开头、组件文件与组件名对齐、文件路径体现模块边界。这四个点落地后，项目代码的可读性会有一个从“能跑”到“能维护”的跃迁。其余的规则都是在这四个点上做细化，不必一步到位。命名规范是一套投资，前期花时间定规则，后期每天都在回收可维护性。