composer如何为CLI应用构建独立PHAR包？（结合box与composer依赖）

box是当前最靠谱的phar打包工具，因其能正确处理autoload、类映射、依赖嵌入与签名，并自动重写__dir__和路径常量，避免运行时class not found等错误。

为什么 box 是当前最靠谱的 PHAR 打包工具

因为 composer 本身不打包，box 是少数能正确处理 autoload、类映射、依赖嵌入和签名的 CLI 工具。它直接读取 composer.json，把 vendor/ 里的东西按需压缩进 PHAR，还能自动重写 __DIR__ 和路径常量——这点其他脚本工具（比如纯 PHP 手写 Phar::buildFromDirectory）很容易漏掉，导致运行时报 Class not found 或 file not found。

常见错误现象：phar://xxx.phar/vendor/autoload.php 被加载了，但里面 require 的路径还是指向原始 vendor 目录，一执行就报错。

• 必须用 box compile（不是 build），它会触发自动路径重写
• 确保 composer.json 中 "bin" 字段声明了主入口文件（如 "bin/myapp"），box 依赖这个找启动脚本
• PHP 版本要跟目标运行环境一致；box 默认用当前 PHP 编译 PHAR，如果用了 ext-sockets 这类扩展，打包机没装就会静默失败

如何让 box 正确包含 Composer 依赖

box 不是“复制 vendor”，而是解析 composer.lock + autoload 配置，把实际用到的类文件打包进去。所以它能剔除未引用的依赖，但前提是你的代码里真调用了那些类——静态分析做不到 100% 准确，尤其涉及反射、字符串类名或 class_exists 的情况。

使用场景：你写了命令行工具，依赖 symfony/console 和 guzzlehttp/guzzle，但只在某个子命令里用到了 Guzzle；默认配置下 box 可能不打包 Guzzle，运行时报 Class "GuzzleHttpClient" not found。

• 在 box.json 里显式加 "files" 列表，把关键依赖入口文件列进去，比如 "vendor/guzzlehttp/guzzle/src/Client.php"
• 或者设 "whitelist": ["**/*.php"]（慎用，会增大体积）
• 检查 composer.json 的 "autoload" 是否含 "psr-4" 映射；如果用了 "files" 自动加载，box 默认不处理，得手动加进 "files" 字段

box.json 必须配对的关键字段

很多失败源于 box.json 没对齐项目结构。它不像 webpack 配置那么灵活，字段名错一个、路径少个 /，编译就通过但运行出错。

参数差异："main" 指向的是 PHAR 内部的入口路径（不是磁盘路径），而 "output" 是生成后的文件名；"compression" 设成 "GZ" 时，某些老旧 linux 环境的 PHP 会因没开 zlib 扩展直接拒绝执行。

• "main" 值必须是相对于项目根目录的路径，且该文件第一行得是 #!/usr/bin/env php（否则 windows 下双击打不开，Linux 下 ./myapp.phar 报权限错）
• "alias" 推荐设成 "myapp.phar"，不然 Phar::getAlias() 返回空，某些框架检测逻辑会崩
• "chmod" 设为 "0755"，否则生成的 PHAR 在某些 CI 环境里不可执行

PHAR 运行时报 PharException: phar "/xxx.phar" has a broken signature 怎么办

这是签名验证失败，不是文件损坏。原因通常是：你在开发机上用 box sign 签了名，但目标机器没装对应私钥，或签名算法被禁用（如 PHP 8.2+ 默认禁用 SHA1）。

性能影响：签名本身不拖慢执行，但每次运行都会校验，如果 PHAR 很大（>50MB），校验耗时明显；兼容性上，SHA256 最稳妥，OPENSSL 签名需要目标机有 openssl 扩展且证书可信。

• 开发阶段先关签名："signing" 设为 "false"，确认功能正常后再开
• 要用签名，就统一用 "algorithm": "SHA256"，别碰 "OPENSSL" —— 它依赖外部证书链，CI/容器里极难维护
• 如果必须用 OpenSSL，私钥不能密码保护，且 "private-key" 路径必须是绝对路径（box 不支持相对路径）

最容易被忽略的是：PHAR 文件权限和 shebang 行。哪怕签名、依赖、路径全对，少了 #!/usr/bin/env php 或 chmod 没给执行位，Linux/macos 下就只能 php myapp.phar，不能直接 ./myapp.phar。