gemorroj/archive7z是php对命令行7z工具的封装，需先安装p7zip-full等底层工具并验证which 7z和7z i，再通过composer安装该库；其依赖ext-zip仅用于fallback，核心功能通过shell调用实现，解压、列内容、密码处理均需确保路径权限、临时目录可用及环境变量对齐。
确认系统已装好 p7zip 命令行工具
PHP 本身不自带 7z 解析能力，gemorroj/archive7z 是对命令行 7z 或 7zz 的封装，不是纯 PHP 实现。没装底层工具，库加载了也跑不动。
- Ubuntu/Debian：
sudo apt install p7zip-full p7zip-rar（p7zip-rar非必需，但解 RAR 时有用） - CentOS/RHEL 8+：
sudo dnf install p7zip-plugins；RHEL 7 先装 EPEL：sudo yum install epel-release && sudo yum install p7zip - 验证是否可用：
which 7z必须有输出；再试7z i | head -n 3看是否打印支持格式列表 - Alpine 用户注意：
apk add --no-cache p7zip，别只装zlib-dev——那只是编译依赖，不是运行时工具
用 Composer 安装 gemorroj/archive7z 并检查扩展兼容性
这个包依赖 ext-zip 仅用于 fallback 场景（比如临时解压 ZIP 包里的元数据），但它本身不靠 ZipArchive 工作。不过 Composer 自身安装过程会用到它，所以仍需确保 ZipArchive 可实例化。
- 运行
php -r "new ZipArchive(); echo 'OK';"不报错才算真正可用；php -m | grep zip成功不代表能用 - 装包：
composer require gemorroj/archive7z；若失败，先查php --ini对应的php.ini是否启用了extension=zip - 该库默认调用
7z，但某些环境（如旧版 Alpine）只有7zz，可手动指定：$archive = new \Archive7z\Archive7z('/usr/bin/7zz');
Archive7z 基本操作：解压、列出内容、带密码处理
它提供面向对象接口，但底层仍是 shell 调用，所以路径、权限、临时目录问题必须前置排查。
- 解压到指定目录：
$archive->extract('/path/to/archive.7z', '/target/dir');——目标目录需存在且可写 - 列出压缩包内容：
$archive->listContent('/path/to/archive.7z');返回数组，含文件名、大小、修改时间 - 解密带密码的 7z：
$archive->setPassword('your-pass');再调用extract()；密码错误会抛RuntimeException，不是静默失败 - 注意：不支持流式解压；大文件解压时，
proc_open超时可能触发异常，建议设ini_set('max_execution_time', 300)
常见故障点：临时目录权限、SELinux、Docker 中的路径映射
报错如 failed to open stream 或 Permission denied，90% 不是代码问题，而是环境卡点。
- Linux 默认用
/tmp作临时工作区，df -h /tmp和df -i /tmp都得看；满或 inodes 耗尽就挂 - Docker 容器里跑 PHP，宿主机
/tmp映射进容器后可能被覆盖为只读，改用TMPDIR=/var/tmp php your-script.php - SELinux 启用时，
7z被限制访问某些路径，临时关 SELinux 测试：setenforce 0；长期方案是加策略：audit2allow -a - 别在
/proc、/sys或 NFS 挂载点下解压——7z会因stat或openat失败直接退出
7z 命令路径、php.ini 加载、TMPDIR 环境变量，三者都得对齐；换一个就可能从本地 OK 变成线上报错。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
