ESLint、Prettier、Husky 和 Commitlint 完整配置指南

# 检查 Node.js 版本
node --version

# 检查 pnpm 版本
pnpm --version

# 检查 Git 版本
git --version

# 1. 安装 ESLint 核心依赖
pnpm add -D eslint@^8.57.0

# 2. 安装 TypeScript ESLint 支持
pnpm add -D @typescript-eslint/eslint-plugin@^6.21.0 @typescript-eslint/parser@^6.21.0

# 3. 安装 Vue ESLint 支持
pnpm add -D eslint-plugin-vue@^9.20.1

# 4. 安装 Import 检查支持
pnpm add -D eslint-plugin-import@^2.29.1 eslint-import-resolver-typescript@^3.6.1

# 5. 安装 Prettier 核心依赖
pnpm add -D prettier@^3.2.5

# 6. 安装 ESLint 和 Prettier 集成
pnpm add -D eslint-config-prettier@^9.1.0

# 7. 安装 Git Hooks 管理
pnpm add -D husky@^9.0.11 lint-staged@^15.2.2

# 8. 安装提交信息检查
pnpm add -D @commitlint/cli@^18.6.1 @commitlint/config-conventional@^18.6.2

pnpm add -D eslint@^8.57.0 \
  @typescript-eslint/eslint-plugin@^6.21.0 \
  @typescript-eslint/parser@^6.21.0 \
  eslint-plugin-vue@^9.20.1 \
  eslint-plugin-import@^2.29.1 \
  eslint-import-resolver-typescript@^3.6.1 \
  prettier@^3.2.5 \
  eslint-config-prettier@^9.1.0 \
  husky@^9.0.11 \
  lint-staged@^15.2.2 \
  @commitlint/cli@^18.6.1 \
  @commitlint/config-conventional@^18.6.2

# 创建 ESLint 配置文件
touch .eslintrc.cjs

# 创建 ESLint 忽略文件
touch .eslintignore

# 创建 Prettier 配置文件
touch .prettierrc.cjs

# 创建 Prettier 忽略文件
touch .prettierignore

# 创建 Commitlint 配置文件
touch commitlint.config.cjs

# 初始化 Husky
npx husky init

# 创建 commit-msg hook
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

# 检查 ESLint 版本
npx eslint --version

# 检查 Prettier 版本
npx prettier --version

# 检查 Commitlint 版本
npx commitlint --version

# 测试配置是否正常工作
npm run lint
npm run format:check

# 备份现有的配置文件（如果存在）
cp .eslintrc.* .eslintrc.backup 2>/dev/null || true
cp .prettierrc.* .prettierrc.backup 2>/dev/null || true

# 先安装基础依赖
pnpm add -D eslint@^8.57.0 prettier@^3.2.5

# 测试基础配置
npm run lint -- --no-fix
npm run format:check

# 逐步添加其他依赖和配置

# 格式化所有现有代码
npm run format

# 修复可自动修复的 ESLint 问题
npm run lint:fix

# 手动修复剩余问题
npm run lint

# 正确的提交信息
feat(auth): add user login functionality
fix(ui): resolve button alignment issue
docs: update installation guide
chore: update dependencies

# 错误的提交信息
Add login feature          # 缺少类型
feat: Add Login Feature     # 主题首字母大写
fix(ui): fix button.        # 主题以句号结尾

npx lint-staged

npx --no -- commitlint --edit $1

# ✅ 正确格式
feat: add user authentication
fix(ui): resolve button alignment issue
docs: update API documentation

# ❌ 错误格式
Add user authentication        # 缺少类型前缀
feat: Add User Authentication  # 主题首字母大写
fix(ui): resolve button.       # 主题以句号结尾
feature: add auth             # 类型不在允许列表中

# 1. 开发过程中，随时检查代码质量
npm run lint

# 2. 修复可自动修复的问题
npm run lint:fix

# 3. 格式化代码
npm run format

# 4. 提交前进行完整检查
npm run check

# 5. 提交代码（会自动触发 hooks）
git add .
git commit -m "feat: add new feature"

# 检查所有文件的代码规范
npm run lint
# 等同于：npx eslint . --ext .js,.ts,.vue --ignore-path .eslintignore

