第三方PHP扩展正常运行需验证三件事：API版本匹配、二进制架构一致、运行时功能可用；缺一不可。
第三方PHP扩展（如 redis、swoole、grpc）是否能在当前PHP版本下正常加载并运行，不能只看“装没装上”，必须验证三件事：API版本是否匹配、二进制架构是否一致、运行时功能是否可用。缺一不可。
查PHP与扩展的module API版本是否对得上
这是最常被跳过的致命检查点。报错 Module compiled with module API=20200930, PHP compiled with module API=20190902 就是典型症状——两个数字不一致，扩展直接拒载。
- 执行
php -i | grep "PHP API"查当前PHP解释器的API编号（例如20200930对应PHP 8.1） - 执行
php-config --version && php-config --extension-dir确认你用的phpize/php-config工具链指向的是同一个PHP版本 - 若扩展是手动编译的，进入其源码目录重新跑
phpize && ./configure && make；若是PECL安装的，用pecl install redis-6.0.2显式指定带版本号的包（不要只写pecl install redis）
确认扩展文件和PHP进程架构一致
在M1/M2 Mac或ARM服务器上，加载x86_64架构的 .so 文件会静默失败或报 incompatible architecture，但错误日志可能被忽略。
- 运行
php -v看输出是否含arm64或aarch64 - 运行
uname -m看系统原生架构 - 运行
file /usr/lib/php/20200930/redis.so（路径按实际改）看扩展文件架构标识 - 三者必须全为
arm64或全为x86_64；混用时，PECL包要选带-arm64后缀的，或用本机phpize重编译
验证扩展不仅加载了，还能干活
extension_loaded('redis') 返回 true 只说明.so加载成功，不代表Redis类能用、连接能通、命令能执行。很多CI失败就卡在这步。
立即学习“PHP免费学习笔记（深入）”；
- 写一个最小验证脚本
check-redis.php：<?php if (!extension_loaded('redis')) { die("redis extension not loaded\n"); } $r = new Redis(); if (!$r->connect('127.0.0.1', 6379, 1)) { die("redis connect failed\n"); } echo $r->ping() === 'PONG' ? "OK\n" : "PING failed\n"; - 在Docker健康检查或部署后钩子里运行它，而不是只依赖
php -m | grep redis - 对
swoole要测Swoole\Coroutine::create()；对grpc要试new Grpc\Channel()；不能只查类是否存在
区分CLI和Web环境的两套PHP实例
你在终端里 php -m 看到 redis 已启用，但网页打开就报 Class 'Redis' not found——大概率是Nginx+php-fpm用的是另一套PHP配置，彼此完全隔离。
- 终端执行
php --ini查CLI用的php.ini - 在Web页面中建一个
info.php，内容为<?php phpinfo();，搜索Loaded Configuration File看Web用的是哪个ini - 两个
php.ini都要检查extension_dir路径是否真实存在，且extension=redis.so行没有拼写错误或多余空格 - 改完Web端配置后，必须重启
php-fpm（不是reload），否则不生效
最容易被忽略的是：扩展ABI兼容性只由PHP主次版本（如8.1）和module API决定，和修订号（8.1.23）无关；但功能可用性可能依赖修订号里的bugfix，比如某个SSL握手问题只在8.1.25里修复。所以生产环境别只锁主次版本，补丁号也值得盯住。
