Composer怎么安装Captain Hook_Composer如何引入captainhook管理Git钩子配置【教程】-composer-PHP中文网

Composer 仅用于安装 captainhook/captainhook 包，CaptainHook 需手动初始化配置、启用钩子、配置 Git hooks 脚本并验证执行；默认配置全禁用，须编辑 captainhook.json 启用如 pre-commit 并确保 .git/hooks/ 下脚本存在且可执行。

composer怎么安装captain hook_composer如何引入captainhook管理git钩子配置【教程】

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"
        }
      ]
    }
  }
}

注意：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

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。整个过程不依赖全局安装，但极度依赖项目级路径和权限设置——这也是多人协作时最容易出问题的地方。