# 自动修复可修复的 ESLint 问题
npm run lint:fix
# 等同于：npx eslint . --ext .js,.ts,.vue --ignore-path .eslintignore --fix

# 格式化所有支持的文件
npm run format
# 等同于：npx prettier --write "**/*.{js,ts,vue,json,md,yml,yaml}"

# 检查文件格式化状态（不修改文件）
npm run format:check
# 等同于：npx prettier --check "**/*.{js,ts,vue,json,md,yml,yaml}"

# 同时运行 lint 和格式检查
npm run check
# 等同于：npm run lint && npm run format:check

# 同时运行 lint 修复和格式化
npm run fix
# 等同于：npm run lint:fix && npm run format

# 只检查特定目录
npx eslint packages/reactivity --ext .ts,.js

# 只格式化特定文件类型
npx prettier --write "**/*.vue"

# 使用缓存提高性能
npx eslint . --cache --ext .js,.ts,.vue

# 输出详细信息
npm run lint -- --format=detailed

# 只显示错误，不显示警告
npm run lint -- --quiet

# 检查特定文件
npx eslint packages/reactivity/src/index.ts

# 检查并修复特定文件
npx eslint packages/reactivity/src/index.ts --fix

# 检查特定目录
npx eslint packages/reactivity/src/

# 检查 Vue 文件
npx eslint packages/vite-project-vue/src/App.vue

# 格式化特定文件
npx prettier --write packages/reactivity/src/index.ts

# 检查文件格式（不修改）
npx prettier --check packages/reactivity/src/index.ts

# 格式化整个目录
npx prettier --write "packages/reactivity/src/**/*.{ts,js,vue}"

# 检查提交信息格式（手动测试）
echo "feat: add new feature" | npx commitlint

# 检查最近的提交信息
npx commitlint --from HEAD~1 --to HEAD --verbose

# 检查所有提交信息
npx commitlint --from=origin/main --to=HEAD --verbose

# 1. 修改文件后添加到暂存区
git add src/components/Button.vue

# 2. 尝试提交（会触发两个 hooks）
git commit -m "feat: add button component"

# 执行过程：
# ├── pre-commit hook 触发
# │   ├── 运行 lint-staged
# │   ├── 对 Button.vue 执行 eslint --fix
# │   ├── 对 Button.vue 执行 prettier --write
# │   └── 如果有错误，停止提交并显示错误
# ├── commit-msg hook 触发
# │   ├── 运行 commitlint
# │   ├── 检查 "feat: add button component" 格式
# │   └── 如果格式错误，停止提交并显示错误
# └── 提交成功创建

git add src/utils.ts  # 文件有格式问题
git commit -m "fix: update utils"

# 输出：
# ✔ Running tasks for staged files...
# ✔ prettier --write: src/utils.ts
# ✔ eslint --fix: src/utils.ts
# [main abc1234] fix: update utils

git add src/api.ts  # 文件有未使用的变量
git commit -m "feat: add api client"

# 输出：
# ✖ eslint --fix:
# src/api.ts
#   5:7  error  'unusedVar' is assigned a value but never used
#
# ✖ lint-staged failed
# 提交被取消，需要手动修复错误

git add README.md
git commit -m "Update documentation"  # 格式不正确

# 输出：
# ✖ subject may not be empty [subject-empty]
# ✖ type may not be empty [type-empty]
#
# 需要使用正确格式：
git commit -m "docs: update documentation"

# 紧急情况下可以跳过 hooks，但不推荐
git commit -m "feat: emergency fix" --no-verify

# 或者只跳过 pre-commit
git commit -m "feat: emergency fix" --no-verify

# 通过命令行安装扩展
code --install-extension ms-vscode.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension Vue.volar
code --install-extension bradlc.vscode-tailwindcss  # 如果使用 Tailwind CSS

# 错误：缺少类型
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
# 解决：添加正确的类型前缀
git commit -m "feat: add new feature"

# 错误：类型不在允许列表中
✖ type must be one of [feat, fix, docs, style, refactor, perf, test, chore, revert, build, ci] [type-enum]
# 解决：使用正确的类型
git commit -m "feat: add new feature"  # 而不是 "feature: add new feature"

