变灰表示PhpStorm静态分析判定符号未被读取或调用，但不等于无用，需人工验证；常见原因包括未启用相关检查、PHP版本不匹配、动态变量、反射或魔术方法等逃逸分析场景。
代码变灰 = PhpStorm 判定该符号当前未被读取或调用，但不等于“绝对无用”——它只是静态分析的初步提示，需人工验证。
为什么变量/函数会变灰
PhpStorm 默认启用 Unused local variable 和 Unused function 检查，一旦发现某个声明在作用域内没有被“读取”（如赋值后没再出现、函数定义后没被调用），就会将其标为灰色。常见触发场景包括：
-
foreach ($items as $item) { process($item); }中的$item变灰：可能因process()缺少@param注解，或 PHP Language Level 设置过低（如设为 PHP 7.4 却用了 PHP 8.2 的短闭包），导致 PhpStorm 无法追踪参数流向 -
$tmp = json_encode($data);后再无引用：会被标灰，即使它本意是调试打点——Report variables used only for writing默认关闭，需手动勾选才能捕获这类“写即弃”变量 - 类中
private $cache;不会变灰：它属于“未使用类成员”，需单独开启Unused private field检查，且仅在全局扫描（Inspect Code…）中生效，编辑器内不实时高亮 - 用
extract($arr)或${$key} = $val动态创建的变量，PhpStorm 完全无法识别，也不会变灰——这类代码天然逃逸静态分析
变灰 ≠ 可直接删除
灰色只是警告，不是判决。盲目删除可能破坏运行时逻辑：
- 变量可能被
__get()/__set()间接访问，或通过反射（ReflectionProperty）读取，静态分析看不到 - 函数可能被字符串调用：
$fn = 'helper_' . $type; $fn();，PhpStorm 不解析变量拼接的函数名 - 类型别名（
type Foo = string;）或接口（interface Bar）若被其他类型extends或&组合，即使没直接实例化，删掉也会导致类型断裂 - 测试文件（
*Test.php）中的声明常被主逻辑忽略，但实际被 PHPUnit 调用——需确认扫描范围是否包含测试目录
怎么安全清理变灰的代码
靠悬停 Alt+Enter → Remove unused declaration 只适用于单个、上下文明确的局部变量；批量清理必须走全局路径：
立即学习“PHP免费学习笔记（深入）”；
- 右键项目根目录 →
Inspect Code…→ 范围选Whole project，Profile 用Default（确保含Unused symbols） - 扫描完成后，在
Inspection Results窗口中展开PHP → Unused symbols，点击右上角Export to File导出 CSV - 用 Excel 或文本工具按
file path和line number排序，逐条核对：是否在tests/下？是否被注释块包裹？是否出现在 YAML/JSON 配置的类名字符串里？ - 确认无误后，回到编辑器，打开对应文件，手动删除——不要依赖 “Apply fix” 批量删，它不区分上下文，容易误伤
真正容易被忽略的是：unset() 是运行时行为，而变灰提示纯属静态分析；你删掉一个变量，不代表它没在某次请求中被动态写入并影响后续逻辑。清理前，先跑一遍覆盖率报告（phpdbg -qrr vendor/bin/phpunit --coverage-html coverage），看哪些代码路径确实从未执行过，比单纯盯灰色更可靠。
