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 自然也就无法解析它们了。
