Phalcon 扩展需手动编译启用，不可通过 Composer 安装；phalcon/incubator 仅兼容 3.x 且已停更，4/5 版本应使用 phalcon/common；务必先确认 php -m | grep phalcon 有输出，再安装适配器。
Phalcon 不支持通过 Composer 直接安装扩展本身（phalcon 扩展是 C 编写的 PHP 模块），但它的官方适配器包 phalcon/incubator 和现代替代品 phalcon/common 可以用 Composer 引入——前提是你的环境已正确编译并启用了 phalcon 扩展。
确认 phalcon 扩展已启用，再装适配器
很多失败源于跳过这步：Composer 能装下 phalcon/incubator，但运行时会报 Class 'Phalcon\Di\FactoryDefault' not found 或类似错误。这不是 Composer 问题，而是 PHP 根本没加载扩展。
- 运行
php -m | grep phalcon，有输出才表示扩展已载入 - 检查
php.ini中是否包含extension=phalcon.so（Linux/macOS）或extension=php_phalcon.dll（Windows） - 若用 Docker，确保基础镜像含预编译的 Phalcon（如
phalconphp/phalcon:4.1-apache），或自行构建时启用--enable-phalcon -
php --ri phalcon应显示版本与编译信息；若报错“Invalid argument”，说明扩展未生效
composer require phalcon/incubator 仅适用于 Phalcon 3.x
phalcon/incubator 是旧版辅助库，已停止维护，且与 Phalcon 4/5 不兼容。强行安装会导致类型冲突、命名空间错误（如 Phalcon\Mvc\Model\CriteriaInterface 不存在）。
- Phalcon 3.x 项目可执行：
composer require phalcon/incubator:^3.4
- Phalcon 4.x+ 必须改用
phalcon/common（轻量工具集）或直接使用框架内置类 -
phalcon/common不提供 MVC 辅助类，只含Arr、Str、Inflector等通用工具，安装命令为：composer require phalcon/common:^5.0
- 注意：它不解决模型验证、表单生成等老
incubator功能，那些需自行实现或换用第三方组件（如symfony/validator）
Phalcon 5.x 推荐组合：phalcon/common + 原生 DI/Loader 配置
Phalcon 5 彻底移除了 Phalcon\DI\Service 等旧类，依赖 PSR-11 兼容容器。适配器不再是“加个包就行”，而是要对齐框架生命周期。
- 避免在
services.php中继续写new \Phalcon\Di\FactoryDefault()—— 改用new \Phalcon\Di\Di() -
phalcon/common的Phalcon\Common\Arr::first()这类函数可直接用，无需注册服务 - 若需数据库查询构建器增强，不要找
incubator的QueryBuilder，改用 Phalcon 5 原生Phalcon\Mvc\Model\Query\Builder或 Doctrine DBAL - 自动加载路径无需额外配置：Composer 自动处理
phalcon/common的 PSR-4 映射
真正卡住人的地方从来不是 Composer 命令输错，而是把“装了包”当成“框架就跑起来了”。Phalcon 的扩展层和 PHP 层是分离的，缺一不可；而适配器只是锦上添花，不是救命稻草。
