前端项目规范搭建

从零搭建前端项目的代码规范、Git 规范和提交规范。各工具的完整配置见 工具模块。

---

整体流程

1. ESLint + Prettier     → 代码检查与格式化
2. husky + lint-staged   → Git 提交前自动检查
3. commitlint            → 提交信息规范
4. EditorConfig          → 编辑器统一配置

---

1. ESLint + Prettier

为什么要用 ESLint？

• 自动发现潜在 bug：比如使用了未定义的变量、== 而不是 ===、忘记处理 Promise 错误
• 统一代码风格：团队成员用不同的编辑器、不同的习惯，ESLint 强制统一规则
• 减少 Code Review 争议：格式问题交给工具处理，CR 专注于业务逻辑

为什么要用 Prettier？

• 自动格式化代码：保存时自动调整缩进、引号、分号等
• 支持多种语言：JS、TS、CSS、HTML、Markdown 等
• 与 ESLint 配合：ESLint 管代码质量，Prettier 管代码格式，各司其职

# 安装（ESLint 9+ flat config）
yarn add -D eslint @eslint/js eslint-plugin-vue prettier eslint-config-prettier

ESLint 核心配置

// eslint.config.js（ESLint 9+ 推荐的 flat config 格式）
import js from '@eslint/js'
import pluginVue from 'eslint-plugin-vue'
import prettier from 'eslint-config-prettier'

export default [
  js.configs.recommended,                             // ESLint 推荐规则
  ...pluginVue.configs['flat/recommended'],            // Vue 3 推荐规则
  prettier,                                            // 禁用与 Prettier 冲突的规则（放最后）
  {
    rules: {
      'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
      'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
      'vue/multi-word-component-names': 'off',
    },
  },
]

💡 ESLint 8 及更早版本使用 .eslintrc.cjs 格式，需额外安装 eslint-plugin-prettier。新项目建议直接使用 ESLint 9+ flat config。

验证 ESLint 是否生效：

# 1. 运行 ESLint 检查
npx eslint src/

# 2. 应该看到错误和警告列表
# 3. 运行自动修复
npx eslint src/ --fix

# 4. 在 VS Code 中安装 ESLint 扩展，保存时自动检查

Prettier 核心配置

// .prettierrc.cjs
module.exports = {
  semi: false,                                        // 不加分号（如：const a = 1 而不是 const a = 1;）
  singleQuote: true,                                  // 使用单引号（如：const a = 'hello'）
  trailingComma: 'all',                               // 多行末尾加逗号（方便 git diff）
  printWidth: 100,                                    // 每行最大字符数（超过则换行）
  tabWidth: 2,                                        // 缩进使用 2 个空格
  endOfLine: 'lf',                                    // 换行符使用 LF（Linux/Mac 格式）
}

验证 Prettier 是否生效：

# 1. 运行 Prettier 格式化
npx prettier --write .

# 2. 检查格式化结果
npx prettier --check .

# 3. 在 VS Code 中安装 Prettier 扩展，保存时自动格式化

📖 完整配置参考：ESLint 命令 · Prettier 命令

---

2. husky + lint-staged

为什么要用 husky + lint-staged？

想象一下：你配置了 ESLint 和 Prettier，但团队成员可能忘记运行检查就直接提交代码，不规范的代码就进入了仓库。

husky：Git 钩子工具，在 git commit 之前自动执行检查，不通过就不让提交。

lint-staged：只检查本次修改的文件（暂存区的文件），而不是整个项目。这样：

• 速度快：只检查改了的几个文件，不用扫描整个项目
• 不影响旧代码：不会因为历史遗留问题导致提交失败

npm install -D husky lint-staged
npx husky init                           # 初始化 .husky/ 目录
echo 'npx lint-staged' > .husky/pre-commit   # 提交前执行检查

lint-staged 配置

// package.json
{
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"],   // 对 JS/TS/Vue 文件运行 ESLint 修复 + Prettier 格式化
    "*.{css,scss,less}": ["prettier --write"]                 // 对样式文件运行 Prettier 格式化
  }
}

验证 lint-staged 是否生效：

# 1. 修改一个 JS 文件
echo "const a = 1" > test.js

# 2. 暂存文件
git add test.js

