pecl install cassandra 在 phpenv 下大概率失败，主因是依赖链断裂：phpenv 编译的 PHP 不识别非标准路径下的 libcassandra.so，且 PECL 构建不自动注入 -L/-I 参数，导致 configure 找不到 libuv、cassandra.h 或出现符号未定义错误。
phpenv 本身不提供 Cassandra 驱动安装能力，它只是 PHP 版本管理工具。想让 phpenv 管理的 PHP 实例连接 Cassandra，必须手动编译并启用 cassandra 扩展——而这个过程极易失败，核心原因不是配置错，而是依赖链断裂。
为什么 pecl install cassandra 在 phpenv 下大概率失败
PECL 安装 cassandra 扩展时，会尝试链接系统级的 libcassandra.so（来自 DataStax C/C++ driver），但 phpenv 编译的 PHP 默认不识别非标准路径下的动态库，且 PECL 构建过程不会自动注入 -L/usr/local/lib64 或 -I/usr/local/include/cassandra 这类关键参数。
常见报错包括：
-
configure: error: Unable to load libuv——libuv装了但没被pkg-config发现，或版本不匹配（如 v1.4.x 与 cpp-driver v2.15+ 不兼容） -
fatal: cannot open file '/include/cassandra.h' for reading—— cpp-driver 没装，或装了但头文件没软链到系统 include 路径 -
undefined symbol: uv_print_all_handles——libuv版本太新（v1.40+），而旧版 cpp-driver 源码里调用了已被移除的调试函数
实际可行的安装路径：绕过 PECL，用源码 + 显式路径编译
适用于 phpenv 管理的任意 PHP 版本（如 7.4.33、8.1.27），前提是已用 phpenv install 成功编译该版本。
操作要点：
立即学习“PHP免费学习笔记（深入）”；
- 先装好 cpp-driver（推荐 v2.15.2）：从 GitHub release 页面 下载源码，
mkdir build && cd build && cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local，再sudo make install - 确认
/usr/local/lib64/libcassandra.so.2和/usr/local/include/cassandra.h存在；若只有/usr/lib64/下的，加软链：sudo ln -sf /usr/lib64/libcassandra.so.2 /usr/local/lib64/ - 下载对应 PHP 版本的
cassandra扩展源码（如 PHP 8.1 →cassandra-1.7.0），解压后执行：PATH=$(phpenv which phpize):$PATH phpize<br>./configure --with-cassandra=/usr/local<br>make<br>sudo make install
- 在
phpenv当前版本的php.ini中添加：extension=cassandra.so；注意不是php_cassandra.dll（Windows 才用）
phpenv 下连接 Cassandra 的最小可用代码
扩展加载成功后，不能直接用 PDO——Cassandra 没有 PDO 驱动。必须用原生 Cassandra\Cluster 类：
$cluster = Cassandra::cluster()
->withContactPoints(['127.0.0.1'])
->withPort(9042)
->build();
$session = $cluster->connect('mykeyspace');
关键点：
-
withContactPoints()必须是 IP 字符串数组，不支持域名或localhost（某些 libcassandra 版本会解析失败） - 默认端口是
9042，不是3306或5432；若改过 cassandra.yaml 中的native_transport_port，这里必须同步 - 连接前确保 keyspace 已存在，
connect('nonexistent')会抛Cassandra\Exception\RuntimeException，不是 PDO 那种静默失败
环境变量和多实例部署的坑
如果你用 phpenv 切换多个 PHP 版本，每个版本都需单独编译 cassandra.so，因为扩展是 ABI 绑定的。别试图共用一个 .so 文件。
另外，phpenv 默认不接管 LD_LIBRARY_PATH，所以即使 libcassandra.so.2 在 /usr/local/lib64，PHP 运行时仍可能找不到它。临时解决：
- 启动 PHP 前运行：
export LD_LIBRARY_PATH="/usr/local/lib64:$LD_LIBRARY_PATH" - 或写入
/etc/ld.so.conf.d/cassandra.conf并执行sudo ldconfig - 检查是否生效：
php -r "echo Cassandra::version();"—— 输出类似1.7.0才算真正就位
最常被忽略的是：cpp-driver 和 cassandra-PHP 扩展的版本必须严格对齐。比如 PHP 8.2 + cassandra-1.8.0 就要求 cpp-driver ≥ v2.16.0，低一个 patch 版都可能触发段错误。查版本别只看 PECL 页面，得翻 GitHub Release note 里的 “Compatibility” 小节。
