FFI 可用需满足扩展启用且 ffi.enable=true，Web 环境默认 preload 不生效；验证需返回 bool(true)，否则检查配置、库路径或声明匹配性。
确认 FFI 扩展已启用且配置正确
PHP 8.0+ 默认编译时带 --with-ffi，但不等于自动启用。最常被忽略的是 ffi.enable 配置项——它的默认值是 "preload"，只在 CLI 模式下、且脚本通过 opcache.preload 加载时才生效，Web SAPI（如 PHP-FPM 或 Apache mod_php）中直接调用会静默失败，连报错都没有。
必须显式修改 php.ini：
ffi.enable = true
改完后重启 PHP 进程（不是 Web 服务器），并用以下代码验证：
<?php
var_dump(FFI::cdef('int getpid();', 'libc.so.6')->getpid() > 0);
?>
- 返回
bool(true)表示 FFI 可用；返回Fatal error: Uncaught Error: Call to undefined class FFI是扩展未加载 - 返回
bool(false)或直接崩溃（如 Segmentation fault），大概率是ffi.enable仍为"preload"或共享库路径错误 - Linux 下常用库名是
libc.so.6、libm.so.6；macOS 要换用libc.dylib、libm.dylib
用 FFI::cdef() 声明函数时，参数类型必须严格匹配 C ABI
FFI::cdef() 第一个参数是 C 声明字符串，它不是语法检查器，也不会做类型推导。写错类型不会报错，但调用时可能返回垃圾值、崩溃或静默截断——尤其在浮点、指针、结构体字段对齐上。
立即学习“PHP免费学习笔记（深入）”；
常见翻车点：
-
int printf(const char *format, ...)中的...必须原样保留，不能写成void或省略；否则调用变未定义行为 - C 的
size_t在 64 位系统是unsigned long，不是int；传错会导致数组越界 - 传递字符串给 C 函数时，PHP 字符串是 UTF-8 编码、以
\0结尾的字节序列，但若 PHP 字符串含嵌入\0（如二进制数据），需用FFI::new()显式分配内存并 memcpy - 调用数学函数如
pow()，C 库是libm.so.6，不是libc；写错库名会提示undefined symbol
安全做法：从真实头文件复制声明，或用 gcc -E 预处理后粘贴，别手写。
调用自定义 C 库前，必须确保符号可见且无依赖缺失
自己编译的 .so 文件如果用了其他库（如 libgmp、libopenblas），PHP 的 FFI 不会自动解析依赖链。运行时会卡在 dlopen() 阶段，报错类似：
PHP Warning: FFI::cdef(): failed to load library 'libmycalc.so': libgmp.so.10: cannot open shared object file
解决步骤：
- 用
ldd libmycalc.so查看所有依赖，确保每个.so都在LD_LIBRARY_PATH或系统路径中 - 编译时加
-Wl,-rpath,'$ORIGIN'，让库优先从自身目录找依赖（$ORIGIN是当前 .so 所在路径） - PHP 中加载时用绝对路径，避免因工作目录不同导致找不到文件：
FFI::cdef(..., '/opt/mylib/libmycalc.so') - 若 C 函数返回指针（如
double*），PHP 接收后要用FFI::cast()转类型，再用[$i]访问元素，不能直接当 PHP 数组用
FFI 调用不是万能加速器，要注意内存和生命周期管理
FFI 绕过了 PHP 的内存管理，意味着你得自己负责 C 端分配的内存释放。比如调用 malloc() 后没 free()，就会泄漏；而 PHP 的 GC 对这些内存完全不可见。
关键约束：
- PHP 传给 C 的字符串、数组指针，在 C 函数返回后就失效——除非你用
FFI::new()在 FFI 堆上分配，并手动free() - 不要把 PHP 对象（如
stdClass）直接传给 C；FFI 只认原始内存布局，对象会被当成乱码指针 - 多线程场景下，FFI 对象本身不是线程安全的；若多个协程/线程并发调用同一
$ffi实例，需加锁或每个线程单独初始化 - 性能上，FFI 调用开销约 50–200ns，比纯 PHP 函数调用高一个数量级；所以别用它包装单个
strlen()，而应封装整块计算逻辑（如整个图像滤镜流程）
真正值得用 FFI 的地方很窄：已有成熟 C 库、计算密集、且调用频次足够摊薄 ffi 开销——比如 BLAS 矩阵运算、FFmpeg 解码、加密哈希。其它情况，先测 JIT + OPcache，再考虑 FFI。