# 错误：主题过长
✖ header must not be longer than 100 characters [header-max-length]
# 解决：缩短提交信息
git commit -m "feat: add user auth"  # 而不是很长的描述

# 错误：主题格式不正确
✖ subject must not be sentence-case [subject-case]
# 解决：使用小写开头
git commit -m "feat: add new feature"  # 而不是 "feat: Add new feature"

# 1. 检查 husky 是否正确安装
ls -la .husky/

# 2. 检查 hooks 文件权限
chmod +x .husky/pre-commit
chmod +x .husky/commit-msg

# 3. 检查 Git hooks 路径
git config core.hooksPath

# 4. 手动测试 hooks
.husky/pre-commit
echo "test commit" | .husky/commit-msg

# 重新初始化 husky
rm -rf .husky
npx husky init
echo 'npx lint-staged' > .husky/pre-commit
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

# 检查依赖树
npm ls eslint
npm ls @typescript-eslint/eslint-plugin

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install

# 或使用 pnpm
pnpm install --force

# 使用 cross-env 处理环境变量
npm install -D cross-env

# package.json
{
  "scripts": {
    "lint": "cross-env NODE_ENV=development eslint ."
  }
}

# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在 package.json 中
{
  "scripts": {
    "format": "node --max-old-space-size=4096 ./node_modules/.bin/prettier --write ."
  }
}

# ESLint 调试
DEBUG=eslint:* npm run lint

# Prettier 调试
npx prettier --debug-check src/

# Commitlint 调试
npx commitlint --verbose

# Husky 调试
HUSKY_DEBUG=1 git commit -m "test"

# 一键修复常见问题
npm run fix

# 重置所有配置
rm -rf node_modules .eslintcache
npm install
npx husky init

# 批量修复文件权限（Unix/Linux/macOS）
find .husky -type f -exec chmod +x {} \;

# 检查配置文件语法
node -c .eslintrc.cjs
node -c .prettierrc.cjs
node -c commitlint.config.cjs

# 完整的提交前检查流程
npm run check          # 检查代码质量和格式
npm run test          # 运行测试（如果有）
git add .
git commit -m "feat: add new feature"  # 触发 Git hooks

# 创建功能分支
git checkout -b feature/new-feature

# 开发过程中定期检查
npm run lint:fix
npm run format

# 提交前最终检查
npm run check

# 合并前确保主分支代码质量
git checkout main
git pull origin main
npm run check

# 创建团队配置同步脚本
# scripts/setup-dev-env.sh
#!/bin/bash

echo "Setting up development environment..."

# 安装依赖
pnpm install

# 设置 Git hooks
npx husky install

# 检查编辑器配置
if [ ! -d ".vscode" ]; then
  echo "Creating VS Code workspace settings..."
  mkdir -p .vscode
  # 复制推荐配置
fi

# 运行初始检查
npm run check

echo "Development environment setup complete!"

# 使用 .prettierignore 排除大文件
echo "*.min.js" >> .prettierignore
echo "*.bundle.js" >> .prettierignore
echo "dist/" >> .prettierignore

# 只格式化变更文件
npx prettier --write $(git diff --name-only --diff-filter=ACMR | grep -E '\.(js|ts|vue)$')

# 每月执行的维护脚本
# scripts/monthly-maintenance.sh

#!/bin/bash

echo "Running monthly maintenance..."

# 检查依赖更新
npm outdated

# 更新 ESLint 和 Prettier
npm update eslint prettier @typescript-eslint/eslint-plugin

# 检查配置兼容性
npm run check

# 生成依赖报告
npm audit

echo "Maintenance complete!"

# 生成代码质量报告
npx eslint . --format json --output-file reports/eslint-report.json

# 统计代码质量指标
echo "ESLint errors: $(cat reports/eslint-report.json | jq '[.[] | .errorCount] | add')"
echo "ESLint warnings: $(cat reports/eslint-report.json | jq '[.[] | .warningCount] | add')"

# 检查过时的依赖
npm outdated

# 更新 ESLint 相关依赖
npm update eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser

# 更新 Prettier
npm update prettier eslint-config-prettier