PHPStan 适合快速上手和轻量CI检查，Psalm类型推导更强但配置重；新项目首选PHPStan，强类型需求再引入Psalm；需显式配置扫描路径，避免依赖autoloader；Psalm开启allowPhpStormGenerics会增强泛型校验但增加报错和耗时；CI中应限制线程数、优化autoload、使用精简配置。
PHPStan 和 Psalm 到底该选哪个
PHPStan 更适合快速上手、CI 集成轻量检查；Psalm 类型推导更强，但配置更重、学习成本高。如果你项目里已有 phpstan.neon 或 psalm.xml，别轻易换——两者不兼容，迁移成本远超预期。
常见错误现象：PHPStan 报 Call to an undefined method 但方法明明存在；Psalm 报 InvalidArgument 却找不到调用点。本质是 autoloader 没加载对，或 scanDirectories / <file></file> 漏了路径。
- 新项目起步优先用
phpstan/phpstan+--level max，稳； - 强类型诉求（比如重构 legacy 代码、写 SDK）再引入
vimeo/psalm； - 两者都支持
composer require --dev安装，别用全局phar，CI 中易出版本漂移；
怎么让 PHPStan 检查到你写的类和 trait
默认只扫 src/，但很多项目把 domain logic 放在 app/Models、lib/ 或 packages/*/src。PHPStan 不会自动发现这些路径，必须显式声明。
使用场景：Laravel、Symfony、自定义 MVC 结构下，phpstan analyse 总报“class not found”或“method not defined”，其实不是代码错，是没告诉它去哪找。
立即学习“PHP免费学习笔记（深入）”；
- 在
phpstan.neon里加parameters → paths，例如：parameters: paths: - app - lib - packages/*/src； - 避免用
autoload-dev代替路径扫描——PHPStan 不走 Composer autoloader 加载类，它靠 AST 解析； - 如果用了 psr-4 映射但目录名不规范（如
App\Helpers\→helpers/），PHPStan 会跳过，老老实实按真实路径列进去；
Psalm 的 allowPhpStormGenerics 是干啥的
这是个开关，决定 Psalm 是否信任 PhpStorm 风格的 PHPDoc 泛型注解，比如 @param array<string user></string> 或 @return Collection<post></post>。默认关闭，一开就可能暴增 InvalidReturnType 报错——不是你写错了，是 Psalm 开始认真校验这些注解了。
性能影响：开启后分析时间增加 15%~30%，尤其在大量使用 Collection、IlluminateSupportLazyCollection 的 Laravel 项目中明显。
- 只在团队统一用 PhpStorm + PHPDoc 泛型时打开；
- 打开前先跑
psalm --init生成 baseline，再改配置，否则一堆历史问题直接阻塞 CI； - 注意
array<int string></int>和list<string></string>在 Psalm v5+ 语义不同，后者要求键连续从 0 开始，别混用；
CI 里怎么避免 PHPStan/ Psalm 成为瓶颈
本地快不代表 CI 快。Docker 环境缺 OPCache、Composer classmap 没 dump、并行数设太高反拖慢，都会让静态分析从 20 秒涨到 3 分钟。
容易踩的坑：phpstan analyse --no-progress 在 CI 里仍可能卡住，因为默认用 4 进程，而 GitHub Actions 默认只有 2 vCPU；psalm --threads=auto 在低配 runner 上等于自爆。
- CI 中固定线程数：
phpstan analyse --threads=2（GitHub Actions）、psalm --threads=1（GitLab Shared Runner）； - 提前
composer dump-autoload --optimize，减少文件 stat 开销； - 用
phpstan analyse --configuration=phpstan.ci.neon单独配一个精简版配置，关掉checkGenericClassInNonGenericObjectType这类耗时规则；
最麻烦的其实是 vendor 依赖里的类型错误——它们会污染你的报告。别硬扛，用 ignoreErrors 或 <taintanalysis></taintanalysis> 关掉第三方包路径，聚焦自己写的代码。
