FFI 调用 C++ 共享库时，FFI::cdef() 声明不匹配的典型表现是 segfault 或返回乱码，主因是参数类型不符或未用 extern "C" 导致符号名被 mangling；必须用 extern "C" 封装函数、nm -D 确认符号、严格对齐结构体内存布局。
FFI 调用 C++ 共享库时，FFI::cdef() 声明不匹配的典型表现
常见错误是 PHP 层面的 FFI::cdef() 声明与实际 C++ 导出函数签名不一致，比如参数类型写成 int 但 C++ 实际是 long long，或遗漏 extern "C" 导致符号名被 C++ 编译器修饰（如变成 _Z12my_functionv）。此时调用会直接 segfault 或返回乱码，FFI::scope() 无法捕获这类底层错误。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 所有供 FFI 调用的 C++ 函数必须用
extern "C"封装，禁用 name mangling - 在 C++ 侧编译时加
-fvisibility=hidden，仅对明确标记__attribute__((visibility("default")))的函数导出 - 用
nm -D libmylib.so | grep my_function确认符号名是否为原始名称（非 mangled） -
FFI::cdef()中的结构体定义需严格对齐 C++ 的struct内存布局，尤其注意packed和 padding
如何让 Composer 自动加载封装好的 FFI 类并复用实例
FFI 实例创建开销不小，反复调用 FFI::cdef() 会导致性能下降。不能靠每次 new 一个类就重新加载 so 文件——必须把 FFI 句柄作为静态属性或容器服务管理。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在
composer.json的"autoload"中配置 PSR-4，例如："Native\": "src/Native/" - 封装类中使用
private static $ffi+ 双重检查锁（if (null === self::$ffi)）确保单例 - 避免在构造函数里调用
FFI::cdef()，改用懒加载静态方法：self::getFFI() - 若项目用 Laravel/Symfony，可注册为服务并设为
shared: true，由容器统一管理生命周期
生产环境启用 ffi.enable 后仍报 Call to undefined function FFI::cdef()
这不是扩展没启，而是 CLI 与 Web SAPI 配置分离导致的典型问题。PHP-FPM 或 Apache mod_php 的 php.ini 通常和 php -v 所用的不是同一份配置，ffi.enable = true 很可能只写在 CLI 的 ini 里。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
phpinfo()页面搜索Loaded Configuration File，确认 Web 环境实际读取的是哪个 ini - 在对应 ini 文件中显式添加：
ffi.enable = true，**不能只依赖默认值** - 重启 PHP-FPM 进程（
sudo systemctl restart php*-fpm），而非仅 reload - 检查
php -m | grep ffi（CLI）和phpinfo()（Web）输出是否都显示 ffi 已启用
用 Composer 引入的第三方 FFI 包（如 ffi-sodium）为何无法直接调用自定义 C++ 库
这类包只封装了特定 C 库（如 libsodium），其 FFI::cdef() 声明和 load() 路径都是硬编码死的，不会自动适配你本地编译的 libmycalc.so。强行修改 vendor 里代码不仅违反 Composer 管理原则，下次 composer update 还会被覆盖。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 不要 patch vendor，而是新建自己的命名空间（如
MyCompanyNativeCalc）封装调用逻辑 - 将 C++ 库路径设为环境变量（如
MYCALC_LIB_PATH=/opt/mylib/libmycalc.so），运行时动态传入FFI::load() - 在
composer.json的"autoload"里加入该目录，确保 Composer 能找到你的封装类 - 若需多环境部署，用
extra字段声明路径模板，再通过脚本生成实际配置
~MyClass()，你得在 PHP 类的 __destruct() 里显式调用 C++ 的清理函数。 
