PHPStan与Psalm应互补共存：PHPStan作主干门禁（level=6+Laravel扩展），Psalm补强类型契约（errorLevel=3–4）并支持自动修复，二者协同集成于CI/CD与本地开发流程。
PHP 8.1 项目要落地工程化的静态扫描，光靠单个工具不够扎实。PHPStan 和 Psalm 各有侧重：PHPStan 更贴近 Laravel 生态、学习曲线平缓、适合渐进式治理；Psalm 类型检查更激进、泛型支持更强、修复能力更直接。两者不是二选一，而是互补共存。
分层配置：用 PHPStan 做主干质量门禁
在 CI/CD 流水线中，把 PHPStan 设为必过关卡：
- 使用 level=6 作为默认分析级别，兼顾严格性与可维护性，能覆盖类型不匹配、未定义方法、空值解引用等高频风险
- 配合 nunomaduro/larastan 扩展，让 PHPStan 理解 Eloquent 关系、Facade、Service Container 绑定等 Laravel 特有模式
- 对历史遗留代码，先运行
vendor/bin/phpstan --generate-baseline生成 baseline 文件，只对新增/修改代码报错，避免阻塞交付 - 在
phpstan.neon中明确指定paths（如app、src），排除storage、bootstrap/cache等非源码目录
深度加固：用 Psalm 补强类型契约与自动修复
Psalm 不是替代 PHPStan，而是补位它“不敢太严”的部分：
- 初始化后调整
psalm.xml的errorLevel为 3–4（1 最严，8 最松），比 PHPStan level=6 更细粒度地捕获模板参数、联合类型误用、不安全的new static等问题 - 对关键服务类或 DTO 层，启用
<issueHandlers>单独收紧规则，比如强制所有 public 方法声明返回类型、禁止隐式array而要求array<string, mixed> - 利用
vendor/bin/psalm --alter --issues=MissingReturnType,InvalidReturnType批量注入类型声明，尤其适合 PHP 8.1 的联合类型（string|int|null）和枚举返回值场景 - Psalm 对 PHP 8.1 原生枚举（
enum）、只读类（readonly）和never类型有原生识别能力，PHPStan 需依赖扩展且支持滞后
协同集成：避免重复告警，统一反馈口径
两个工具并行运行，必须防止同一问题被反复报告、干扰判断：
立即学习“PHP免费学习笔记（深入）”；
- 在
psalm.xml中通过<globals>或<stubs>引入 PHPStan 已知的框架存根（如 Laravel 的Illuminate\Support\Facades\*），减少 Psalm 误报 - 将 Psalm 的
--output-format=checkstyle与 PHPStan 的--error-format=checkstyle输出统一接入 CI 报告系统（如 SonarQube 或 GitLab Code Quality），合并展示为“静态分析问题”大类 - 本地开发时，用 Composer script 封装双工具命令：
"static:check": "vendor/bin/phpstan analyse && vendor/bin/psalm"，配合 pre-commit 钩子确保提交前双检 - 对 Psalm 报出但暂不修复的问题（如第三方包类型缺失），用
<ignore>按文件路径+问题码精准忽略，而非全局降级 errorLevel
持续演进：从扫描到重构的闭环
静态扫描的价值不在报告本身，而在驱动代码进化：
- 每季度回顾 Psalm 的
--stats输出，追踪MissingReturnType、InvalidArgument等高发 issue 的下降趋势，作为团队类型化进度指标 - 结合 Rector，在 Psalm 修复建议基础上批量升级语法：例如将 PHP 7.4 的
array注解自动转为 PHP 8.1 的list<string>或non-empty-array<int, string> - 在 PHPDoc 中逐步淘汰
@var array这类模糊注解，改用 Psalm 支持的@var array{status: string, data?: array}结构化数组类型，提升 IDE 跳转与自动补全精度 - 新模块开发强制启用
declare(strict_types=1)，并在 Psalm 配置中开启strictBinaryOperands和disallowMixedArray，从源头遏制动态类型漂移
