以下是现代前端项目的完整代码规范配置方案，涵盖主流技术栈和自动化工具链配置：

---

一、基础工程配置

1. 项目结构规范

project/
├── src/
│   ├── assets/         # 静态资源
│   ├── components/     # 通用组件
│   ├── layouts/        # 布局组件
│   ├── router/         # 路由配置
│   ├── store/          # 状态管理
│   ├── styles/         # 全局样式
│   ├── utils/          # 工具函数
│   └── views/          # 页面组件
├── .editorconfig       # 编辑器统一配置
├── .eslintrc.js        # ESLint 配置
├── .prettierrc         # Prettier 配置
├── .stylelintrc.js     # Stylelint 配置
└── .commitlintrc.js    # Git 提交规范

---

二、JavaScript/TypeScript 规范

1. ESLint 配置 (.eslintrc.js)

module.exports = {root: true,env: { browser: true, es2021: true },extends: ['eslint:recommended','plugin:@typescript-eslint/recommended','plugin:vue/vue3-recommended', // Vue项目添加'prettier'],parserOptions: {ecmaVersion: 'latest',sourceType: 'module'},rules: {// 核心规则'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off','no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off','max-depth': ['error', 4], // 最大嵌套层级// TypeScript 规则'@typescript-eslint/no-explicit-any': 'off','@typescript-eslint/ban-ts-comment': 'warn',// Vue 专用规则'vue/multi-word-component-names': 'off','vue/html-self-closing': ['error', {html: { void: 'always' }}]},overrides: [{files: ['*.vue'],rules: {'max-lines-per-function': 'off'}}]
};

2. Prettier 配置 (.prettierrc)

{"printWidth": 100,"tabWidth": 2,"useTabs": false,"semi": true,"singleQuote": true,"quoteProps": "consistent","trailingComma": "none","bracketSpacing": true,"arrowParens": "avoid","vueIndentScriptAndStyle": true,"htmlWhitespaceSensitivity": "ignore"
}

---

三、CSS/SCSS 规范

1. Stylelint 配置 (.stylelintrc.js)

module.exports = {extends: ['stylelint-config-standard','stylelint-config-recommended-scss','stylelint-config-prettier'],plugins: ['stylelint-order'],rules: {'selector-class-pattern': '^[a-z][a-z0-9]*(-[a-z0-9]+)*$', // 短横线命名'order/properties-order': ['position','top','display','flex-direction', // 按逻辑分组排序'width','height','margin','padding','color','background'],'max-nesting-depth': 3, // 最大嵌套层级'scss/at-import-partial-extension': 'never'}
};

2. BEM 命名示例

// Good
.user-profile {&__avatar { ... }&__name--highlight { ... }
}// Bad
.userProfile {.avatar { ... }.nameHighlight { ... }
}

---

四、Vue 组件规范

1. 单文件组件结构

<template><!-- 组件根元素使用 kebab-case --><div class="user-card"><!-- 使用 PascalCase 组件名 --><UserAvatar /></div>
</template><script setup>
// 组合式 API 规范
import { ref } from 'vue'// 变量命名
const isLoading = ref(false)// 方法命名
const handleButtonClick = () => { ... }
</script><style lang="scss" scoped>
.user-card {// Scoped 样式
}
</style>

2. Props 定义规范

// TypeScript 类型定义
interface Props {/** 用户ID */userId: number/** 是否显示详情 */showDetail?: boolean
}const props = defineProps<Props>()

---

五、Git 提交规范

1. Commitlint 配置 (.commitlintrc.js)

module.exports = {extends: ['@commitlint/config-conventional'],rules: {'type-enum': [2,'always',['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']],'subject-case': [0]}
};

2. Commitizen 适配器

# 安装工具
npm install -g commitizen cz-conventional-changelog# 提交示例
git commit -m "feat(user): add login functionality"

---

六、自动化工具链

1. Husky + lint-staged 配置

// package.json
{"scripts": {"prepare": "husky install","lint": "npm run lint:js && npm run lint:style","lint:js": "eslint --ext .js,.vue src","lint:style": "stylelint src/**/*.{css,scss,vue}"},"lint-staged": {"*.{js,vue}": ["eslint --fix", "prettier --write"],"*.{css,scss}": ["stylelint --fix", "prettier --write"]}
}

2. Git Hook 配置

# 创建 pre-commit hook
npx husky add .husky/pre-commit "npx lint-staged"# 创建 commit-msg hook
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

---

七、最佳实践总结

1. 命名规范：

   • PascalCase：Vue组件、TypeScript 类型
   • camelCase：JavaScript 变量/函数
   • kebab-case：CSS类名、文件名

2. 代码组织：

   • 组件复杂度控制：单个组件不超过 500 行
   • 方法长度限制：单个方法不超过 50 行
   • 文件大小限制：单文件不超过 1000 行

3. 性能优化：

   // 组件懒加载
   const UserProfile = () => import('./UserProfile.vue')// 图片懒加载
   <img v-lazy="imageUrl" />
   

4. 文档规范：

   /*** 格式化日期* @param {Date} date - 需要格式化的日期对象* @param {string} format - 格式字符串* @returns {string} 格式化后的日期字符串*/
   function formatDate(date, format = 'YYYY-MM-DD') {// ...
   }
   

该配置方案适用于 Vue3 + TypeScript + Vite 技术栈，可根据项目需求调整扩展规则。建议搭配 VSCode 的 ESLint、Prettier 插件实现实时校验。