如何配置Composer以映射PHP文件后缀路径？

本文共计898个文字，预计阅读时间需要4分钟。

Composer 本身没有机制将 .php 文件映射为可执行入口、自动加载目标或安装路径的一部分。您看到的 vendor/bin/xxx 脚本可以直接运行，是因为 Composer 在安装时为依赖的命令行工具生成了这些脚本。这是由于 Composer 在生成这些脚本时使用了死代码（dead code），导致它们不会影响程序的逻辑。

具体来说，Composer 会将依赖的命令行工具路径硬编码到这些脚本中，并确保这些路径指向正确的安装位置。由于这些路径在脚本中是固定的，它们不会因为程序的逻辑变化而改变，因此可以直接运行这些脚本。

vendor/bin 下脚本为什么没 .php 后缀？

这是 Composer 的硬编码行为：所有通过 bin 配置项注册的命令（如 "phpunit": "phpunit/phpunit"），在 vendor/bin/ 目录下生成的是无后缀的可执行文件（Linux/macOS）或 .bat（Windows）。它不是靠后缀识别，而是靠文件头 shebang 或批处理逻辑启动 PHP 解释器。

• Linux/macOS 上，vendor/bin/phpunit 开头是 #!/usr/bin/env php，内核靠这个定位解释器
• Windows 上，vendor/bin/phpunit.bat 内容是 @php "%~dp0phpunit" %*，不依赖 .php 后缀
• 如果你手动把 vendor/bin/phpunit 改成 phpunit.php，它不会自动被识别为可执行——除非你改系统关联或加 php 前缀调用
• PHP CLI 模式下，php xxx.php 和 php xxx 效果一致；后缀只是约定，不是强制要求

想让自定义脚本走特定 PHP 版本，别动后缀，改调用方式

常见需求其实是“让某个 .php 脚本用 PHP 8.2 运行”，但错误做法是给它加后缀再指望 Composer 管理。正确路径是控制执行时的解释器：

• 不要重命名脚本为 mytool.php 然后期待 composer run mytool 自动识别——composer run 只认 scripts 里定义的命令，且仍走当前 PHP_BINARY
• 临时指定：直接用完整 PHP 路径调用 /opt/homebrew/bin/php82 mytool.php
• 绑定到 composer.json 的 scripts：写成 "mytool": "/opt/homebrew/bin/php82 mytool.php"（注意路径必须绝对，避免 CI 中失败）
• 若脚本需 autoload，确保它 require __DIR__ . '/third-party/autoload.php';（如果改了 vendor-dir）

容易被忽略的点：shebang 行里的 php 不受 PHP_BINARY 影响

你在项目里写了个 bin/deploy，开头是 #!/usr/bin/env php，然后执行 ./bin/deploy —— 这个行为完全绕过 PHP_BINARY，由 shell 查找 env php 决定用哪个 PHP。此时即使你设了 PHP_BINARY=/usr/bin/php82，也无效。

立即学习“PHP免费学习笔记（深入）”；

验证方法：运行 head -1 bin/deploy | xargs which，看它实际解析出哪个 php。真正可控的方式只有两种：php82 bin/deploy 或把 shebang 改成 #!/usr/bin/env php82（前提是系统 PATH 里有 php82 命令）。