命名与目录约定自动化从口头约定到检查脚本在前端团队的工程化规章里几乎都有一份详尽的《命名与目录组织规范》“Vue 组件文件名必须使用大驼峰PascalCase如UserProfile.vue”“工具函数文件必须使用中划线kebab-case如format-currency.ts”“自定义 Hooks 必须以use开头如usePagination.ts”“图片与静态资源必须全小写加下划线如icon_success.png”“测试文件必须紧邻源码并命名为*.spec.ts或*.test.ts。”这些约定看似微不足道但一旦团队规模扩张或项目长期演进各种大小写不一的命名就会四处开花如usercard.vue、User_Card.vue、userCard.vue并存。更要命的是macOS 默认对文件名大小写不敏感Case-insensitive而 Linux 生产构建机对大小写严格敏感Case-sensitive开发者本地编译一切正常一推到 GitLab CI 就报Module not found引发恶性的发布阻断事故。靠在 Code Review 里人肉盯文件名不仅浪费时间而且极易漏检。真正的工程洁癖解法是将命名与目录约定编写为自动化检查脚本并将其挂载至 Git Hooks 与 CI 门禁。约定体系设计文件命名模式与目录矩阵我们建立了一套清晰的文件类型与命名规则对应矩阵[前端工程命名与目录矩阵] 目录路径 (Pattern) 强制命名规范 典型示例 ------------------------------------------------------------------------------------- src/components/**/*.vue 大驼峰 (PascalCase) ProTable.vue, UserAvatar.vue src/views/**/*.vue 大驼峰 (PascalCase) OrderList.vue, Checkout.vue src/hooks/**/use*.ts 小驼峰 (camelCase) useWindowSize.ts, useRequest.ts src/utils/**/*.ts 中划线 (kebab-case) format-money.ts, date-helper.ts src/stores/**/use*Store.ts 小驼峰 (camelCase) useUserStore.ts, useAuthStore.ts src/assets/images/**/*.{png,svg} 小写下划线 (snake_case) bg_dashboard_header.png检查脚本开发轻量且高精度的 lint-filenames.ts我们编写了一个轻量级无依赖的 Node.js 校验脚本基于glob与正则对全仓或增量文件进行模式匹配// scripts/lint-filenames.ts import fs from fs; import path from path; import { globSync } from glob; interface Rule { name: string; pattern: string; // 匹配的文件 glob validator: (basename: string, ext: string) boolean; errorMessage: string; } // 命名校验正则 const PASCAL_CASE /^[A-Z][a-zA-Z0-9]$/; const CAMEL_CASE /^[a-z][a-zA-Z0-9]$/; const KEBAB_CASE /^[a-z0-9](-[a-z0-9])*$/; const SNAKE_CASE /^[a-z0-9](_[a-z0-9])*$/; const rules: Rule[] [ { name: Vue 组件必须使用大驼峰 (PascalCase), pattern: src/{components,views}/**/*.vue, validator: (basename) PASCAL_CASE.test(basename) || basename index, errorMessage: Vue 组件文件名必须使用 PascalCase (例如: MyComponent.vue), }, { name: 自定义 Hooks 必须以 use 开头并采用 camelCase, pattern: src/hooks/**/*.{ts,js}, validator: (basename) basename.startsWith(use) CAMEL_CASE.test(basename), errorMessage: Hooks 文件名必须使用小驼峰并以 use 开头 (例如: useDebounce.ts), }, { name: 工具函数文件必须使用 kebab-case, pattern: src/utils/**/*.{ts,js}, validator: (basename) KEBAB_CASE.test(basename) || basename index, errorMessage: Utils 工具函数文件名必须使用 kebab-case (例如: format-date.ts), }, { name: 静态图片与图标必须使用 snake_case, pattern: src/assets/images/**/*.{png,jpg,jpeg,svg,webp}, validator: (basename) SNAKE_CASE.test(basename), errorMessage: 图片资源文件名必须全部小写并使用下划线连接 (例如: banner_home_top.png), }, ]; export function runFilenameLinter(isIncremental false): boolean { console.log( 开始执行工程文件名与目录约定检查...); let hasError false; for (const rule of rules) { const files globSync(rule.pattern, { ignore: [**/node_modules/**, **/dist/**] }); for (const filePath of files) { const ext path.extname(filePath); const basename path.basename(filePath, ext); if (!rule.validator(basename, ext)) { console.error(❌ [命名违规] 文件: ${filePath}); console.error( 规则: ${rule.name}); console.error( 说明: ${rule.errorMessage}\n); hasError true; } } } if (hasError) { console.error( 检查未通过请按照前端工程规范修正文件名后重新提交); return false; } console.log(✅ 所有文件命名与目录规范检查通过); return true; } // 支持命令行直接执行 if (require.main module) { const success runFilenameLinter(); process.exit(success ? 0 : 1); }接入 Husky 与 Git 大小写敏感防御为了在源头掐死跨平台大小写不一致的“幽灵故障”除了运行上述脚本还需要在工程初始化的package.json中配置两项硬核防线1. 强制 Git 开启大小写敏感跟踪在仓库初始化脚本中执行# 强制让本地 Git 严格区分大小写 git config core.ignorecase false2. 挂载到 lint-staged 与 Pre-commit 钩子在package.json中{ scripts: { lint:filenames: tsx scripts/lint-filenames.ts }, lint-staged: { src/**/*.{vue,ts,js,png,svg}: [ tsx scripts/lint-filenames.ts ] } }在开发者执行git commit时lint-staged会秒级拦截非法命名的文件直接禁止提交并输出清晰的修复指引。落地成效彻底终结跨平台构建事故自脚本接入 CI 门禁后全团队因“大小写拼写不一导致 Linux 编译报错”的事故率直接归零代码库整洁度大幅提升新加入的工程师无需反复阅读十几页的 Wiki 命名文档脚本在本地实时反馈100% 确保整个多仓Monorepo的目录结构保持高度的一致性与审美洁癖。