PHP FFI 调用共享库函数失败的常见原因与修复方案

在 PHP 8.1 里，如果用 FFI 去加载 .so 动态库时碰到 “Failed resolving C function” 这类报错，问题往往不在库本身，而是出在头文件里混入了 FFI_SCOPE 和 FFI_LIB 这两个宏定义。要注意，这两个宏本来就是给 FFI::scope() 这种加载方式准备的；一旦和 FFI::cdef() 里手动指定的库路径放在一起，就容易发生冲突，最终触发这个错误。

在 PHP 8.1 里用 FFI 加载 `.so` 动态库，如果碰到 “Failed resolving C function” 这类报错，问题通常就出在头文件里误混入了 `FFI_SCOPE` 和 `FFI_LIB` 这两个宏定义。说白了，这两个宏本来只适用于 `FFI::scope()` 这种加载方式，一旦和 `FFI::cdef()` 里显式指定库路径的写法放在一起，就很容易产生冲突。

在使用 PHP FFI（Foreign Function Interface）调用 C 编写的共享库函数时，必须严格区分两种加载机制：FFI::cdef() 和 FFI::scope()。本例中的核心问题在于——将仅适用于 FFI::scope() 的预处理宏误写进了供 FFI::cdef() 解析的头文件中。

❌ 错误根源分析

FFI_SCOPE 和 FFI_LIB 是 PHP FFI 特殊的预处理宏，其作用是为 FFI::scope() 提供编译期绑定信息。当使用 FFI::cdef($cdef, $libPath) 时，PHP 会：

• 直接解析 $cdef 字符串（或文件内容）中的 C 类型声明；
• 将函数符号（如 getint）动态绑定到 $libPath 指定的共享库；
• *完全忽略头文件中任何 `#define FFI_` 宏**——它们不仅无效，还会干扰解析逻辑，导致符号解析失败。

因此，原 get_int.h 中：

#define FFI_SCOPE "GETINT"
#define FFI_LIB "./getint.so"// ← 此行在 cdef 模式下有害无益
int getint(int val);

会导致 FFI::cdef() 在解析时产生歧义，最终抛出 Failed resolving C function 'getint'。

✅ 正确做法：分离声明与绑定

步骤 1：精简头文件（仅保留纯 C 声明）
get_int.h 应仅为标准 C 头文件，不含任何 PHP FFI 特有宏：

// get_int.h
int getint(int val);

步骤 2：正确编译共享库（确保导出符号）

gcc -shared -fPIC -o getint.so get_int.c
# ✅ 建议添加 -Wall 检查警告，-O2 优化

? 验证符号是否导出：nm -D getint.so | grep getint 应显示 T getint（小写 t 表示本地，大写 T 才表示全局可导出）。

步骤 3：PHP 中使用 FFI::cdef() 显式绑定

getint(123);
var_dump($result); // int(123)

⚠️ 注意事项

• 路径必须准确：FFI::cdef() 第二个参数需为共享库的绝对路径（相对路径易因工作目录变化失效）；
• 权限与 SELinux：确保 Web 服务器用户（如 www-data）对 .so 文件具有读取与执行权限；在启用 SELinux 的系统中，可能需运行 setsebool -P httpd_can_network_connect 1 或调整上下文；
• 架构匹配：PHP（x86_64）与 .so 必须同为 64 位（或同为 32 位），可通过 file getint.so 和 php -r 'echo PHP_INT_SIZE * 8;' 验证；
• 替代方案：使用 FFI::scope()（推荐用于大型项目）
  若需复用同一库多次，可改用作用域方式（此时才需 FFI_SCOPE/FFI_LIB）：

  // get_int.h（此时允许宏）
  #define FFI_SCOPE "GETINT"
  #define FFI_LIB "./getint.so"
  int getint(int val);

  // index.php
  require_once '/srv/www/myapp/libs/get_int.h'; // 触发宏定义
  $ffi = FFI::scope('GETINT');
  $ffi->getint(123);

遵循上述规范后，FFI 即可成功解析并调用 C 函数，彻底规避“Failed resolving C function”类错误。