Rector 安装后不能直接使用，因其依赖项目自动加载配置、PHP 版本兼容性及 --dev 安装；常见问题包括 autoload 未定义、PHP 版本不匹配、误入生产依赖；必须手动创建 rector.php 等三个配置文件。
Composer 安装 Rector 没有“一键升级”这回事，直接 composer require rector/rector --dev 装上后，不配置规则、不指定 PHP 版本、不处理自动加载问题，跑起来大概率报错或什么也不改。
为什么 composer require rector/rector --dev 装完不能直接用
Rector 不是普通库，它依赖当前项目已有的自动加载机制和 PHP 语法兼容性。常见卡点：
- 项目用了
psr-4但未在composer.json的"autoload"或"autoload-dev"中正确定义，Rector 扫描时类找不到，静默跳过 - 项目 PHP 版本是 7.4，却用了
rector/rector:^1.0（要求 PHP 8.1+），composer install可能成功，但运行vendor/bin/rector process直接抛Fatal error: Uncaught Error: Call to undefined function - 安装时没加
--dev，导致 Rector 进了生产依赖，CI 构建时被误删（尤其用了composer install --no-dev）
必须手动补全的 3 个配置文件
装完只是第一步，以下三个文件缺一不可：
-
rector.php：根目录下，必须存在。哪怕只写<?php use RectorConfigRectorConfig; return static function (RectorConfig $config): void { $config->paths(['src', 'tests']); };，否则报Could not find rector.php config file -
composer.json中的 autoload：确保要重构的目录（如src/）已在"autoload": {"psr-4": {"App\": "src/"}}里声明；如果只在"autoload-dev"里，Rector 默认不读（除非显式调--autoload-file composer.json） -
.gitattributes（可选但推荐）：加上* text=auto eol=lf，避免 Windows 换行符导致 Rector 行号错位、补丁失败
rector process 常见失败原因和对应命令参数
不加参数硬跑，90% 情况下会提示 “No changes” 或 “PHP Parse Error”。关键参数不是可选，是刚需：
- 加
--dry-run：先看会改什么，别直接写入。尤其第一次用，不加这个等于闭眼动手术 - 加
--level php80（或php74、symfony60）：不指定 level，Rector 默认不启用任何规则。别信文档里“自动检测版本”，它不会猜你目标版本 - 加
--no-progress-bar：CI 环境下无 TTY，不加这个会卡住或报Unable to open console - 路径必须明确：
vendor/bin/rector process src/ --level php80 --dry-run，别只写process就回车
升级 PHP 版本时最易忽略的陷阱
比如从 PHP 7.4 升到 8.1，你以为加 --level php81 就够了？其实还有两处硬伤：
-
mbstring.func_overload已废弃，但 Rector 不会帮你删ini_set('mbstring.func_overload', 2)—— 这得靠自定义规则或 grep 手动清 -
mysql_connect()这类函数在 PHP 8.0+ 彻底移除，但 Rector 的php80level 只处理mysql_* → mysqli_*，不覆盖已删除函数的兜底逻辑（比如是否用了@抑制错误） - 第三方包的兼容性：Rector 改了你的代码，但
monolog/monolog:^2.0在 PHP 8.1 下可能仍需手动升到 ^3.0，否则运行时报Deprecated: Return type of Monolog...
真正麻烦的从来不是 Rector 能改什么，而是它明确告诉你“这部分我不管”，然后留给你一堆需要人工判断的边界情况。
