phan 正常运行需同时满足 php-ast 扩展（≥1.1.3）、正确配置 .phan/config.php（含 directory_list、exclude_analysis_directory_list、plugins）及完整 composer 自动加载链；任一缺失均导致报错或静默失效。
Phan 不是“装上就能用”的工具，Composer 只负责拉代码和注册自动加载，真正起作用的是 php-ast 扩展 + .phan/config.php 配置 + 正确的执行路径。漏掉任一环，vendor/bin/phan 就会报错或静默失效。
为什么 composer require phan/phan 后运行报 “Class 'Phan\Phan' not found”
这不是 Composer 安装失败，而是自动加载链断了。Phan 的类靠 vendor/composer/autoload_classmap.php 映射，这个文件一旦被误删或没生成，就彻底找不到入口。
- 确认是否执行了
composer install或composer update（不是只跑require）； - 检查
vendor/autoload.php是否存在且可读； -
vendor/bin/phan脚本内部会require __DIR__.'/../autoload.php'，如果项目根目录下没有它，或路径被覆盖（比如某些 CI 环境用自定义入口），就会直接失败； - 别手动改
autoload_classmap.php—— 它由 Composer 自动生成，手改会被下次dump-autoload覆盖。
php-ast 扩展缺失或版本不匹配的典型表现
Phan 6+ 强依赖 php-ast 1.1.3+（尤其 PHP 8.4+），没它就只能退到 --allow-polyfill-parser 模式，但文档注释解析不准、类型推断弱、@param/@return 识别率下降明显。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Linux 下：先
pecl install ast，再在php.ini加extension=ast.so； - Windows 下：官方 PHP 包不带
php_ast.dll，得去 pecl.php.net 下对应 PHP 版本的 DLL，手动放进ext/并配置； - 验证是否生效：
php -m | grep ast有输出，且php --ri ast显示版本 ≥ 1.1.3； - Docker 用户注意：
docker-php-ext-install ast不行，必须用pecl install+ 手动启用，否则构建镜像时扩展根本没加载。
.phan/config.php 里最常配错的三个参数
运行 phan --init 只生成骨架，不填关键项等于白搭。实际项目中，这三个参数几乎必调，且顺序和值敏感。
-
'directory_list' => ['src', 'app']：必须显式列出要分析的目录；漏掉src就等于没扫业务代码；vendor不该放这儿，否则会把第三方库也当目标分析（极慢且无意义）； -
'exclude_analysis_directory_list' => ['vendor', 'tests', 'migrations']：这里列的是“跳过分析但保留符号信息”的目录；vendor必须加进来，否则 Phan 不知道 Laravel/Doctrine 的类型定义，大量“未定义方法”误报； -
'plugins' => ['AlwaysReturnPlugin', 'UnreachableCodePlugin']：不加插件，死代码、永远不执行的分支、多余return全部检测不到；vendor/phan/phan/src/Phan/Plugin/Internal/下的插件名要严格匹配，大小写错一个字母就静默忽略。
CI 中 phan 报 “Too many issues” 或内存溢出怎么办
Phan 默认不限制 issue 数量，也不设内存上限，大项目一跑就 OOM 或卡住。这不是 bug，是设计如此 —— 它默认追求“全量精确”，不是“快速反馈”。
- 加
--limit-memory=512M（Docker 内存紧张时建议设成256M）； - 用
--minimum-severity=5过滤低优先级提示（1=info, 5=error）； - 避免在 CI 中跑
--dead-code-detection：它需要全项目控制流图，内存占用翻倍，且对遗留项目容易误报； - 如果只想做兼容性检查（如升 PHP 8.2），用
--target-php-version=8.2+ 关闭所有插件，速度能快 3 倍以上。
最容易被忽略的点是：Phan 的配置不是“一次写完就不管”，target_php_version 必须和项目真实运行环境一致，否则类型推断和语法兼容性检查全失效；另外，vendor 在 directory_list 和 exclude_analysis_directory_list 中的角色完全相反，填错位置会导致分析范围爆炸或类型信息丢失。
