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 "GuzzleHttp\Client" 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。
