phpinsights安装失败主因是PHP版本＜8.0或缺失json/mbstring/xml/tokenizer扩展；配置失效因路径错误、strict_types声明不兼容或检查器名拼写错误；运行卡顿因默认扫描范围过广，需在配置中限定paths并调高内存限制。
Composer 安装 phpinsights 失败：常见报错和前置条件
直接运行 composer require --dev nunomaduro/phpinsights 失败，大概率不是命令写错了，而是 PHP 版本或扩展不满足。phpinsights 当前（v2.x）要求 PHP ≥ 8.0，且必须启用 json、mbstring、xml 和 tokenizer 扩展——缺一个都会在 composer install 阶段报错，比如：
PHP extension "tokenizer" is required but not loaded.
- 用
php -m | grep -E "(json|mbstring|xml|tokenizer)"快速核对已加载模块 - Windows 用户注意：XAMPP/MAMP 默认可能没开
tokenizer，需手动改php.ini - 如果项目已锁死 PHP 7.4，别硬升，改用 phpinsights v1.19（最后支持 7.4 的版本），安装时加
@v1.19
phpinsights 配置文件不生效：为什么 .phpinsights.php 被忽略
放了配置文件却还是跑默认规则？phpinsights 只认两种路径：.phpinsights.php（项目根目录）或 phpinsights.php（同级），且必须返回一个数组。常见失效原因：
- 文件里用了
declare(strict_types=1)但 PHP 版本低于 7.0 —— phpinsights v2 不再兼容 strict_types 声明 - 配置数组里写了不存在的检查器名，比如把
'PhpCsFixer' => true写成'PhpCsFixerFixer' => true，整个配置会被静默跳过 - 用
php artisan insights（Laravel 场景）但没发布配置：先跑php artisan vendor:publish --provider="NunoMaduro\PhpInsights\Application\Adapters\Laravel\InsightsServiceProvider"
运行 phpinsights 卡住或报内存不足
大项目首次运行常卡在 “Analyzing files…” 或直接抛 Fatal error: Allowed memory size exhausted。这不是 bug，是默认分析范围太宽：
- 默认扫描
app/、src/、tests/下所有 PHP 文件，包括 vendor 里的测试工具代码（比如phpunit/phpunit自带的src/Framework/） - 在
.phpinsights.php中显式限制路径：'paths' => ['app', 'src', 'tests/Unit']，排除tests/Feature或vendor - 临时提内存：运行时加
-d memory_limit=-1，例如php -d memory_limit=-1 vendor/bin/phpinsights
分数不准或规则冲突：为什么有些 “严重问题” 没被标红
phpinsights 的分数是加权计算，不是简单计数。比如 Complexity 权重 25%，DuplicatedCode 权重 15%，即使后者问题更多，总分也可能被前者拖低。更关键的是规则实际是否启用：
立即学习“PHP免费学习笔记（深入）”；
-
phpinsights默认禁用部分高误报规则（如ForbiddenDefine），要启用得在配置里设'ForbiddenDefine' => true - Laravel 项目里
config/*目录默认被排除在分析外，但如果你的业务逻辑写在config/services.php里，这部分就完全不会被扫到 - 分数面板里 “Maintainability” 和 “Architecture” 是基于静态 AST 分析，不执行代码；而 “Style” 类规则依赖 php-cs-fixer，两者引擎不同，修复建议可能打架
配置文件里每个开关都得对应到具体检查器名，拼错一个字母就等于没开——这点很容易被当成“没效果”而放弃调试。
