name: setup-pre-commit description: "在当前仓库配置 Husky 提交前钩子，结合 lint-staged（Prettier）、类型检查和测试。用户希望加入提交前钩子、配置 Husky/lint-staged 或提交时格式化、类型检查、测试时使用。"
第 35 课 / setup-pre-commit
在保存提交前运行项目检查
它配置 Husky 和 lint-staged，让暂存文件格式检查及已有类型、测试命令进入提交前流程。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
在关系图中查看 setup-pre-commit 与其他技能的关联 →
一 / 读这一课之前
先把必要的概念讲清楚
提交前钩子把一些快速质量检查放在保存 Git 提交之前。它帮助你理解代码格式、类型检查、测试各自提供什么证据，以及自动流程怎样组合。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
hook｜事件发生时自动运行的钩子
在某个时点运行的脚本，例如 Git 提交前执行检查，或 Claude 使用命令工具前检查命令。它把规则变成可自动执行的动作。钩子覆盖什么取决于注册事件、匹配范围和运行环境，并不因安装一个脚本就控制所有工具。
Git、commit、branch｜版本与分支
Git 记录项目随时间的变化；commit 是一次有标识的修改记录；branch 是一条可继续发展的工作线。你可在功能分支试做收藏能力，验证后再合入主分支。保存了文件不等于已提交，提交了也不等于已推到服务器或已上线。
CLI｜命令行界面
通过输入文字命令操作程序，例如运行测试或检查 Git 状态。它与点按钮一样是操作入口，只是参数更容易记录、重复执行。读命令时先分清程序名、子命令、选项和目标路径；看懂命令不等于已执行它。
package / dependency｜代码包与依赖
package 是可以统一安装、导入或管理的一组代码；dependency 是当前程序需要的其他代码。开发依赖常用于检查和构建。安装了一个包只说明代码可取得，还要配置并调用，才会实际参与工作。
CI｜持续集成检查
把修改提交到共享流程时，自动运行测试、类型检查等约定检查，尽早发现集成问题。绿灯表示配置的检查通过，不代表所有需求都正确；红灯也可能由环境故障导致，应看具体证据。需要先检查“配置了什么”，才能解释绿灯的意义。
二 / 中英全文对照与精讲
读原文，理解每一步为什么这样做
左右内容按小节对应；窄屏先中文、后英文。两种语言均完整展示，对应讲解紧接在小节之后。译文传达原文要求；老师讲解补充概念、原因、例子与适用边界。
中文译文English · 英文原文
name: setup-pre-commit description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
在 Git 提交之前自动检查
Setup Pre-Commit Hooks
将配置哪些能力
- 用 Husky 设置提交前钩子，让 Git 在提交之前运行指定命令。
- 用 lint-staged 让 Prettier 处理本次已暂存的文件。
- 项目缺少时，添加 Prettier 格式配置。
- 在钩子中加入类型检查和测试脚本。
What This Sets Up
- Husky pre-commit hook
- lint-staged running Prettier on all staged files
- Prettier config (if missing)
- typecheck and test scripts in the pre-commit hook
老师讲解 · 对应上方原文 · 含教学举例
三个工具和两类检查，各自做什么
Husky 管理 Git 钩子；lint-staged 选取已暂存、准备进入提交的文件；Prettier 负责格式化。typecheck 检查类型关系，test 运行测试。它们不是同一个“质量分数”。
例如缺一个分号可能由格式化处理；把字符串误当数字可能被类型检查发现；收藏重复产生两条记录，需要合适的行为测试。没有哪一个工具自动覆盖全部需求。
暂存区是本次准备提交的内容集合，不一定等于工作目录所有修改。理解这一点，才能看懂 staged-only 的范围。
提交前钩子：把检查放进一个会自动发生的时机
hook 是在特定动作发生时，由工具自动调用的程序。 这篇把检查安排在 Git 提交之前，减少每次都靠人记住命令的负担。
假设 AI 改了收藏页面并准备提交。Husky 先执行钩子，lint-staged 找到准备提交的文件，Prettier 整理格式，之后运行类型检查和测试。出现错误时，需要先处理，再继续提交。
暂存区表示你选定要纳入这次提交的改动，并非工作目录中一切内容。格式正确、类型正确、功能正确也不是同一件事：Prettier 不会证明刷新后收藏仍然存在，测试才检查被覆盖的行为。
项目没有测试脚本时，省略该行不等于自动获得测试能力。报告应明确实际检查了什么，不能将一次提交成功概括为全部功能正确。
配置步骤
Steps
1. 识别包管理工具
按已有锁文件判断：package-lock.json 对应 npm，pnpm-lock.yaml 对应 pnpm，yarn.lock 对应 yarn，bun.lockb 对应 bun。使用找到的工具；无法判断时，默认 npm。
1. Detect package manager
Check for package-lock.json (npm), pnpm-lock.yaml (pnpm), yarn.lock (yarn), bun.lockb (bun). Use whichever is present. Default to npm if unclear.
老师讲解 · 对应上方原文 · 含教学举例
沿用项目工具，避免混用锁文件和命令
锁文件记录依赖解析结果，帮助团队获得一致版本。根据已有锁文件识别 npm、pnpm、yarn 或 bun，可以避免随意混用造成不同安装状态。
初始化 Husky 会增加目录和 prepare 脚本，随后写 pre-commit 内容。如果项目没有 typecheck 或 test 脚本，原文要求省略并告知，而不是调用不存在的命令再声称已配置。
配置文件已存在时保留其规则，不能为了一份默认模板覆盖项目格式习惯。
2. 安装依赖
将下列工具作为开发依赖安装：
husky lint-staged prettier
2. Install dependencies
Install as devDependencies:
husky lint-staged prettier
3. 初始化 Husky
npx husky init
这会创建 .husky/，并在 package.json 加入 prepare: "husky"。
3. Initialize Husky
npx husky init
This creates .husky/ dir and adds prepare: "husky" to package.json.
4. 创建 .husky/pre-commit
写入下面内容。本文说明 Husky v9 及以后无需在钩子顶部写 shebang 解释器声明：
npx lint-staged
npm run typecheck
npm run test
按前面识别的工具替换 npm。若项目没有 typecheck 或 test 脚本，省略对应行，并告诉用户缺少哪项。
4. Create .husky/pre-commit
Write this file (no shebang needed for Husky v9+):
npx lint-staged
npm run typecheck
npm run test
Adapt: Replace npm with detected package manager. If repo has no typecheck or test script in package.json, omit those lines and tell the user.
5. 创建 .lintstagedrc
{
"*": "prettier --ignore-unknown --write"
}
5. Create .lintstagedrc
{
"*": "prettier --ignore-unknown --write"
}
6. 缺少配置时创建 .prettierrc
只有项目没有 Prettier 配置，才采用以下默认值：
{
"useTabs": false,
"tabWidth": 2,
"printWidth": 80,
"singleQuote": false,
"trailingComma": "es5",
"semi": true,
"arrowParens": "always"
}
6. Create .prettierrc (if missing)
Only create if no Prettier config exists. Use these defaults:
{
"useTabs": false,
"tabWidth": 2,
"printWidth": 80,
"singleQuote": false,
"trailingComma": "es5",
"semi": true,
"arrowParens": "always"
}
7. 实际验证
- [ ]
.husky/pre-commit存在且可执行。 - [ ]
.lintstagedrc存在。 - [ ]
package.json的prepare脚本为"husky"。 - [ ] 存在 Prettier 配置。
- [ ] 运行
npx lint-staged，确认可正常工作。
7. Verify
- [ ]
.husky/pre-commitexists and is executable - [ ]
.lintstagedrcexists - [ ]
preparescript in package.json is"husky" - [ ]
prettierconfig exists - [ ] Run
npx lint-stagedto verify it works
老师讲解 · 对应上方原文 · 含教学举例
钩子能运行，与项目已经充分验证不同
验证文件存在、可执行、脚本名称正确，并运行 lint-staged，能发现一部分配置错误。实际提交再触发钩子，是一次整体冒烟检查。
钩子在本地运行，不能自动取代服务器端 CI。不同环境可能没安装或绕过本地钩子，因此共享质量要求通常还需对应自动检查。
如果完整测试非常慢，每次提交都运行可能影响节奏。原文给的是作者默认组合，实际工程应基于成本和风险选择检查位置，而不是机械增加等待时间。
8. 提交配置
将本次修改或创建的文件加入暂存区，提交消息使用 Add pre-commit hooks (husky + lint-staged + prettier)。
这次提交会实际触发新钩子，因此也构成一次基本运行检查。
8. Commit
Stage all changed/created files and commit with message: Add pre-commit hooks (husky + lint-staged + prettier)
This will run through the new pre-commit hooks: a good smoke test that everything works.
补充说明
- 本文采用的 Husky v9 及以后不需要钩子文件的 shebang。
prettier --ignore-unknown跳过无法解析的文件，例如图片。- 先运行只处理暂存文件、通常较快的 lint-staged，再运行完整类型检查和测试。
Notes
- Husky v9+ doesn't need shebangs in hook files
prettier --ignore-unknownskips files Prettier can't parse (images, etc.)- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
格式检查全通过，能说明需求已经实现吗？
我已思考，查看参考思路
不能。格式检查只覆盖可机械判定的格式问题；需求还需要行为验证或内容核验。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 35 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：Agent 写了一个无法解析的文件，格式或类型检查可以在提交时失败；但“教材讲错了概念”通常不会被这些工具发现，需要内容审查。
边界与容易误读的地方
全套测试很慢时，提交钩子可能成为负担。需要权衡反馈时机，不能因为装了工具就宣布质量问题解决。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。