Skip to content

Latest commit

 

History

History
185 lines (131 loc) · 5.39 KB

.pre-commit-setup.md

File metadata and controls

185 lines (131 loc) · 5.39 KB

Pre-commit Hooks 设置指南

本项目使用 pre-commit hooks 来确保代码质量。在提交代码之前，会自动运行以下检查：

检查内容

后端检查

  1. Ruff Lint - 自动修复可修复的代码问题
  2. Ruff Format - 检查代码格式
  3. Ruff Check (严格模式) - 强制检查，不允许任何 lint 错误
  4. MyPy - Python 类型检查

前端检查

  1. ESLint - JavaScript/TypeScript 代码检查

通用检查

  • 行尾空白检查
  • 文件末尾换行检查
  • YAML/JSON 格式检查
  • 大文件检查
  • 合并冲突检查
  • 私钥检测

安装步骤

pre-commit 与后端 UV 环境绑定，不推荐全局安装 pre-commit。请使用项目提供的脚本一键安装。

1. 安装 uv（若尚未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 在仓库根目录执行安装脚本

# 在项目根目录执行
./scripts/setup-pre-commit.sh
# 或: bash scripts/setup-pre-commit.sh

该脚本会：在 backend 中执行 uv sync --dev（安装 pre-commit 等 dev 依赖）、uv run pre-commit install --install-hooks（安装 Git hooks，hook 将使用 backend 的 venv）。

3. 验证安装

# 使用后端 venv 运行所有 hooks 检查所有文件（在仓库根目录执行）
./scripts/run-pre-commit.sh
# 或
backend/.venv/bin/python -m pre_commit run --all-files

# 只运行特定 hook
backend/.venv/bin/python -m pre_commit run backend-ruff-check --all-files
backend/.venv/bin/python -m pre_commit run frontend-lint --all-files

使用说明

正常提交流程

当你执行 git commit 时，pre-commit hooks 会自动运行：

git add .
git commit -m "your message"

如果检查失败，提交会被阻止。你需要：

  1. 修复报告的错误
  2. 重新添加文件 (git add .)
  3. 再次提交

跳过 Hooks (不推荐)

如果确实需要跳过 hooks（例如紧急修复），可以使用：

git commit --no-verify -m "emergency fix"

注意： 跳过 hooks 会绕过代码质量检查，可能导致 CI 失败。

手动运行检查

# 检查所有文件（在仓库根目录，使用 backend venv）
./scripts/run-pre-commit.sh
# 或 backend/.venv/bin/python -m pre_commit run --all-files

# 检查暂存的文件（在仓库根目录，需已通过 setup-pre-commit.sh 安装 hook）
pre-commit run

# 检查特定 hook
backend/.venv/bin/python -m pre_commit run ruff --all-files
backend/.venv/bin/python -m pre_commit run frontend-lint --all-files

故障排除

问题：Operation not permitted / uv cache 或 sysconf 报错

解决方案：

  • 已改为使用 backend .venv 直接运行 pre-commit，不再用 uv run，可避免 uv cache 权限问题。
  • 若在 Cursor 内置终端仍报 os.sysconf 等权限错误，请在本机系统终端（如 Terminal.app、iTerm）执行： 
    ./scripts/run-pre-commit.sh
# 或
backend/.venv/bin/python -m pre_commit run --all-files

问题：uv run ruff check 找不到命令

解决方案：

  1. 确保已安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
  2. 确保 backend 目录下有虚拟环境：cd backend && uv venv
  3. 确保已安装依赖：cd backend && uv sync --dev

问题：pnpm run lint 找不到命令

解决方案：

  1. 确保已安装 pnpm：npm install -g pnpm
  2. 确保 frontend 目录下已安装依赖：cd frontend && pnpm install

问题：Hooks 运行太慢

解决方案：

  • Hooks 默认只检查更改的文件
  • 如果需要跳过某些检查，可以临时使用 --no-verify
  • 考虑优化检查配置，排除不需要检查的文件

问题：某些检查在 CI 中失败但在本地通过

解决方案：

  • 确保本地环境与 CI 环境一致
  • 运行 ./scripts/run-pre-commit.sh 或 backend/.venv/bin/python -m pre_commit run --all-files 检查所有文件
  • 检查是否有未提交的修复

更新 Hooks

# 更新 hooks 到最新版本（在仓库根目录）
backend/.venv/bin/python -m pre_commit autoupdate

# 然后重新安装
backend/.venv/bin/python -m pre_commit install --install-hooks

配置说明

配置文件：.pre-commit-config.yaml

主要配置：

  • 后端 Ruff Check: 使用 uv run ruff check . 检查整个 backend 目录
  • 前端 ESLint: 使用 pnpm run lint 检查整个 frontend 目录
  • 两个检查都设置为 always_run: false，只在相关文件更改时运行

最佳实践

  1. 提交前运行检查：在提交前运行 ./scripts/run-pre-commit.sh 或 backend/.venv/bin/python -m pre_commit run --all-files 确保所有检查通过
  2. 修复自动修复的问题：Ruff 会自动修复一些问题，记得重新添加修复后的文件
  3. 不要跳过 hooks：除非是真正的紧急情况
  4. 保持 hooks 更新：定期运行 pre-commit autoupdate 更新 hooks

相关命令

# 安装 hooks（推荐使用脚本）
./scripts/setup-pre-commit.sh

# 或仅安装 hooks（需已运行 uv sync --dev 于 backend）
backend/.venv/bin/python -m pre_commit install --install-hooks

# 卸载 hooks
backend/.venv/bin/python -m pre_commit uninstall

# 运行所有检查（在仓库根目录）
./scripts/run-pre-commit.sh
# 或 backend/.venv/bin/python -m pre_commit run --all-files

# 更新 hooks
backend/.venv/bin/python -m pre_commit autoupdate

# 清理缓存
backend/.venv/bin/python -m pre_commit clean