Composer怎么配置Git Hooks 结合Composer自动化工作流【进阶】

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 里定义：

"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 频率和团队忍耐度反复调参。