setup-git-hooks

设置 Git 钩子

此设置的内容

• core.hooksPath 指向已提交的 .githooks/ 目录（Git 内置功能，无需 Husky）
• lint-staged 对其支持的语言运行 Biome
• Biome 配置（如果缺失）
• Prettier 用于 Biome 未覆盖的语言，仅在用户选择启用时使用
• 在 pre-commit 钩子中运行 typecheck 和 build 脚本

为什么不用 Husky：Husky 唯一的工作就是将运行器复制到 .git/hooks/。git config core.hooksPath .githooks 无需任何依赖即可实现相同效果。prepare 脚本会在每次 npm install 时设置该配置，因此团队成员克隆仓库后也能使用。

步骤

1. 检测包管理器和现有钩子工具

检查是否存在 package-lock.json（npm）、pnpm-lock.yaml（pnpm）、yarn.lock（yarn）、bun.lockb（bun）。使用检测到的包管理器。如无法确定，则默认使用 npm。

如果仓库已在使用 Husky（存在 .husky/ 目录或 prepare: husky），请先询问用户是要迁移掉 Husky，还是保留 Husky 并在此停止，然后再进行任何安装或写入操作。

2. 确定格式化工具的覆盖范围

列出仓库包含的语言，然后检查你将安装的 Biome 版本支持格式化和 lint 的语言（查看其文档或运行 biome --help）。有些语言（包括 Biome 2.x 中的 HTML）只有在 biome.json 中启用后才受支持；将其视为已覆盖，并在步骤 7 中启用。保留项目已经在使用的格式化工具（oxfmt、dprint、Prettier），并将其支持的语言分配给该工具。

如果仍有未覆盖的语言，请逐一列出这些语言，为它们提供 Prettier 选项，并让用户选择是否接受。

完成标准：仓库中的每种语言都已分配给 Biome、现有格式化工具、Prettier（用户接受）或不使用格式化工具（用户拒绝）。

3. 安装依赖

将 lint-staged 和 @biomejs/biome 安装为 devDependencies；仅当用户接受时，才将 prettier 一并安装。跳过仓库中已有的工具。

4. 创建 .githooks/pre-commit

写入此文件并将其设为可执行（chmod +x .githooks/pre-commit）：

#!/bin/sh
npx lint-staged
npm run typecheck --if-present
npm run build --if-present

调整：将 npm 替换为检测到的包管理器（不支持 pnpm --if-present，因此先检查 package.json 中是否存在相应脚本；如果不存在，则省略该行）。如果仓库的 package.json 中没有 typecheck 或 build 脚本，则省略相应脚本，并告知用户。

5. 将 Git 指向钩子目录

git config core.hooksPath .githooks

这是本地配置；新克隆的仓库也需要此配置。在 package.json 中添加 prepare 脚本，使其在每次安装时运行：

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks"
  }
}

将其合并到现有脚本中；如果 prepare 已存在，则追加 git config 调用（例如使用 &&）。

6. 创建 .lintstagedrc

Biome 会为步骤 2 中分配给它的语言执行格式化和 lint（check）。只有用户将某些语言分配给 Prettier 时，才添加 Prettier 条目：

{
  "*.{js,jsx,ts,tsx,json,jsonc,css,graphql}": "biome check --write --no-errors-on-unmatched",
  "*.{html,md,mdx,yaml,yml,scss,vue,svelte,astro}": "prettier --write"
}

每个 glob 只能指定一个工具，并且只列出仓库中包含的扩展名。

7. 创建 biome.json 和 .prettierrc（如果缺失）

仅当不存在任何配置文件时才创建配置（检查是否存在 biome.json、biome.jsonc、.prettierrc、.prettierrc.json、prettier.config.*）。启用步骤 2 中分配给 Biome 的可选语言。仅当用户接受 Prettier 时才写入 .prettierrc。

Biome 默认配置（biome.json）。写入前询问用户基础格式化偏好（参见下方问题），然后写入文件：

{
  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
  "formatter": {
    "enabled": true,
    "indentWidth": 2,
    "lineWidth": 160,
    "trailingComma": "none"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "semicolons": "always",
      "arrowParentheses": "always"
    }
  },
  "json": {
    "formatter": { "enabled": true }
  },
  "css": {
    "formatter": { "enabled": true }
  },
  "linter": { "enabled": true },
  "organizeImports": { "enabled": true },
  "assist": {
    "actions": {
      "source": {
        "useSortedAttributes": "on",
        "useSortedKeys": "on",
        "useSortedProperties": "on"
      }
    }
  }
}

写入 biome.json 前，询问用户基础参数（跳过已回答或上文已固定的项）：

• 使用制表符还是空格（默认：空格，宽度为 2）？
• 行宽（默认：160）？
• JS/TS 的引号样式（默认：双引号）？
• 分号和箭头函数括号（默认：始终使用 / 始终使用）？

Prettier 默认配置（.prettierrc，用户接受时使用，与 Biome 基础配置一致）：

{
  "useTabs": false,
  "tabWidth": 2,
  "printWidth": 160,
  "singleQuote": false,
  "trailingComma": "none",
  "semi": true,
  "arrowParens": "always"
}

8. 验证

• .githooks/pre-commit 存在且可执行
• git config core.hooksPath 输出 .githooks
• package.json 中的 prepare 脚本会设置 core.hooksPath
• .lintstagedrc 存在
• biome.json 存在（或已找到现有的 Biome 配置）
• 如果接受了 Prettier，则 Prettier 配置存在
• 运行 npx lint-staged，验证其能正常工作

9. 提交

只暂存此设置创建或修改的文件：.githooks/、.lintstagedrc、格式化工具配置、package.json 和锁文件。如果存在其他未提交的更改且当前分支是默认分支，请在提交前询问。提交说明中应注明安装的工具，例如 Add git hooks via core.hooksPath (lint-staged + biome)。

提交时会运行新的 pre-commit 钩子，这是验证一切正常的良好冒烟测试。

备注

• core.hooksPath 会完全覆盖 .git/hooks/；其中的钩子将不再运行
• prepare 脚本需要存在 Git 仓库；在非 Git 环境中运行 npm install 会失败，除非添加保护（例如，在已发布的包中使用 prepare": "git rev-parse && git config core.hooksPath .githooks || true"）
• Biome 的 check 会一次运行格式化和 lint；--no-errors-on-unmatched 可在没有暂存受支持文件时避免 lint-staged 输出提示
• Prettier 只处理 Biome 不处理的文件，因此两者不会争相处理同一个文件
• pre-commit 会先运行 lint-staged（速度快，仅处理已暂存文件），然后运行完整的类型检查和构建
• 如果团队需要 pre-commit 之外的更多功能（并行步骤、无需 lint-staged 的按 glob 运行器），建议将 lefthook 作为下一步选择；Husky 只是在 core.hooksPath 已具备的功能上增加了便捷封装