PHPStan 是什么
PHPStan 是 PHP 的静态分析工具，用级别控制分析严格度：级别越低越宽松，越高检查越深、报错也越多。它支持用基线文件冻结存量报错，用 phpstan.neon 指定扫描路径、级别与忽略项。典型升级路径是先把当前级别锁住过 CI，再每个迭代尝试提升一级并修完新增报错。
基本信息
| 严格度 | 用级别表示，逐级递增 |
|---|---|
| 配置文件 | phpstan.neon（路径、级别、忽略项） |
| 存量处理 | --generate-baseline 生成基线文件 |
| 运行方式 | vendor/bin/phpstan analyse |
| 集成方式 | 编辑器插件、CI、pre-commit 钩子 |
典型使用场景
- 新项目从合理级别起步，老项目先用基线冻结存量
- CI 中把新增报错当失败，阻止问题继续累积
- 重构前后对比报错数量，量化改动的实际收益
- 接入框架扩展包，提升对框架 API 的分析准确度
- 升级 PHP 大版本前，先用静态分析找出兼容性问题
- 把类型声明缺失较多的模块列为专项清理对象
配置与运行
配置与运行
# phpstan.neon
parameters:
level: 6
paths:
- src
ignoreErrors:
- '#Call to an undefined method#'
# 命令行
# vendor/bin/phpstan analyse 按配置分析
# vendor/bin/phpstan analyse --generate-baseline 生成基线，冻结存量报错级别提升的阶段
| 级别区间 | 检查强度 | 适用阶段 |
|---|---|---|
| 较低级别 | 基础语法与明显错误 | 老项目刚接入，先跑通再说 |
| 中等级别 | 类型与调用关系检查 | 常规项目的起跑线 |
| 较高级别 | 更严格的类型推断 | 逐步提升的主要区间 |
| 最高级别 | 接近逐行严格推断 | 核心模块或全新代码 |
级别的编号与上限随版本演进：升级 PHPStan 之前先核对官方文档中的级别定义，避免按旧印象配置，出现与预期不符的报错量。
提升路径：先锁当前级别过 CI，再每个迭代尝试加一级并修完新报错。跳级提升会让历史代码的报错数量失控，团队很快放弃。每次提级后把新增报错按类型归类，优先修类型声明与调用签名这类会连锁的问题。