VUP

简体中文

English

简体中文

English

Appearance

Git Hooks 管理 ​

Husky 是一个用于管理 Git hooks 的工具，可以在 Git 操作的不同阶段自动执行脚本，确保代码质量和团队协作规范。本指南将详细介绍如何在 VUP 项目中使用 Husky。

什么是 Husky ​

Husky 是一个 Git hooks 管理工具，提供：

  • Git Hooks 管理 - 统一管理所有 Git hooks
  • 团队协作 - 确保团队成员使用相同的代码规范
  • 自动化检查 - 在提交前自动运行代码检查
  • 灵活配置 - 支持多种脚本和工具
  • 易于维护 - 简单的配置和管理方式

快速开始 ​

VUP 项目已经预配置了 Husky，开箱即用：

1. 查看现有配置 ​

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

# 查看现有 hooks
cat .husky/pre-commit
cat .husky/pre-push

2. 启用 Git Hooks ​

bash
# 确保 hooks 已安装
pnpm husky install

# 检查 hooks 权限
chmod +x .husky/*

支持的 Git Hooks ​

pre-commit ​

在提交前执行，用于代码检查：

bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行 lint-staged
pnpm lint-staged

pre-push ​

在推送前执行，用于运行测试：

bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行测试
pnpm test

commit-msg ​

在提交信息验证时执行：

bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 验证提交信息格式
npx commitlint --edit $1

post-commit ​

在提交后执行：

bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 提交后通知
echo "提交成功！"

项目配置 ​

package.json 配置 ​

json
{
  "scripts": {
    "prepare": "husky install",
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.{js,ts,tsx,vue}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}

.husky 目录结构 ​

.husky/
├── _/
│   └── husky.sh
├── pre-commit
├── pre-push
├── commit-msg
└── post-commit

常用配置 ​

代码格式化 ​

bash
# pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行 ESLint 和 Prettier
pnpm lint-staged

测试检查 ​

bash
# pre-push
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行测试
pnpm test

# 运行类型检查
pnpm type-check

提交信息验证 ​

bash
# commit-msg
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 验证提交信息格式
npx commitlint --edit $1

构建检查 ​

bash
# pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 检查构建
pnpm build

高级配置 ​

条件执行 ​

bash
# pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 只在特定文件变更时运行
if git diff --cached --name-only | grep -q "src/"; then
  pnpm lint-staged
fi

多环境支持 ​

bash
# pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 根据环境执行不同命令
if [ "$NODE_ENV" = "development" ]; then
  pnpm lint-staged
else
  pnpm lint-staged --strict
fi

错误处理 ​

bash
# pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行命令并处理错误
if ! pnpm lint-staged; then
  echo "代码检查失败，请修复后重新提交"
  exit 1
fi

团队协作 ​

新成员加入 ​

bash
# 克隆项目后安装依赖
pnpm install

# 自动安装 hooks（通过 prepare 脚本）
# 无需手动执行 husky install

配置同步 ​

bash
# 提交 hooks 配置
git add .husky/
git commit -m "chore: add husky hooks"

# 推送到远程仓库
git push origin main

新成员加入 ​

bash
# 新成员克隆项目
git clone <repository-url>
cd project

# 安装依赖（自动安装 hooks）
pnpm install

最佳实践 ​

1. 选择合适的 Hooks ​

  • pre-commit: 代码格式化和基础检查
  • pre-push: 运行测试和类型检查
  • commit-msg: 验证提交信息格式
  • post-commit: 提交后通知或清理

2. 性能优化 ​

  • 只检查变更的文件
  • 使用缓存机制
  • 避免运行耗时的操作

3. 错误处理 ​

  • 提供清晰的错误信息
  • 支持跳过 hooks 的选项
  • 记录详细的日志

4. 团队规范 ​

  • 统一 hooks 配置
  • 文档化使用说明
  • 定期更新和维护

常见问题 ​

问题 1: Hooks 不执行 ​

原因: Husky 未正确安装或配置

解决方案:

bash
# 重新安装 Husky
pnpm remove husky
pnpm add -D husky
pnpm husky install

# 检查 hooks 权限
chmod +x .husky/pre-commit

问题 2: 权限错误 ​

原因: Hooks 文件没有执行权限

解决方案:

bash
# 添加执行权限
chmod +x .husky/*

# 或者使用 Git 配置
git config core.hooksPath .husky

问题 3: 命令找不到 ​

原因: 环境变量或路径问题

解决方案:

bash
# 使用完整路径
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 使用 pnpm 执行
pnpm exec eslint --fix

问题 4: 跳过 Hooks ​

原因: 需要临时跳过检查

解决方案:

bash
# 跳过 pre-commit
git commit --no-verify -m "紧急修复"

# 跳过 pre-push
git push --no-verify

相关工具 ​

lint-staged ​

只对暂存的文件运行 linters：

json
{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"]
  }
}

commitlint ​

验证提交信息格式：

json
{
  "commitlint": {
    "extends": ["@commitlint/config-conventional"]
  }
}

pretty-quick ​

快速格式化代码：

bash
# 格式化暂存的文件
npx pretty-quick --staged

相关资源 ​

Copyright © 2025 VUP-CLI