Composer如何分发CLI工具为PHAR_Composer分发CLI工具为PHAR方法

Composer 不支持直接安装 .phar 文件，因其仅处理 Packagist 注册的含 composer.json 的 PHP 包；.phar 是构建产物，无版本管理与自动加载机制。正确方式为手动下载、授权并放入系统路径，或用 humbug/box 打包。

为什么不能用 composer require xxx.phar

如果你尝试直接运行 composer require php-cs-fixer.phar，大概率会看到这样的报错：Could not find a matching version of package php-cs-fixer.phar。这可不是拼写问题，根本原因在于 Composer 的设计逻辑——它压根就不认识 .phar 这个后缀。Composer 的核心职责是管理 Packagist 上注册的、带有标准 composer.json 的 PHP 包。而 .phar 文件呢？它本质上是一个构建产物，一个已经打包好的“成品”，既没有版本约束，也谈不上依赖解析或自动加载。

很多开发者容易在这里踩坑：听说“可以用 Composer 安装 PHAR 工具”，就去满世界搜索带 .phar 的包名，结果无一例外全都失败。这其实是混淆了两个概念：“分发方式”和“安装方式”。

• 通过 Composer 分发 CLI 工具，靠的是在包的 composer.json 里声明一个 "bin" 字段（比如大家熟知的 phpstan/phpstan），而不是直接把工具打包成 PHAR 上传。
• 当你执行 composer global require phpstan/phpstan 时，下载的其实是源码压缩包，Composer 会自动将 bin 字段里声明的脚本软链接到全局路径（如 ~/.composer/vendor/bin/）。整个过程，跟 PHAR 文件没有直接关系。
• 至于工具作者内部是不是用 PHAR 来打包入口文件，对使用者来说是透明的。你只需要关心命令能否执行，Composer 会帮你处理好自动加载和路径注册这些底层细节。

只有独立 .phar 文件时，该怎么做

如果你手头已经有一个现成的独立 PHAR 文件，比如 php-cs-fixer.phar 或 box.phar，这时候就别再想着让 Composer 帮忙了——它不仅帮不上忙，还可能让你在配置仓库和修改设置上白费功夫。

正确的做法，回归到最经典的 Unix 哲学：下载、授权、放入路径。就这么简单。

• 下载：curl -Lo php-cs-fixer.phar https://cs.symfony.com/download/php-cs-fixer-v3.phar
• 加执行权限：chmod +x php-cs-fixer.phar
• 移到系统路径：例如，sudo mv php-cs-fixer.phar /usr/local/bin/php-cs-fixer
• 验证：运行 php-cs-fixer --version（注意，这里不需要在前面加 php 命令，因为文件内部已经包含了 shebang 解释器声明）。

对于 Windows 用户，这里有个关键提醒：.phar 文件在 Windows 上并非原生可执行文件，直接双击肯定会失败。你必须显式地通过 PHP 解释器来调用，比如 php php-cs-fixer.phar --version，或者在批处理脚本里写死路径：php "%~dp0php-cs-fixer.phar"。

想自己把项目打包成 PHAR，用 humbug/box 而不是 Composer

Composer 本身并不参与 PHAR 的构建过程。真正负责打包的，是 humbug/box 这类专门工具。它的工作流程是：读取 box.json 配置文件，扫描项目源码，合并 vendor 目录依赖，生成存根（stub），最后进行压缩和签名——整个过程完全绕开了 Composer 的依赖管理逻辑。

所有关键的配置选项都在 box.json 里设置，而不是 composer.json：

• "main": "bin/myapp"：这个路径必须指向一个包含 #!/usr/bin/env php 头的可执行入口文件，不能是普通的 .php 脚本。
• "install": false：这个设置很重要，它会强制关闭 Box 自动运行 composer install 的行为，否则开发依赖（require-dev）也会被打包进去。
• "exclude-composer-files": true：启用后会自动剔除 composer.lock 和元数据文件，有助于减小 PHAR 体积。
• 打包前的最佳实践是手动运行：composer install --no-dev --optimize-autoloader，然后记得删除 vendor/composer/autoload_dev.php 文件。

一切就绪后，执行 box compile。最终生成的 myapp.phar 就是一个完全自包含的“二进制”文件，不依赖宿主机上的 vendor 目录或 composer.json。

PHAR 运行时报 Class not found 怎么查

遇到运行时提示类找不到，问题通常不在于类文件没打进包，而是自动加载器（autoloader）混淆了开发环境和生产环境的路径。Box 默认会加载 vendor/autoload.php，但如果这个文件内部还引用了仅用于开发的 autoload-dev，而对应的开发文件又被排除在打包列表之外，映射自然就失效了。

最直接的排查步骤可以这样来：

• 解包检查：使用命令 php -d phar.readonly=0 -r '$p = new Phar("myapp.phar"); foreach ($p as $f) { echo $f->getFileName()."\n"; }' 列出 PHAR 内所有文件，确认关键类是否存在。
• 确认开发文件已剔除：检查打包后的 PHAR 内是否还存在 vendor/composer/autoload_dev.php。
• 审查自动加载器：确认 vendor/autoload.php 里没有类似 require __DIR__.'/autoload_dev.php' 这样的语句。
• 开启详细错误：运行时加上 -d display_errors=1 参数，获取完整的报错路径：php -d display_errors=1 myapp.phar --version。

最容易忽略的两个坑是：第一，在运行 box compile 之前，没有彻底清理掉 autoload_dev.php；第二，box.json 里漏写了 "install": false 配置，导致 Box 自作主张又运行了一次 composer install，把本应排除的开发依赖重新拉了回来。