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，把本应排除的开发依赖重新拉了回来。
