Composer怎么安装Psalm静态分析_Composer如何引入Psalm检查代码类型安全【教程】

Psalm 起效关键在于 psalm.xml 与 composer.json autoload 配置严格对齐

很多开发者以为，composer require --dev vimeo/psalm 之后，静态分析工具就能立刻投入工作。其实，这只是拿到了入场券。真正决定 Psalm 能否正常工作的，是后续那一步关键的配置对齐——psalm --init 生成的 psalm.xml 必须与 Composer 的自动加载配置严丝合缝。可以说，九成以上令人头疼的 “Class not found” 报错，根源都出在这里。

psalm --init 必须立刻执行，且选 medium 规模

安装完 Psalm 不立刻执行 psalm --init，psalm.xml 配置文件就不会生成，后续所有调整都无从谈起。这个初始化命令会交互式地询问项目规模，通常有三个选项：

• small：会跳过深层调用链的分析，虽然反赌，但容易漏掉一些像 InvalidReturnType 这样的深层类型问题。
• medium：默认启用了一套比较合理的规则集，对新项目起步非常友好，也是普遍推荐的选择。
• large：会开启一大堆严格规则（比如全面启用 MixedAssignment），新手很容易在第一轮扫描时就被大量报错卡住，反而无从下手。

另外要注意，psalm --init 会尝试自动猜测你的源码目录（比如扫描到 src/ 文件夹，就会在配置里写上 ）。但这个“猜测”过程并不读取 composer.json 的配置，所以猜出来的路径大概率需要你手动核对和修改。

psalm.xml 的 必须和 composer.json 的 autoload 完全一致

Psalm 本身并不负责解析类的具体路径，它完全复用 Composer 的自动加载器映射。这就意味着，两者的配置必须对齐。举个例子，如果你的 composer.json 里是这么写的：

"autoload": {
  "psr-4": {
    "App\\": "app/"
  }
}

那么，psalm.xml 里的项目文件目录就必须对应设置为：

如果没对上，就会出现各种奇怪的问题：

• 报错 ERROR: UndefinedClass - src/Service/UserService.php:12:21 - Class AppModelUser was not found，其实很可能只是路径映射没配好。
• 有些类明明没被使用，Psalm 却不报 INFO: UnusedClass —— 这是因为 Psalm 根本没把 tests/ 这类目录识别为项目文件，除非你显式地加上 。

对于全局函数文件（比如 src/helpers.php）也需要留意，它们必须在 composer.json 的 "files" 字段中声明，否则 Psalm 同样无法感知到它们的存在。

CI 中 psalm 失效？先检查 composer dump-autoload 和 --no-dev

CI（持续集成）环境是另一个容易踩坑的地方。由于没有本地缓存，vendor/autoload.php 里的类映射必须是最新生成的：

• 运行 Psalm 前，务必先执行 composer dump-autoload -o 来优化自动加载器，否则 Psalm 可能会回退到缓慢的文件扫描模式，甚至因超时而失败。
• 命令 composer install --no-dev 会跳过安装 vimeo/psalm 这类开发依赖，导致 vendor/bin/psalm 可执行文件消失。因此，CI 流程最好分两步：先带着 --dev 依赖运行 Psalm 检查，通过后再用 --no-dev 构建生产环境用的包。
• 不要试图用 autoloader="vendor/autoload.php" 这样的配置去覆盖默认行为。Psalm 本来就会读取这个文件，额外指定反而可能干扰正常的路径解析逻辑。

有个快速验证自动加载是否生效的方法：在 CI 脚本里加一行 php -r "var_dump(class_exists('YourMainClass'));"。如果返回 false，那基本可以断定自动加载链路出了问题。

“Unable to resolve class Xyz” 怎么定位？从 class_exists 开始

遇到这类报错，先别急着怀疑是 Psalm 的 bug。问题很可能出在自动加载层：

• 首先，在命令行跑一下 php -r "var_dump(class_exists('Xyz'));" —— 如果返回 false，那么问题出在 Composer，而不是 Psalm。
• 接着，仔细检查 composer.json 的 autoload 部分：是不是命名空间末尾少了反斜杠（比如把 "App\\" 写成了 "App"）？或者实际路径是 lib/ 却配置成了 src/？
• 对于第三方扩展（例如 ext-redis），它们本身不提供 PHP 类文件。这时才需要用到 配置，并且必须手动编写完整的存根文件，同时在 psalm.xml 中显式声明。

还有一个最容易被忽略的细节：当你新增了 PSR-4 映射，或者修改过 composer.json 后，必须手动再执行一次 composer dump-autoload。否则，Composer 根本不会感知到这些新类，Psalm 自然也就无法解析它们了。