# 3. 提交（会触发 lint-staged 检查）
git commit -m "test: 验证 lint-staged"

# 4. 如果代码不规范，提交会被阻止
# 5. 修复后重新提交

📖 完整配置参考：husky + lint-staged

---

3. commitlint

为什么要用 commitlint？

当项目越来越大，提交记录可能有几百上千条。如果提交信息写成"fix bug"、"update"、"改了一下"，过几个月根本不知道这次提交改了什么。

commitlint 的好处：

• 规范化提交信息：强制按照 type(scope): description 格式写
• 自动生成 changelog：根据提交类型自动生成版本更新日志
• 快速定位问题：回溯历史时，清晰的提交信息能快速找到相关改动
• 团队协作：每个成员都能快速理解每次提交的意图

npm install -D @commitlint/cli @commitlint/config-conventional
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

配置文件

// commitlint.config.cjs
module.exports = {
  extends: ['@commitlint/config-conventional'],        // 使用 Angular 提交规范（业界标准）
}

验证 commitlint 是否生效：

# 1. 尝试不规范的提交
git commit -m "fix bug"

# 2. 应该被拒绝，提示格式错误

# 3. 使用规范格式提交
git commit -m "fix: 修复首页白屏问题"

# 4. 提交成功

提交格式

# <type>: <subject>
git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复首页白屏问题"
git commit -m "docs: 更新 README"
git commit -m "refactor: 重构请求封装"
git commit -m "feat(login): 添加手机号登录"   # 带作用域

type	说明
feat	新功能
fix	修复
docs	文档
style	格式（不影响逻辑）
refactor	重构
perf	性能优化
test	测试
chore	其他杂项

---

4. EditorConfig

# .editorconfig
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

---

完整 package.json 示例

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint . --fix",
    "format": "prettier --write .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,ts,vue}": ["eslint --fix", "prettier --write"],
    "*.{css,scss,less}": ["prettier --write"]
  }
}

---

验证项目规范

完整验证流程

# 1. 安装所有依赖
npm install

# 2. 初始化 husky
npx husky init

# 3. 运行 ESLint 检查
npm run lint

# 4. 运行 Prettier 格式化
npm run format

# 5. 测试提交规范
echo "const a = 1" > test.js
git add test.js
git commit -m "test: 验证规范"
# 应该成功提交

# 6. 测试不规范提交
git commit -m "fix bug"
# 应该被拒绝

验证 Git 钩子

# 1. 查看 .husky 目录
ls .husky/

# 2. 应该看到 pre-commit 和 commit-msg 文件

# 3. 测试 pre-commit 钩子
git add .
git commit -m "test"
# 如果代码不规范，提交会被阻止

# 4. 测试 commit-msg 钩子
git commit -m "invalid format"
# 如果提交信息不规范，提交会被阻止

---

常见问题

ESLint 和 Prettier 冲突

问题：ESLint 报错但 Prettier 无法修复

解决方案：
1. 确保安装了 eslint-config-prettier
2. 确保 eslint.config.js 中 prettier 配置放在最后
3. 运行 npx eslint --print-config src/main.ts 查看最终配置，确认无冲突规则

husky 钩子不生效

问题：git commit 时没有触发检查

解决方案：
1. 确保运行了 npx husky init
2. 确保 .husky/pre-commit 文件有执行权限
3. 确保 package.json 中有 "prepare": "husky" 脚本
4. 重新安装 husky：npm install husky --save-dev

commitlint 报错

问题：提交信息格式正确但被拒绝

解决方案：
1. 确保 commit-msg 钩子文件存在
2. 确保 commitlint.config.cjs 文件存在
3. 检查提交信息是否符合格式：<type>: <subject>
4. type 必须是 feat/fix/docs/style/refactor/perf/test/chore 之一

VS Code 保存时不自动格式化

问题：保存文件时没有自动运行 ESLint/Prettier

解决方案：
1. 安装 ESLint 和 Prettier 扩展
2. 在 settings.json 中添加：
   {
     "editor.formatOnSave": true,
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true
     }
   }

---

参考

• ESLint 官方文档
• Prettier 官方文档
• husky 文档
• commitlint 文档
• Angular Commit 规范