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 层是分离的，缺一不可；而适配器只是锦上添花，不是救命稻草。