PHP-Zstd 是原生扩展而非 Composer 包，须通过 PECL 或编译安装并依赖 libzstd；正确步骤为安装开发依赖、运行 pecl install zstd、启用 extension=zstd 并验证函数存在。
PHP-Zstd 扩展不是 Composer 包，不能用 composer require 安装
很多人搜“PHP Zstandard Composer”后直接跑 composer require，结果报错或装了个假包——php-zstd 是 PHP 的 原生扩展（extension），不是纯 PHP 类库。它依赖系统级的 libzstd，必须通过 pecl 或编译安装，Composer 只能装 zstd 的纯 PHP 模拟实现（如 datto/zstd），但性能极差、不支持流式压缩、无法对接原生 Zstandard API。
正确安装方式：用 PECL 编译并启用扩展
前提是你的 PHP 环境有 pecl 命令且已安装 php-dev（或 php-devel）和 zstd-devel（或 libzstd-dev）。
- Ubuntu/Debian：
sudo apt install php-dev libzstd-dev - CentOS/RHEL：
sudo yum install php-devel zstd-devel（或dnf） - macOS（Homebrew）：
brew install php zstd，确保pecl能找到zstd.h
然后执行：
pecl install zstd
成功后，检查 php.ini 是否自动追加了 extension=zstd；如果没有，手动添加并重启 PHP-FPM 或 Apache。
立即学习“PHP免费学习笔记（深入）”；
验证是否生效：
php -m | grep zstd<br>php -r "var_dump(function_exists('zstd_compress'));"
调用 Zstandard 的关键函数与参数陷阱
zstd_compress() 和 zstd_uncompress() 是最常用接口，但默认行为容易踩坑：
- 压缩级别默认是
1（最快，压缩比低），不是最高压缩；要高压缩比，显式传22（最大值）：zstd_compress($data, 22) - 输入数据超过 ~128KB 时，
zstd_compress()可能返回false—— 这通常是因为内存限制或zstd库版本太旧（ -
zstd_uncompress()对损坏数据会直接崩溃（segmentation fault），不是抛异常；务必先用zstd_is_compressed()校验再解压 - 不支持分块流式压缩（如边读文件边压），只能全量内存操作；大文件需自行分片 +
zstd_compress()多次调用
Composer 能装什么？只有纯 PHP fallback 方案
如果你无法安装原生扩展（比如共享主机、Docker 权限受限），可用 datto/zstd 作为降级方案：
composer require datto/zstd
但它本质是调用系统 zstd 命令行工具，依赖 exec()，且：
- 每次压缩都 fork 进程，开销巨大，吞吐量下降 10 倍以上
- 不支持自定义压缩级别（固定为
-13） - 无法处理二进制空字节（
\x00）导致截断 - Windows 下基本不可用（缺少
zstd.exe自动发现逻辑）
所以它只适合临时调试或极低频小数据场景，别当生产方案。
真正的超高压缩比（比如文本从 10MB 压到 1.2MB），必须走原生扩展 + zstd_compress($data, 22)，其他路都是绕远。扩展没装好，后面所有优化都白搭。
