PHPStan不报语法错误，但能暴露跨版本类型契约断裂；php -l仅检查语法合法性，两者必须共存：前者深查类型兼容性，后者快筛基础语法。
PHPStan 本身不报语法错误，但它能暴露因版本差异导致的类型契约断裂——这才是跨版本兼容问题最危险的信号。
php -l 只能发现语法错误，不能代替 PHPStan
很多人以为用 php -l 扫一遍就能确认 PHP 版本兼容性，其实它只检查词法和基本语法是否合法。比如在 PHP 7.4 下写 fn($x) => $x * 2（箭头函数），php -l 不报错；但放到 PHP 7.3 就直接解析失败。PHPStan 不会拦这个，但它会在你把箭头函数返回值当作 int 传给一个要求 float 的函数时，精准指出类型不匹配——而这种“看似能跑、实则错”的情况，恰恰是升级后线上突然崩溃的主因。
-
php -l是第一道筛子，快但浅：适合 CI 中快速过一遍，防低级语法崩盘 - PHPStan 是第二道筛子，慢但深：依赖
phpVersion配置识别函数签名变更（如str_contains()在 8.0+ 才存在） - 两者必须共存：漏掉
php -l，可能连文件都加载不了；漏掉 PHPStan，可能所有单元测试都通过，但用户一提交表单就Fatal error: Uncaught TypeError
phpstan.neon 必须显式声明 phpVersion
默认情况下，PHPStan 按当前运行环境的 PHP 版本推断函数行为。如果你在 PHP 8.2 环境下分析目标为 PHP 7.4 的项目，不加限制就会把 match、??=、联合类型等全当合法，完全失去检测意义。
- 在
phpstan.neon的parameters区块里必须写明：phpVersion: 70400（对应 7.4.0） - 数值格式固定为「主版本×10000 + 次版本×100 + 修订号」，例如 PHP 8.1.22 →
80122 - 如果项目需兼容多个版本（如 7.4–8.2），优先按最低目标版本设
phpVersion，否则高版本特性会被当作“已存在”而跳过检查 - 注意：该配置不影响 PHPStan 自身运行版本，只改变它对标准库函数签名的理解
ignoreErrors 不是兜底方案，而是临时止血手段
ThinkPHP、Laravel 等框架大量使用魔术方法和动态属性，PHPStan 默认会报 Call to an undefined method 或 Access to an undefined property。这时候加 ignoreErrors 很容易，但掩盖了真正的问题——比如你误用了已被弃用的 Db::table() 而非 Db::name()，忽略后就再也收不到提示。
立即学习“PHP免费学习笔记（深入）”；
- 优先走正向适配：用
bootstrapFiles加载框架 stub（如think-stubs.php）或includes引入类型定义 - 只对明确已知、短期内无法重构的动态调用加
ignoreErrors，且必须带注释说明原因和计划修复时间 - 正则匹配要够窄：用
'#Call to an undefined method App\Model\User::getProfileData#'，而不是宽泛的'#undefined method#' - 一旦某条
ignoreErrors规则连续 3 个版本没被触发，应主动删除——它大概率已失效或冗余
level 设置过高反而掩盖兼容性风险
Level 9 看似严格，但它会强制要求返回类型声明、私有属性类型等 PHP 7.4+ 特性。如果你的目标环境是 PHP 7.2，开 level 9 不仅报一堆“无法实现”的错误，还会让真正危险的兼容问题（如 array_key_exists() 在 PHP 8.0+ 对对象行为变更）被淹没在噪音里。
- 跨版本项目建议从
level: 5起步：它覆盖参数类型、返回类型、未定义方法、空值解引用等核心风险点 - 每提升一级，先确认目标 PHP 版本是否支持对应语法（例如 level 7 开始校验构造函数属性提升，这要求 PHP 8.0+）
- 用
--generate-baseline生成基线文件时，务必指定--php-version=70400，否则 baseline 会绑定当前环境版本，失去迁移价值 - CI 中不要无条件用最高 level：可分两阶段执行——先用目标版本 level 5 过兼容性，再用开发环境 level 8 过代码质量
最难处理的不是语法报错，而是那些“PHPStan 不报、php -l 不报、测试也通过，但换到新版本就静默改变行为”的函数——比如 json_encode() 的浮点数精度、mb_strtolower() 的区域设置敏感性。这类问题必须靠针对性的单元测试覆盖，PHPStan 只能帮你守住类型契约这一条底线。
