Composer 仅用于安装 captainhook/captainhook 包，CaptainHook 需手动初始化配置、启用钩子、配置 Git hooks 脚本并验证执行；默认配置全禁用，须编辑 captainhook.json 启用如 pre-commit 并确保 .git/hooks/ 下脚本存在且可执行。
Composer 本身不提供 CaptainHook，它只是用来安装和管理 PHP 包的工具；CaptainHook 是一个独立的 Git 钩子管理器，需通过 Composer 安装其 PHP 包，并配合本地 Git 配置才能生效。
用 Composer 安装 captainhook/captainhook
直接运行以下命令即可把 captainhook/captainhook 作为开发依赖加入项目：
composer require --dev captainhook/captainhook
注意两点：
-
--dev是必须的，因为 Git 钩子只在开发环境运行，不应进入生产依赖 - 安装后，二进制文件会出现在
vendor/bin/captainhook，不是全局命令，不能直接敲captainhook—— 后续要用相对路径或配置$PATH - 如果项目已禁用脚本执行（如
composer.json中"scripts": {}为空或被清空），captainhook的自动初始化可能跳过，需手动触发
初始化 captainhook 配置文件（captainhook.json）
安装完不等于能用，必须生成配置文件。运行：
vendor/bin/captainhook init
它会创建默认的 captainhook.json，但这个默认配置是“全关闭”状态：所有钩子都设为 "enabled": false。常见误操作是以为装完就能拦截 commit，结果毫无反应——其实是没启用任何 hook。
你需要手动编辑 captainhook.json，例如启用 pre-commit 并绑定一个 PHP 脚本：
{
"hooks": {
"pre-commit": {
"enabled": true,
"commands": [
{
"command": "php ./scripts/check-staged.php"
}
]
}
}
}
注意：
-
commands数组里每个command字段是 shell 命令字符串，不是函数调用，路径必须可被 Git 进程访问（推荐用相对项目根目录的路径） - 不要写成
php scripts/check-staged.php（缺./），否则在某些 Git 环境下会找不到文件 - 配置文件必须放在项目根目录，且文件名严格为
captainhook.json（大小写敏感）
让 Git 知道该用 captainhook 处理钩子
CaptainHook 不会自动改写 .git/hooks/ 下的脚本，它靠 Composer 脚本 + Git 模板机制联动。最可靠的方式是：在 composer.json 的 scripts 中注册 post-install-cmd 和 post-update-cmd：
"scripts": {
"post-install-cmd": ["CaptainHook\Composer\Installer::createHooks"],
"post-update-cmd": ["CaptainHook\Composer\Installer::createHooks"]
}
这样每次 composer install 或 update，都会自动在 .git/hooks/ 下生成对应 shell 包装器（如 pre-commit 文件），内容是调用 vendor/bin/captainhook 并传入当前钩子名。
容易忽略的点：
- 如果之前手动写过
.git/hooks/pre-commit，它会被CaptainHook的 installer 覆盖——这是设计行为，不是 bug - Windows 用户要注意：Git for Windows 默认用 MSYS2 shell，而
captainhook生成的 hook 脚本是 bash 风格，一般能跑；但如果启用了 Windows Subsystem for Linux（WSL），Git CLI 可能走不同环境，导致 hook 不触发 - CI 环境（如 GitHub Actions）通常不执行 Git 钩子，所以
pre-commit类钩子在那里不会运行，别指望它替代 CI 检查
验证 hook 是否真在工作
光看配置和文件存在不够，得实测。最简单的验证方式：
- 临时在
captainhook.json的pre-commit下加一条 echo 命令："command": "echo 'HOOK FIRED!'; exit 1" - 然后执行
git add . && git commit -m "test" - 如果看到
HOOK FIRED!并且提交被中止（因为exit 1），说明链路通了
如果没反应，优先检查三处：
-
.git/hooks/pre-commit文件是否存在、是否可执行（chmod +x） - 该文件内容第一行是不是
#!/usr/bin/env php或类似 shell shebang（正常应是#!/bin/sh开头） - 运行
git config core.hooksPath，确认没指向其他自定义钩子路径，否则.git/hooks/被忽略
配置生效后，captainhook 的实际执行逻辑藏在 vendor/bin/captainhook 里，它会读取 captainhook.json、解析当前 Git 事件、按顺序执行 commands。整个过程不依赖全局安装，但极度依赖项目级路径和权限设置——这也是多人协作时最容易出问题的地方。
