Duster 配置完全手册：include、exclude、scripts 与 processTimeout 全解析-平芜编程栈

Duster 配置完全手册：include、exclude、scripts 与 processTimeout 全解析

【免费下载链接】dusterAutomatic configuration for Laravel apps to apply Tighten's standard linting & code standards.项目地址: https://gitcode.com/gh_mirrors/du/duster

Duster 是一款专为 Laravel 应用打造的代码规范 linting 工具，可自动应用 Tighten 团队默认的 PHP 代码风格。它的核心配置全部集中在项目根目录的duster.json文件中，通过include、exclude、scripts和processTimeout四个关键字段，你可以精确控制 Duster 检查哪些文件、跳过哪些文件、追加哪些自定义脚本，以及脚本运行的超时时间。本文带你一次性掌握 Duster 配置的完整用法。

快速上手：安装 Duster 并运行首次检查

使用 Composer 一行命令安装 Duster：

composer require tightenco/duster --dev

安装完成后，两条命令即可分别完成"检查"与"自动修复"：

./vendor/bin/duster lint # 检查所有代码问题 ./vendor/bin/duster fix # 自动修复所有可修复的问题

当你需要更精细的控制时，只需在项目根目录创建duster.json配置文件。Duster 启动时会自动读取该文件，加载逻辑位于 app/Support/DusterConfig.php 的loadLocal()方法中——如果文件不是合法的 JSON，Duster 会直接报错提示，这一点在配置时务必注意。

配置 include：精确指定 Duster 检查哪些目录

include字段以数组形式列出需要检查的目录或文件，只会被其中包含的 PHP 文件处理。Duster 默认只识别这几种后缀：.php、.php.inc、.php.stub、.php.skeleton（见 DusterConfig.php）。

一个典型的 Laravel 项目配置如下：

{ "include": [ "bin", "scripts", "src", "tests" ] }

🔍小贴士：include支持通配符写法。例如"**/Include2/**"可以递归匹配任意层级下的Include2目录。官方测试用例 tests/Fixtures/DusterConfigWildcard/duster.json 就演示了通配符 include/exclude 的实际效果，扩展实现位于 DusterConfig.php 的expandWildcards()方法。

配置 exclude：跳过不想被检查的文件

exclude字段用于排除测试夹具、生成文件等不希望 Duster 介入的内容。Duster 内置了一份默认排除列表（DusterConfig.php 中的$defaultExclude），已经自动包含：

默认排除项	说明
`vendor/`	Composer 依赖目录
`node_modules/`	前端依赖目录
`storage/`	运行时存储目录
`bootstrap/cache/`	框架缓存目录
`build/`	构建产物目录
`_ide_helper.php`等	IDE 辅助文件
`tests/Pest.php`	Pest 测试框架引导文件

⚠️注意：这些路径会被自动排除，你在exclude里再写一遍vendor或node_modules是多余的，Duster 会直接过滤掉这类重复项。实际项目中通常只需排除测试夹具即可：

{ "exclude": [ "tests/Fixtures" ] }

exclude同样支持通配符，比如"**/folderToExclude/**"可排除任意深度的指定文件夹。Duster 自身仓库的配置 duster.json 就是很好的参考范例。

配置 scripts：让 Duster 顺带运行你的自定义脚本

这是 Duster 最强大的能力之一——它不仅能跑内置的 TLint、PHP_CodeSniffer、PHP CS Fixer 和 Pint，还能把你的 PHPStan、Pest 等任意脚本编排进统一的 lint / fix 流程。

在scripts下按lint和fix两个分组声明，键是脚本名称，值是命令参数数组：

{ "scripts": { "lint": { "phpstan": ["./vendor/bin/phpstan", "analyse"], "pest": ["./vendor/bin/pest"] } } }

之后运行duster lint时，这些脚本会被自动执行；某个脚本失败会导致整体流程失败，非常适合接入 CI。

如果你只想运行指定工具，可以用--using参数按名称挑选并控制执行顺序：

./vendor/bin/duster lint --using="phpstan,tlint,pint"

脚本的执行与超时处理逻辑见 app/Support/UserScript.php。

配置 processTimeout：自定义脚本超时时间

自定义脚本默认在60 秒后超时。如果你的 PHPStan 分析或 Pest 测试跑得比较久，可以用processTimeout字段（单位：秒）覆盖默认值：

{ "processTimeout": 120 }

⏱️ 如果超时发生，Duster 会打印友好的提示信息，直接告诉你"可以用 duster.json 中的 processTimeout 键来覆盖此超时"，无需翻文档就能定位问题。

完整配置示例：四字段一次配齐

把前面四部分内容组合起来，就是一份功能齐全的duster.json：

{ "include": [ "app", "config", "tests" ], "exclude": [ "tests/Fixtures" ], "scripts": { "lint": { "PHPStan": ["./vendor/bin/phpstan", "analyse"] } }, "processTimeout": 120 }

这份配置的来源正是 Duster 仓库自身的 duster.json，可直接复制后按项目结构调整。

新手常见疑问 🧹

必须创建 duster.json 吗？不是。不创建时 Duster 使用内置的默认行为；创建后即可获得目录级、脚本级的完全控制权。
通配符怎么写？使用标准的 glob 语法，如**/folder/**；路径分隔符统一用/，Windows 下也会被自动兼容。
为什么我加了 exclude 的 vendor 没生效？因为vendor/本就在默认排除列表中，无需重复配置。
如何验证配置是否生效？运行./vendor/bin/duster lint，观察输出的文件列表即可确认 include/exclude 是否符合预期；参考测试 tests/Feature/DusterConfigTest.php 中的验证方式。

掌握include、exclude、scripts与processTimeout这四个字段，你就拥有了 Duster 的全部配置能力——从此一条命令，让团队的 Laravel 代码风格保持一致。

【免费下载链接】dusterAutomatic configuration for Laravel apps to apply Tighten's standard linting & code standards.项目地址: https://gitcode.com/gh_mirrors/du/duster

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考