EP18. "wp-phpstan-review PHPStan 静态分析配置审查"

• 装了 PHPStan，跑起来是绿的，但绿的原因是「baseline 把所有旧问题都埋起来了」还是「代码真的没问题」？这两者天差地别，wp-phpstan-review 就是专门抓这种「看起来有做静态分析，其实没真的在分析」的坑
• 这是 jorgerosal/wordpress-skills 开源 skill 包里的其中一个，专门审查 WordPress 项目里的 PHPStan 配置、baseline 策略、CI 整合
• 核心原则：静态分析要够严格到能抓到真的 bug，但不能严格到全是噪音；WordPress 专属的扩展/stub 要有意识地接进去，不是装了就算数
• 📌 这个 skill 在上游仓库的 README 里标注为 🚧 in progress（截至 2026-09 撰写本篇笔记时），代表作者认为它还在持续打磨中；不代表内容不能用，下面的内容是照实际抓到的 SKILL.md 整理的
• 前置知识：先看过 Overview 系列的「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇，知道 Skill 是什么、怎么装

重点内容

这个 Skill 是做什么的

PHPStan 是 PHP 生态最常用的静态分析工具，但 WordPress 项目要接对它并不简单——WordPress 核心函数、hook、全局变量都不是标准 PHP 能直接理解的东西，得靠 szepeviktor/phpstan-wordpress 这类扩展和 php-stubs/wordpress-stubs 补上。这个 skill 审查的是 phpstan.neon/phpstan.neon.dist 配置本身、baseline 用得对不对、CI 有没有真正在跑它、分析路径有没有覆盖到真正的项目代码。

适合用在：

• 审查 phpstan.neon、phpstan.neon.dist 或 CI 里的静态分析配置
• 规划在 WordPress 插件/主题里导入 PHPStan
• 审计 baseline 用法或被忽略（ignore）掉的错误
• 审查 szepeviktor/phpstan-wordpress 的设置
• 检查分析范围、bootstrap 文件、stub 配置

不适合用在：

• 运行时性能审查
• 不以静态分析为重点的 PHPUnit/浏览器测试策略
• 跟分析设置无关的一般 PHP 重构

触发方式

审查流程

1. 找出分析入口 — phpstan.neon/phpstan.neon.dist、Composer 的 require-dev、CI workflow 和脚本、bootstrap 或 stub 文件
2. 先看基础配置 — 配置文件命名和 include 关系；分析等级（level）和分析路径；排除项和 bootstrap 文件；WordPress 专属的扩展/stub 是不是真的有被载入
3. 审查 baseline 和 ignore 策略 — baseline 该是用来「分阶段导入分析」的工具，不是用来「把新问题永远埋起来」；被 ignore 的错误要是有意为之、可回顾的；新代码还是要守住比较高的标准
4. 审查 CI 体验 — 指令是不是确定性的；配置路径对不对；失败行为合不合理；本地跟 CI 的配置有没有悄悄跑偏
5. 给严重度分级

严重度分级

按面向抓的坑

实操示例：phpstan.neon 配置的错法/对法

# ❌ CRITICAL：分析路径没指到真正的项目代码，也没接 WordPress 扩展
parameters:
    level: 5
    paths:
        - src
    # 没有 include WordPress 扩展，但代码里到处用 WP 函数

# ✅ GOOD：分析路径覆盖真正的插件代码，明确接入 WordPress 扩展和 stub
includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
    level: 6
    paths:
        - includes
        - my-plugin.php
    bootstrapFiles:
        - tests/phpstan-bootstrap.php

# ❌ WARNING：错误一多就整个重新生成 baseline，问题被无限期掩盖
# （每次 CI 失败就跑一次 vendor/bin/phpstan analyse --generate-baseline）

# ✅ GOOD：baseline 只在刻意分阶段导入分析时用，新代码不能靠它兜底
includes:
    - phpstan-baseline.neon   # 记录既有代码的旧问题，新增代码走正常报错，不再塞进 baseline

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-phpstan-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-phpstan-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-phpstan-review 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

• ❌ 看到有 baseline 文件就当成「静态分析形同虚设」打回去——baseline 本身是合理的渐进导入手段，问题在于「有没有被刻意维护」，不是「存不存在」
• ❌ 项目用了 require-dev 装 stub/扩展，就假设一定有接进 phpstan.neon——扩展装了不代表配置里真的 include 了，这两件事要分开确认
• ❌ 只看 level 数字高不高就判断分析够不够严格——level 再高，如果 paths 根本没扫到真正的插件代码，也是白搭
• 💡 判断这个项目的静态分析是不是「真的在用」，先看 CI 里跑的指令和配置路径跟本地文档写的是不是同一套，再看 baseline 有没有随手重生成的痕迹

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-phpstan-review SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-phpstan-review/SKILL.md