Phalcon扩展加载失败主因是php.ini中extension=phalcon.so位置错误，须置于opcache.so之后、zlib/curl之前，且不可在[zend]段内；需确认php.ini路径、文件权限及Zephir编译流程合规。
Phalcon 扩展加载失败：检查 extension=phalcon.so 位置和顺序
Phalcon 是以 C 扩展形式存在的，不是普通 PHP 包，php.ini 中的加载顺序直接影响能否成功启用。常见现象是 php -m | grep phalcon 没输出，或 Web 请求报 Class 'Phalcon\Mvc\Application' not found。
关键点：Phalcon 必须在 opcache 之后、zlib 或 curl 等依赖扩展之前加载（因它内部使用了部分 Zend API，过早加载会触发符号未定义）。
- 用
php --ini确认实际生效的php.ini路径，别改错文件 - 把
extension=phalcon.so放到opcache.so行下方，且不要放在[zend]段内（Zephir 编译出的扩展属于常规 extension，不是 zend_extension） - Linux 下确认
phalcon.so权限为 644，且 PHP 进程有读取权限（尤其当用 nginx + php-fpm 时，注意 fpm 用户是否能访问该文件）
Zephir 编译报错 Cannot find config.json 或 Class 'PhalconVersion' not found
这是 Zephir 开发流程中最常卡住的环节——Zephir 不是“写完就能编译”，它依赖 Phalcon 源码根目录下的完整结构，包括 config.json 和 ext/ 子目录。直接 clone 官方仓库但删了 ext/，或只下载 release zip（不含构建元数据），都会失败。
正确路径是：从 phalcon/cphalcon 克隆完整仓库，切到对应 tag（如 v5.0.0），再进 phalcon/ 目录执行 zephir build。
立即学习“PHP免费学习笔记（深入）”；
-
zephir generate只生成 C 代码，不编译；真正要装进 PHP，必须跑zephir build（它会自动调用phpize/configure/make） - 若提示
version.h: No such file or directory，说明zephir build前没运行zephir fullclean清掉旧构建残留 - 开发中频繁修改，建议加
--backend=ZendEngine3显式指定后端，避免 Zephir 自动探测出错（尤其在 PHP 8.1+ 环境）
PHP 8.2+ 下 Zephir 编译失败：TSRMLS_DC 报错或 zend_string 类型冲突
Zephir 0.15.x 及更早版本默认生成兼容 PHP 7 的代码，无法直接用于 PHP 8.2+。错误典型表现为大量 use of undeclared identifier 'TSRMLS_DC' 或 incompatible pointer type 指向 zend_string*。
根本原因：Zephir 的语法层未同步 PHP 8 的 Zend API 变更，比如移除了 TSRMLS（线程安全资源宏）、重构了字符串/数组的底层表示。官方 phalcon v5.0+ 已切换到手动维护 C 代码 + Zephir 仅作部分生成，不再支持纯 Zephir 新增核心类。
- 若你坚持用 Zephir 写新扩展，必须升级到 Zephir 0.16.0+（需从源码编译），并确认其
config.json中"php_version": "8.2"设置匹配 - 更现实的做法：用 Zephir 写业务逻辑层（如自定义验证器），然后通过
extern关键字调用 PHP 8 原生函数或已编译好的 C 函数，避开 Zend 结构体操作 - 注意 Zephir 的
array类型在 PHP 8.2 下会被映射为zend_array*，但遍历时若混用foreach和底层zend_hash_get_current_data，极易触发 GC 崩溃
调试 Zephir 扩展崩溃：Segmentation fault (core dumped) 怎么定位
Phalcon/Zephir 扩展一旦 segfault，PHP 进程直接退出，error_log 里通常只有 child process X exited with code 139，毫无上下文。这时候不能靠 var_dump，得回到 C 层调试。
最有效方法是用 gdb 附着到 PHP CLI 进程，复现问题后看栈回溯。前提是编译时加了调试符号：zephir build --debug（会传 -g 给 gcc）。
- 运行
gdb --args php your_script.php，然后run，崩溃后输入bt查看最后一级 Zephir 生成的 C 函数名（如zim_MyClass_doWork） - 常见陷阱：Zephir 的
string类型在函数返回时未用zephir_create_local_array包装，直接 return C 字符串指针，导致 PHP GC 释放内存后二次访问 - 用
valgrind --tool=memcheck php your_script.php可捕获非法内存读写，但会显著拖慢执行——适合单元测试场景，不适合线上复现
Phalcon 的复杂性不在语法，而在它绕过了 PHP 大部分运行时保护机制。越想用 Zephir “快速开发”，越要清楚自己正在直面 Zend 引擎的裸接口。一个 zval* 指针写错位置，就比 ORM 配置少个逗号难查十倍。
