CaptainHook 需手动运行 ./vendor/bin/captainhook install 初始化，否则钩子不生效；常见失效原因包括权限不足、captainhook.json 中 enabled 为 false、triggered_by 不匹配文件类型、路径错误或 Windows 换行符问题。

CaptainHook 不是 Composer 的内置功能，它只是个 PHP 包；靠 Composer 安装，但钩子是否生效、何时运行、跑什么命令，全由 captainhook.json 和 .git/hooks/ 下的脚本决定——装完不等于能用，漏掉任一环节都会静默失效。

composer require --dev captainhook/captainhook 装完为什么没反应？

因为 Composer 只负责把包放进 vendor/，不会自动写入 Git 钩子文件。常见错误现象是：执行 git commit 时完全没检查、没报错、也没提示，像没装一样。

• --dev 必须加，否则会进生产依赖，CI 环境可能跳过加载
• 二进制入口在 vendor/bin/captainhook，不是全局命令，直接敲 captainhook 会报 command not found
• 如果项目 composer.json 中 "scripts" 是空对象或被清空，captainhook install 的自动初始化阶段会被跳过
• 必须手动运行一次 ./vendor/bin/captainhook install 才会生成 captainhook.json 并往 .git/hooks/ 写脚本

pre-commit 钩子配置后不执行 php-cs-fixer 怎么排查？

最常卡在权限、路径、触发条件三处。不是配置写错了，而是脚本根本没被 Git 调起，或调起了但命令崩了没输出。

One-click installation of GitHub projects

GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。

下载

• .git/hooks/pre-commit 文件必须存在，且有可执行权限：chmod +x .git/hooks/pre-commit
• captainhook.json 里 "pre-commit" 的 "enabled" 得设为 true，默认是 false
• "triggered_by" 列表要匹配你改的文件后缀，比如只写 ["php"]，但你改的是 .js，就不会触发
• "action" 命令中的路径必须相对项目根目录，./vendor/bin/php-cs-fixer 比 php-cs-fixer 更可靠（避免环境 PATH 差异）
• 加 --dry-run 和 --using-cache=no，前者防止误改文件，后者避免缓存导致漏检

如何让新成员 clone 后自动启用钩子？

靠 composer.json 的 post-install-cmd 和 post-update-cmd，但得注意执行顺序和权限问题。

• 在 scripts 里加上："post-install-cmd": "captainhook install" 和 "post-update-cmd": "captainhook install"
• 别写成 vendor/bin/captainhook install —— Composer 脚本执行时，vendor/bin 不一定在 $PATH 里，直接写 captainhook install 即可（Composer 会自动 resolve）
• 如果团队用 Windows，.git/hooks/ 下的 shell 脚本可能无法执行，建议统一用 WSL 或明确文档要求 bash 环境
• 钩子文件本身不进 Git（.git 目录默认被忽略），所以共享靠的是 captainhook.json + 自动 install 流程，不是复制脚本

captainhook.json 里 action 能否复用 composer.json 的 scripts？

不能直接复用。CaptainHook 的 action 是 shell 命令，而 composer run xxx 是另一层封装；强行混用容易因工作目录、环境变量、交互模式出问题。

• 想复用逻辑，推荐把检查命令抽成独立脚本（如 bin/check-code-style），再在 captainhook.json 中调用它
• 如果坚持用 composer run，务必加 --no-interaction 和 --no-ansi，否则遇到提示会卡住提交
• phpunit 这类命令可以直写，但 composer test 就不行——因为 CaptainHook 不解析 composer.json 的 scripts 字段
• 性能敏感场景下，避免在 pre-commit 里调 composer run 再启动 PHP 解释器两次（一次进 Composer，一次进你的脚本）

真正容易被忽略的点是：.git/hooks/ 下的文件权限和换行符。Mac/Linux 上没问题，Windows 用户 clone 后常因 CRLF 导致脚本解析失败，且 chmod 不生效；这时候得靠 git config core.autocrlf input 统一处理，或者改用 brainmaestro/composer-git-hooks 这类更健壮的替代方案。