phalcon 框架无法通过 composer 安装，因其是编译型 zend 扩展而非 php 类库；唯一可写入 composer.json 的是 "ext-phalcon": "*" 用于环境校验，而 phalcon/devtools 和 phalcon/ide-stubs 仅可作为 dev 依赖安装。
Phalcon 框架本身不能通过 Composer 安装，强行 composer require phalcon/phalcon 会失败或引入废弃包；真正能用 Composer 管理的只有环境校验、DevTools 和 IDE 补全三类东西。
为什么 composer require phalcon/phalcon 一定不行
Phalcon 是编译后的 Zend 扩展（phalcon.so 或 php_phalcon.dll），不是纯 PHP 类库。Packagist 上没有官方发布的 phalcon/phalcon 包——v4/v5 版本从未发布到 Composer 仓库。你搜到的旧包要么是空壳，要么映射错误，安装后运行时仍会报 Class 'PhalconDiFactoryDefault' not found 这类致命错误。
常见错误现象：
- 执行
composer require phalcon/phalcon后无报错，但php -m | grep phalcon没输出 - 项目启动时报
Fatal error: Uncaught Error: Class 'PhalconMvcApplication' not found - Docker 构建成功，但容器内
php --ri phalcon提示 “Invalid argument”
根本原因：Composer 没法加载扩展，它只管 PHP 代码依赖。必须先手动安装扩展，再让 Composer 做校验和配套工具管理。
ext-phalcon 在 composer.json 中的正确写法
这是唯一推荐写进 require 的 Phalcon 相关项，作用是部署时自动检查扩展是否已启用。
正确配置示例：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"require": {
"ext-phalcon": "*"
},
"autoload": {
"psr-4": {
"App\": "app/"
}
}
}
关键点：
-
"ext-phalcon": "*"必须放在require（不是require-dev），否则composer install在 CI/CD 环境中不会校验扩展是否存在 - 如果项目支持多环境，不要用
"ext-phalcon": "^5.0"这类带版本号的写法——扩展版本由 PHP 模块决定，Composer 不参与版本匹配 - 执行
composer install后，若扩展未启用，会直接报错：The requested PHP extension ext-phalcon is missing from your system.，这是预期行为，不是 bug
DevTools 和 IDE 补全怎么装才不踩坑
phalcon/devtools 和 phalcon/ide-stubs 是仅有的两个可安全 composer require 的官方包，但必须加 --dev 标志。
实操建议：
- 装 DevTools：
composer require phalcon/devtools --dev—— 它只提供phalcon命令行工具，不包含任何运行时类，不会干扰框架加载 - 装 IDE 补全：
composer require phalcon/ide-stubs --dev—— 生成 PHP stubs，供 VSCode/PhpStorm 识别Phalcon*类名和方法签名 - 别装
phalcon/incubator：它只兼容 v3.x，v4/v5 强行安装会导致PhalconMvcModelCriteriaInterface找不到等命名空间冲突 - v5 推荐替代方案：
composer require phalcon/common:^5.0，它只提供Arr::first()这类工具函数，不侵入 DI 或 MVC 生命周期
手动安装 Phalcon 扩展的验证闭环
所有 Composer 操作都建立在扩展已启用的前提下。跳过这步，后面全是徒劳。
必须完成的验证动作：
- Linux/macOS：确认
php.ini含extension=phalcon.so，且该文件路径正确（php --ini查位置） - Windows：确认
php.ini含extension=php_phalcon.dll，DLL 文件需匹配 PHP 版本（8.1/8.2）、TS/NTS、x64/x86 - 统一验证命令：
php -m | grep phalcon（有输出） +php --ri phalcon（显示版本和编译信息） - Docker 用户注意：基础镜像必须含预编译扩展，如
phalconphp/phalcon:5.0-apache；自建镜像需在Dockerfile中显式pecl install phalcon并重启 PHP-FPM
最容易被忽略的是：本地开发环境启用了 phalcon，但 CI/CD 流水线用的 Docker 镜像没装扩展，导致 composer install 成功、phpunit 却直接 fatal。务必把 php -m | grep phalcon 加进部署前检查脚本。
