Git Hooks 文件必须放在项目根目录的 .git/hooks/ 目录下才能被 Git 识别，Composer 仅能通过插件（如 brainmaestro/composer-git-hooks）或脚本将其复制至此，且需确保无扩展名、有可执行权限（chmod +x）。
Git Hooks 文件该放在哪里才能被 Composer 自动识别
Composer 本身不直接管理 Git Hooks，它只通过 composer.json 中的 scripts 和 extra.git-hooks（需配合插件）触发或安装钩子。真正生效的钩子文件必须放在项目根目录下的 .git/hooks/ 目录里——这是 Git 唯一认的路径。Composer 只能帮你把写好的脚本“复制过去”，不能绕过这个限制。
常见错误是把钩子脚本放在 bin/ 或 scripts/ 下就以为能自动运行，结果提交时完全没反应。正确做法是用插件或自定义脚本确保内容最终落进 .git/hooks/，且文件名匹配钩子名（如 pre-commit、commit-msg），无扩展名，有可执行权限（chmod +x）。
- 手动复制后记得
chmod +x .git/hooks/pre-commit - 若用
composer install自动部署，推荐使用brainmaestro/composer-git-hooks插件，它会读取extra.git-hooks并覆盖写入 - 注意：.git 目录通常被忽略，所以钩子文件不会被 Git 跟踪——想共享配置，得把模板放
dev-tools/hooks/pre-commit这类路径，再靠插件复制
如何用 composer.json 的 scripts 字段绑定 pre-commit 钩子
composer.json 的 scripts 是执行逻辑的中心，但不能直接“注册”到 Git；它需要被外部调用。典型做法是让 pre-commit 钩子脚本本身去调用 composer run-script，从而复用已定义的命令。
例如，在 .git/hooks/pre-commit 中写：
#!/usr/bin/env bash exec composer run-script --no-ansi pre-commit-check || exit 1
然后在 composer.json 里定义：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
"scripts": {
"pre-commit-check": [
"@php -r "echo 'Running static analysis...\n';"",
"phpstan analyse --no-interaction src/",
"php-cs-fixer fix --dry-run --using-cache=no"
]
}
- 务必加
--no-interaction和--dry-run，避免交互式提示阻塞提交 - 所有命令应快速失败（exit code ≠ 0），否则钩子会中止提交
- 不要在
scripts里写长耗时操作（如全量测试），用户会失去耐心；可拆出pre-commit-light和pre-push分级执行
为什么 post-install-cmd 里 copy hook 文件经常失效
很多人在 post-install-cmd 里写 cp dev-tools/hooks/pre-commit .git/hooks/pre-commit，结果 CI 环境或 Docker 构建时失败——因为 .git 目录在某些场景下根本不存在（如 shallow clone、CI 缓存、deploy 模式）。
更健壮的做法是：只在开发环境初始化时安装钩子，而不是每次 composer install 都硬拷贝。
- 用插件（如
brainmaestro/composer-git-hooks）的hooks:install命令，显式执行一次即可 - 或者把安装逻辑放进
scripts.dev-setup，提醒团队首次克隆后运行composer run dev-setup - CI/CD 流水线应跳过钩子安装（加
if [ -d ".git" ]; then ... fi判断） - 钩子文件本身别依赖相对路径里的
vendor/bin/xxx，优先用./vendor/bin/phpunit或$(pwd)/vendor/bin/psalm避免 PATH 不一致
PHP 代码风格检查和类型分析在 pre-commit 中怎么平衡速度与覆盖率
pre-commit 阶段不是跑全量质量门禁的地方，而是拦截明显低级错误。追求 100% 覆盖率只会让开发者关掉钩子。
建议分层处理：
- 必跑项（php -l 检查语法、
php-cs-fixer --dry-run -q快速格式校验 - 可选快检项（phpstan analyse --level=1 --configuration=phpstan.neon.dist src/，只扫基础类型
- 排除项：全量测试（
phpunit）、慢扫描（psalm --diff）、构建类任务——留给pre-push或 CI - 用
git diff --cached --name-only '*.php'动态过滤变更文件，传给 PHPStan/PHPCS，大幅提速
复杂点在于：不同团队对“可接受延迟”的阈值不同。有人容忍 5 秒，有人只接受 1.5 秒——这决定了你是否要引入缓存、跳过 vendor、甚至用 parallel-lint 替代单文件 php -l。没有银弹，只有根据 commit 频率和团队忍耐度反复调参。
