应将PHP-CS-Fixer作为dev依赖安装并集成到composer.json的scripts中，如"cs:fix": "php-cs-fixer fix --verbose --diff"，再通过composer cs:fix执行格式化，配合pre-commit hook和CI脚本确保统一执行。
怎么用 Composer 调用 PHP-CS-Fixer 自动格式化代码？
Composer 本身不提供代码格式检测功能，但能帮你可靠地安装和调用 php-cs-fixer —— 这是目前 PHP 社区最稳定、规则最全的格式化工具。关键不是“写脚本”，而是把 php-cs-fixer 集成进 Composer 的 scripts 生命周期里。
在 composer.json 的 "scripts" 段落中添加：
"scripts": {
"cs:fix": "php-cs-fixer fix --verbose --diff",
"cs:check": "php-cs-fixer fix --dry-run --using-cache=no"
}这样就能直接运行 composer cs:fix 格式化全部 PHP 文件，或 composer cs:check 做只读校验（CI 场景必备）。
-
--dry-run必须配--using-cache=no，否则 CI 上可能漏报缓存命中的未格式化文件 - 默认只处理
.php文件；如需包含.inc或.module（Drupal 场景），加--path-mode=intersection和--extensions=php,inc,module - 别把
php-cs-fixer装全局 —— 用composer require --dev friendsofphp/php-cs-fixer锁定版本，避免团队成员本地环境不一致
为什么不能只靠 .php_cs.dist 规则文件就完事？
规则文件（如 .php_cs.dist）只是配置，它不决定“何时执行”“对哪些文件生效”“是否阻断提交”。真正起约束作用的是执行时机和集成方式。
常见错误是：写了规则文件，但没绑定到 Git Hook 或 CI 步骤，结果只有部分人手动跑，规范形同虚设。
- 推荐在
.php_cs.dist中显式指定目录：Finder::create()->in(['src', 'tests'])->name('*.php')，避免意外扫描 vendor 或生成文件 - 不要用
PSR12全量规则 —— 它包含一些有争议的实践（如强制单行空括号），建议从@Symfony或@PhpCsFixer基础集出发，按需增补 - 如果项目用 PHP 8.2+，注意某些规则（如
declare_strict_types）在低版本 PHP 下会报错，得加phpVersion: PhpCsFixer\Finder::PHP_82显式声明
Git pre-commit hook 怎么和 Composer 脚本联动？
靠人记着跑 composer cs:check 不现实，必须让 Git 提交前自动卡住不合规代码。最轻量的做法是用 composer exec 在 hook 里调用本地安装的命令。
在项目根目录建 .git/hooks/pre-commit（记得 chmod +x）：
#!/bin/sh if ! composer exec -- php-cs-fixer fix --dry-run --using-cache=no; then echo "❌ PHP 代码格式不合规，请先运行：composer cs:fix" exit 1 fi
这个写法比直接写 vendor/bin/php-cs-fixer 更健壮 —— composer exec 会自动识别当前项目的 vendor/bin 路径，且兼容 Windows（Git for Windows 下 vendor/bin 是批处理文件）。
- 别用
husky或lefthook等第三方 hook 工具来管 PHP 格式检查 —— 多一层抽象就多一个故障点，尤其当团队里有人用 WSL、有人用 macOS、有人用 Windows 时 - 如果项目同时有 JS/TS，再另起一套前端 lint 流程；但 PHP 格式检查务必只走 Composer 生态，避免混用
npx和composer导致 PATH 冲突 - hook 里别加
--quiet—— 出错时要看到具体哪几行不合规，否则开发者只能盲猜
CI 流水线里检测失败却没报具体文件？
GitHub Actions / GitLab CI 报错只显示 Exit code 8 或 “fixer failed”，说明输出被截断了。根本原因是 CI 默认关闭 TTY，导致 php-cs-fixer 收缩了 diff 输出。
修复方法很简单：加 --no-ansi + --verbose 组合，强制输出完整路径和变更上下文：
php-cs-fixer fix --dry-run --using-cache=no --no-ansi --verbose
另外，CI 中应禁用缓存（--using-cache=no），否则第一次构建成功后，后续 PR 可能因缓存跳过检查。
- 别在 CI 里用
composer global require安装 fixer —— 全局命令版本不可控，且不同 job 间缓存易污染 - 如果用 GitHub Actions，确保
actions/checkout@v4后执行composer install --no-interaction，否则vendor/bin/php-cs-fixer根本不存在 - 某些私有规则集（比如公司内部的
MyCompanyRules）需要额外require到autoload-dev，否则 CI 中类找不到
实际最难的不是写脚本，是让所有人提交前都真实触发检查 —— 很多团队把 pre-commit hook 放进文档，却不随项目模板自动安装，结果三年过去还是靠口头提醒。
