企业官网建设流程全解析

简介：这是一份面向Java静态代码分析场景的PMD规则配置文件合集，适合使用Eclipse PMD插件、希望统一代码规范并减少潜在缺陷的开发者与项目团队。压缩包共10个文件，以9个XML规则配置和1个TXT说明为主，包体约35KB，体积轻便，便于导入、查阅和按类别调整检查项。内容围绕规则集、具体规则、类别划分、参数设置与排除项展开，能帮助读者理解PMD如何组织设计、冗余代码、复杂度等检查维度，并据此定制符合项目要求的代码审查策略，尤其适合中小型Java项目在建立基础质量规范前做规则梳理。已有1059人学习，说明其在PMD规则配置与落地实践中具有一定参考价值。对于需要提升代码可读性、控制复杂度、排查空块与无用导入等不良习惯的读者，这份配置可作为可直接参考的规则样例和修改起点。

1. PMD 规则文件装错位置，比不装还难查

PMD 的规则文件安装好，并不会自动生效。我在一台新构建机上装好 PMD，用默认 quickstart 规则跑了一遍，报告里全是「变量未使用」这类提示，团队真正在意的空 catch、魔法值、圈复杂度一条没出现——原因是命令行里-R还指着内置 rulesets，我写的 ruleset.xml 根本没被加载。静态扫描的坑大多不在工具本身，而在规则文件放哪、怎么引用、谁覆盖谁。

这套环境常见到什么程度：凡是 Java 项目要接代码门禁，PMD 基本是标配，而规则文件是唯一需要团队自己维护的资产。装不好不会立刻报错，只会安静地少查一半问题，等发现时已经带病上线好几版。这篇写给正在配 PMD 环境、被规则集加载顺序绕住的开发者，从选版本、解压、写 ruleset，一路到跑通验证。

2. 装 PMD 之前先把 JDK 和版本对齐

PMD 是个纯 Java 工具，装它本身没什么门槛，真正需要认真对待的是版本匹配：JDK 版本决定你能用 PMD 6 还是 PMD 7，PMD 版本决定你的规则文件能不能原样搬过来。我见过最常见的翻车现场，是把一套在 PMD 6 上调好的 ruleset 直接丢进 PMD 7 的发行包，命令行启动后直接抛规则引用解析失败，报错信息只说找不到某个 rule，不告诉你这个规则在新版本里被合并了。

2.1 PMD 6.55 与 PMD 7 的规则文件不通用

先说结论：PMD 6 的最后一个稳定分支是 6.55.0，PMD 7 从 7.0.0 起是一条新主线，两者的规则文件格式大体相同，但内部规则库和 XPath 引擎换了一茬。选哪个版本，取决于你项目里的 JDK。

如果你的项目还跑在 JDK 8 上，PMD 6.55.0 是最省事的选择，规则文件在网上能搜到的示例也大多是这一代的写法。如果项目已经切到 JDK 11 或更高，直接上 PMD 7，别再用旧版本撑，PMD 6 对新的语法特性支持有限，扫出来的漏报比误报更麻烦。

提示：版本不要靠「最新」两个字决定。先执行java -version看项目实际编译用的 JDK，再回头挑 PMD 大版本，这一步省不掉。

2.2 下载、解压与目录布局

PMD 的发行包是免安装的压缩包，解压即用。我一般把它放在/opt下，用一个不带版本号的软链接指向当前版本，这样换版本时只改软链接，所有脚本和 CI 配置都不用动。

# 固定工具目录，别放在 /tmp 或者下载文件夹里，清理一次就没了 sudo mkdir -p /opt/pmd cd /opt/pmd # 版本用变量收口，换版本时只改这一行 PMD_VER=7.0.0 curl -fsSLO "https://github.com/pmd/pmd/releases/download/pmd_releases%2F${PMD_VER}/pmd-dist-${PMD_VER}-bin.zip" # 校验压缩包完整性，下载中断的包解压出来会缺 jar unzip -q pmd-dist-${PMD_VER}-bin.zip # 软链接指向当前版本，后面所有路径都写 current ln -sfn /opt/pmd/pmd-bin-${PMD_VER} /opt/pmd/current ls -l /opt/pmd/current

命令里几个点值得说明。PMD_VER单独抽成变量，是为了让升级变成改一行的事；curl -fsSLO里的-f让 HTTP 错误码直接变成命令失败，避免把一个 404 页面当成 zip 存下来；ln -sfn的-n很关键，如果current已经是个指向目录的软链接，不加-n会在目标目录里面再建一个链接，路径越套越深，这种坑排查起来非常费时间。

解压后的目录结构大致是bin/、lib/、LICENSE三部分。bin/下是启动脚本，lib/下是一堆 jar 包。这里有个新手常踩的误区：想找内置规则文件，在解压目录里翻半天找不到rulesets/文件夹，就以为包下错了。实际上 PMD 的内置规则 XML 是打包在lib/pmd-java-*.jar内部的，要用的时候通过category/java/xxx.xml这种逻辑路径引用，不需要、也不应该去解压 jar 拿出来改。

# 想看内置规则到底有哪些，直接从 jar 里列出来 unzip -l /opt/pmd/current/lib/pmd-java-*.jar | grep 'category/java/.*\.xml'

这条命令列出来的就是当前版本所有可引用的内置规则集，包括bestpractices.xml、codestyle.xml、design.xml、errorprone.xml、multithreading.xml、performance.xml、security.xml、documentation.xml。写 ruleset 时ref属性里的路径必须和这里列出来的一字不差，少一个category/java/前缀就会解析失败。

2.3 环境变量与启动前的自检

PMD 的启动脚本会读取PMD_JAVA_OPTS这个环境变量，把里面的参数透传给 JVM。大项目扫描时默认堆内存不够，中途 OOM 是最常见的中断原因，所以这一项建议一开始就配上。

# 写进 ~/.bashrc 或者 CI 的环境准备段 export PMD_HOME=/opt/pmd/current export PATH="$PMD_HOME/bin:$PATH" # 扫描大型工程时默认堆不够，2g 起步；机器内存紧张就调到 1g 并配合 --cache export PMD_JAVA_OPTS="-Xms512m -Xmx2g"

PMD_HOME指向软链接而不是具体版本目录，这样升级时不用改环境变量。-Xms和-Xmx设成一样的值可以减少堆伸缩带来的停顿，不过对 PMD 这种一次性跑完就退出的进程来说影响不大，我通常只关心-Xmx别太小。

配完环境变量，先做一次不涉及任何自定义规则的自检，确认工具链本身是通的。

# PMD 7 的写法：子命令 check + 内置 quickstart 规则集 pmd check --dir src/main/java --rulesets rulesets/java/quickstart.xml --format text # PMD 6 的写法：没有子命令，直接跟参数 run.sh pmd -d src/main/java -R rulesets/java/quickstart.xml -f text

这条命令的意义在于把问题分层。如果连内置规则集都跑不出结果，那问题在 JDK、在 PATH、在参数写法，跟自定义规则文件没关系；如果内置规则跑得通，换成自己的 ruleset 就失败，排查范围立刻收窄到文件本身。运维排查最怕的就是一上来就混着改，先分层再定位，能省掉很多来回。

还有一点容易被忽略：PMD 做类型解析时需要知道项目的依赖类路径，也就是--aux-classpath参数。不传这个参数，PMD 依然能扫，但涉及类型判断的规则（比如某些最佳实践规则）会退化成语法层面的粗略判断，漏报率上升。用 Maven 或 Gradle 插件跑的时候插件会自动处理，用命令行裸跑就得自己把依赖 jar 拼成 classpath 传进去。

3. 写一份能落地的 ruleset.xml

规则文件不是一个配置文件那么简单，它本质上是「团队代码规范的机器可读版本」。直接从内置规则集里全量引用，扫出来的问题清单能长到没人愿意看；只挑三五条，又挡不住真正的问题。合理的做法是分层：一个基线文件管所有项目共用的部分，项目级的规则文件用ref引基线，再按需增删。

3.1 最小骨架与命名空间

先看一份能直接跑起来的最小骨架。这份文件我一般放在项目里的config/pmd/ruleset.xml，跟代码一起走版本控制。

<?xml version="1.0" encoding="UTF-8"?> <ruleset name="team-java-baseline" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.net/ruleset_2_0_0.xsd"> <description>Java 基线规则集，按增量方式维护</description> <!-- 单条引用：分类文件路径 + 斜杠 + 规则名 --> <rule ref="category/java/errorprone.xml/EmptyCatchBlock"/> <rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/> <!-- 整类引用，再用 exclude 剔除不适用的规则 --> <rule ref="category/java/codestyle.xml"> <exclude name="AtLeastOneConstructor"/> <exclude name="ShortVariable"/> </rule> <!-- 覆盖单条规则的优先级，1 最严重，5 最轻 --> <rule ref="category/java/design.xml/CyclomaticComplexity"> <priority>2</priority> </rule> </ruleset>

根元素上的命名空间必须写成http://pmd.sourceforge.net/ruleset/2.0.0，这是 PMD 6 和 PMD 7 共用的规则集 schema 版本号。有人手写时把它改成2.0，或者干脆漏掉xsi:schemaLocation，PMD 在加载阶段就会报 schema 校验错误，但错误信息通常只提到「无法解析元素」，不会直说是命名空间的问题。

<description>不是可选项，某些版本在缺少描述时会给出警告。更重要的是，这个字段是给后来接手的人看的，写清楚这套规则的取舍理由，比写「团队规则」四个字有用得多。

ref属性的路径规则是固定的：category/java/开头，中间是规则分类文件名，最后斜杠后跟具体规则名。整类引用时只写到.xml为止。这个格式不能省成java/errorprone.xml/EmptyCatchBlock，也不能写成相对路径。

<!-- 整类引用时，ref 只到 xml 文件 --> <rule ref="category/java/performance.xml"/> <!-- 单条引用时，ref 必须带规则名 --> <rule ref="category/java/performance.xml/AvoidInstantiatingObjectsInLoops"/>

这两种写法的区别不只是长短。整类引用会自动跟随 PMD 升级，新版本里这个分类新增的规则也会被带上，好处是覆盖全，坏处是升级后突然多出一批告警。单条引用则完全可控，升级不会带来额外噪音。我的习惯是：安全类、错误倾向类的规则整类引用，代码风格类一律单条引用，因为它们最容易在版本升级时新增条目。

3.2 include-pattern 与 exclude-pattern 的路径陷阱

真实项目里总有些目录不该被扫：自动生成的代码、第三方拷贝进来的类、构建产物。在命令行里逐个排除目录很啰嗦，更稳的做法是写进规则文件。

<ruleset name="team-java-baseline" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"> <description>带路径排除的基线规则集</description> <!-- 匹配的是传给 PMD 的文件路径，不是相对项目根目录的路径 --> <exclude-pattern>.*[\\/]generated[\\/].*</exclude-pattern> <exclude-pattern>.*[\\/]target[\\/].*</exclude-pattern> <exclude-pattern>.*[\\/]build[\\/]gen[\\/].*</exclude-pattern> <rule ref="category/java/errorprone.xml/EmptyCatchBlock"/> </ruleset>

exclude-pattern用的是正则，匹配对象是 PMD 实际拿到的文件路径。这一点非常关键：如果你在命令行里传的是绝对路径，那正则就得按绝对路径来写；传的是相对路径，正则匹配的就是相对路径。同一条正则在本地能排除、在 CI 上排除不掉，九成是两边传入的路径形式不一样。

路径分隔符是第二个坑。Linux 和 macOS 下是/，Windows 下是\，正则里写死/在 Windows 构建机上就会失效。用[\\/]这种字符组兼容两种分隔符，是成本最低的写法。.*放在前后两端，是因为正则默认是整串匹配而不是子串搜索，不写前后缀的话，路径里只要多一层目录就匹配不上。

3.3 用 properties 调阈值，用 priority 排门禁

规则文件真正体现团队意志的地方，在properties和priority这两个元素上。前者决定规则的门槛划在哪，后者决定哪类问题卡住合并、哪类只提示。

<!-- 圈复杂度：方法超过 12 就算超标，类总复杂度超过 60 告警 --> <rule ref="category/java/design.xml/CyclomaticComplexity"> <priority>2</priority> <properties> <property name="methodReportLevel" value="12"/> <property name="classReportLevel" value="60"/> </properties> </rule> <!-- 重复字面量：同一个字符串出现超过 8 次才提示，避免误报 --> <rule ref="category/java/optimization.xml/AvoidDuplicateLiterals"> <priority>4</priority> <properties> <property name="maxDuplicateLiterals" value="8"/> </properties> </rule>

methodReportLevel是单个方法的圈复杂度阈值，PMD 默认值通常是 10，团队如果业务分支本来就多，可以适当放宽到 12 到 15 之间；调到 20 以上基本等于放弃这条规则。classReportLevel管的是整个类的复杂度总和，适合发现那种什么都往里塞的巨型服务类。maxDuplicateLiterals控制重复字面量的容忍次数，默认值偏严，测试代码里常量复用少，很容易被刷屏，调到 8 左右比较实用。

属性名不是随便写的，必须和规则内部定义的属性名一致。写错了不会报错，PMD 会静默忽略这个属性，规则按默认值跑——这是最隐蔽的失效方式之一。

<!-- 验证某个规则支持哪些属性，直接看内置规则定义 --> unzip -p /opt/pmd/current/lib/pmd-java-*.jar 'category/java/design.xml' \ | grep -A 10 'name="CyclomaticComplexity"'

这条命令把 jar 里的规则定义打出来，属性名和默认值一目了然。改阈值之前先跑一遍，比猜快得多。

priority的取值是 1 到 5，数字越小越严重。它的作用不只是排序，还直接决定了门禁的松紧。命令行和构建插件都支持设置一个最低优先级阈值，低于阈值的规则不参与扫描，报告里自然也不会出现。实践中的分法是：1 到 2 留给会导致线上问题的规则，例如空 catch、资源未关闭；3 留给可维护性问题，例如方法过长；4 到 5 留给风格问题，先在报告里养着，团队习惯了再收紧。

3.4 自定义 XPath 规则要看清版本

内置规则覆盖不到团队的特殊约束时，就得自己写 XPath 规则。这部分是 PMD 6 升 PMD 7 迁移时最容易卡住的地方，因为 XPath 版本从 1.0 和 2.0 直接跳到了 3.1，底层解析器换了实现，表达式写法和语法兼容性都变了。

<rule name="AvoidConsolePrintln" language="java" message="业务代码不要直接用 println 输出，改用日志组件" class="net.sourceforge.pmd.lang.rule.xpath.XPathRule"> <description>匹配对 println 方法的调用</description> <priority>3</priority> <properties> <property name="xpath"> <value><![CDATA[ //MethodCall[@MethodName = ('println', 'print', 'printf')] ]]></value> </property> </properties> </rule>

class属性固定写net.sourceforge.pmd.lang.rule.xpath.XPathRule，PMD 6 和 PMD 7 都一样。真正变的是xpath属性里的表达式：这段用的是 PMD 7 的语法，靠MethodCall节点和@MethodName属性定位。同样的需求在 PMD 6 里要换成基于PrimaryPrefix和Name节点的写法，两者不能互换。

写自定义 XPath 规则之前，务必先用 AST 查看工具确认当前版本的实际节点名。PMD 发行包里带了 designer 工具，也可以直接用命令行的 AST 导出功能。

# 把某个 Java 文件解析成 AST，看清节点名和属性名再写 XPath pmd ast-dump --language java --file src/main/java/com/example/Demo.java

跳过这一步直接照抄网上的 XPath 示例，是迁移期最高频的翻车点。网上大量示例是 PMD 5 或 PMD 6 早期写的，节点名在新版本里早就改过，复制过来不会报语法错误，只会一条都匹配不到，让人误以为是规则文件没生效。

4. 接进构建流程：CLI、Maven、Gradle 三条路

规则文件写好后，得让它跑在该跑的地方。本地开发时用命令行图个快，CI 门禁必须挂在构建工具上，两条路都要走通，否则会出现「本地扫得出来、流水线看不见」的割裂。

4.1 命令行：先保证参数写对

PMD 7 的 CLI 做了子命令化改造，check是扫描入口，和 PMD 6 的裸参数调用差别不小。下面这段是 CI 脚本里常见的一版配置。

# PMD 7：扫描主源码目录，输出 sarif 格式给 CI 平台消费 pmd check \ --dir src/main/java \ --rulesets ./config/pmd/ruleset.xml \ --format sarif \ --report-file build/reports/pmd.sarif \ --minimum-priority 3 \ --aux-classpath "build/classes/java/main:$(cat cp.txt)" \ --no-fail-on-violation

逐项拆开看。--dir指定扫描目录，可以重复传多次；--rulesets就是规则文件路径，相对路径按当前工作目录解析，CI 里建议直接写绝对路径或基于环境变量拼出来的路径；--format决定报告格式，给机器读用sarif或xml，给人看用text或html；--report-file把结果落盘，不写这个参数结果只打到标准输出，脚本里不好二次处理。

--minimum-priority 3表示优先级数值大于 3 的规则不参与扫描，也就是只跑 1 到 3 档。这个数字要根据团队当前的告警消化能力调，一开始设成 5 全量跑，报告没人看得完，门禁形同虚设。

--aux-classpath传的是依赖类路径，格式和javac的 classpath 一致，Linux 下用冒号分隔，Windows 下用分号。这一步不做，类型解析相关的规则会静默降级。

--no-fail-on-violation需要特别说明：PMD 7 默认在有违规时返回非零退出码，CI 会直接判定这一步失败。如果希望先收集报告、后置到独立的质量门禁阶段，就加上这个参数；如果就是想让它在合并前卡住，反而要把它去掉，让退出码起作用。

PMD 6 对应的写法是：

# PMD 6：没有 check 子命令，参数用单横线风格 run.sh pmd \ -d src/main/java \ -R ./config/pmd/ruleset.xml \ -f text \ -r build/reports/pmd.txt \ -minimumpriority 3 \ -cache

两版命令放在一起看，容易出错的地方集中在三处：子命令有无、参数是双横线还是单横线、缓存的开关方式。PMD 6 需要显式加-cache才启用增量缓存；PMD 7 里缓存默认是开的，要关掉得用--no-cache。这个默认值的反转，会让从旧版迁过来的脚本行为发生变化，尤其是 CI 缓存目录没有正确挂载的时候，缓存反而成了脏数据来源。

4.2 Maven：插件版本和 PMD 版本要对齐

Maven 项目里用maven-pmd-plugin，配置写在pom.xml的build/plugins下。

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-pmd-plugin</artifactId> <version>3.21.2</version> <configuration> <!-- 用自定义规则文件，替换掉插件默认的规则集 --> <rulesets> <ruleset>${project.basedir}/config/pmd/ruleset.xml</ruleset> </rulesets> <!-- 告警时让构建失败，配合 CI 门禁 --> <failOnViolation>true</failOnViolation> <printFailingErrors>true</printFailingErrors> <!-- 只统计优先级 1-3 的规则 --> <minimumPriority>3</minimumPriority> <!-- 生成的源码不参与扫描 --> <excludeRoots> <excludeRoot>target/generated-sources</excludeRoot> </excludeRoots> </configuration> <executions> <execution> <phase>verify</phase> <goals> <goal>check</goal> </goals> </execution> </executions> </plugin>

<rulesets>里的${project.basedir}不能省。这是 Maven 里最值得坚持的一个写法，因为它把路径锚定在项目根目录，不管从哪个子模块目录执行mvn，规则文件都能被找到。用相对路径的写法在单模块项目里看不出问题，一进多模块构建就开始随机失败。

<minimumPriority>和命令行的阈值含义一致，数值越大扫得越宽。<excludeRoots>处理的是 Maven 自己生成的源码目录，这类目录不排除会带来大量无意义告警。

调用方式是mvn pmd:check或mvn pmd:pmd，前者会执行检查并按配置决定是否失败，后者只生成报告。绑到verify阶段后，mvn verify会自动带上。

需要留心的是插件和 PMD 的版本对应关系。maven-pmd-plugin内部捆绑了一个 PMD 版本，这个版本不一定等于你本地解压的那个发行包。两套 PMD 版本混用，会直接表现为「本地命令行能扫出来的问题，Maven 里扫不出来」，或者反过来。确认方式很简单：

# 看插件实际依赖的 PMD 版本 mvn dependency:tree -Dincludes=net.sourceforge.pmd

如果输出的版本和你预期的对不上，用插件配置里的<pmdVersion>显式锁定。这条经验是踩过坑之后才养成的习惯：团队里有人在本地用 7.x 调规则，CI 上插件带的还是 6.x，两边对同一份 ruleset 给出完全不同的结果，排查了半天才发现是版本不一致。

4.3 Gradle：清空默认规则集这一步不能漏

Gradle 内置了 pmd 插件，配置比 Maven 短，但有一个非常容易被忽略的默认行为。

plugins { id 'pmd' } pmd { // 显式锁定 PMD 版本，避免和本地命令行版本漂移 toolVersion = '7.0.0' // 用文件方式指定自定义规则集 ruleSetFiles = files("$rootDir/config/pmd/ruleset.xml") // 关键：清空默认规则集，否则会与上面的配置叠加 ruleSets = [] ignoreFailures = false consoleOutput = true } tasks.withType(Pmd).configureEach { reports { xml.required = true html.required = true } }

ruleSets = []这一行是整段配置里最要紧的。Gradle 的 pmd 插件默认会加载category/java/bestpractices.xml和category/java/errorprone.xml这两个内置规则集，ruleSetFiles是叠加而不是替换。只写ruleSetFiles不清空ruleSets，实际生效的规则是「默认两个分类 + 你的自定义文件」的并集，告警量会比预期多出一大截，而且多出来的部分完全不受你的 ruleset 控制。

toolVersion也建议显式写。不写的话用插件默认版本，Gradle 版本升级时这个默认值可能跟着变，某天突然多出一批新告警，追查起来毫无头绪。

报告输出部分，xml.required建议打开，CI 平台解析 XML 做趋势统计比解析 HTML 稳定得多；html.required留给本地排查时人工看。

三条路都配过之后，有一个判断标准可以自检：同一份代码、同一份 ruleset，命令行、Maven、Gradle 三处跑出来的违规条数和规则名应当完全一致。只要有一处对不上，先查 PMD 版本，再查规则集是否被叠加，最后查 classpath，顺序不要乱。

5. 排查：规则文件不生效的五个现场

规则文件这条链路上，失败往往是静默的。加载成功但匹配不到、匹配到了但被阈值过滤掉、过滤掉了但报告没落盘，每一种表现都像「工具坏了」。下面五条是我实际遇到过的现场，按现象、原因、解决拆开写。

5.1 现象：命令跑完退出码为 0，报告文件是空的

原因通常有两个方向。一是扫描目录里确实没有可扫的源文件，--dir指错了一层，或者指向了一个只放资源的目录；二是exclude-pattern写得太宽，正则把整个源码树都排除了，比如写成.*src.*，本意是排除某个子目录，结果把所有路径里带 src 的文件全干掉了。

解决方式是先做减法。把 ruleset 换成内置的rulesets/java/quickstart.xml跑一遍，确认工具能扫到文件；再换回自定义 ruleset，逐条注释掉exclude-pattern观察结果变化。同时在命令里加--debug，它会打印实际参与扫描的文件列表，一眼就能看出是路径指错还是被排除规则吃掉。

# 打开调试输出，确认哪些文件真正进入了扫描队列 pmd check --dir src/main/java -R ./config/pmd/ruleset.xml -f text --debug 2>&1 | grep -i 'processing'

5.2 现象：加载 ruleset 时直接抛 XPath 相关异常

报错信息里带XPathException、XPST开头的错误码，或者提示表达式无法编译。原因是自定义 XPath 规则用了旧版本语法。PMD 6 支持 XPath 1.0 和 2.0，PMD 7 只认 3.1，很多在旧版能跑的表达式在新版里语法就不合法了。

解决办法不是硬改表达式，而是先用ast-dump看清当前版本的实际 AST 结构，再重写。改完之后在规则文件里只留这一条规则单独跑一遍，确认能匹配到目标代码，再合并回主规则集。一次性改一批 XPath 规则然后整体运行，出错时根本分不清是哪一条的问题。

# 单独验证一条自定义规则 pmd check --dir src/main/java -R ./config/pmd/xpath-only.xml -f text

5.3 现象：CI 上报「无法解析规则引用」，本地却正常

本地跑得好好的，进了流水线就报规则或规则集引用无法解析。九成是路径解析基准不同。命令行里的相对路径按当前工作目录解析，CI 的构建步骤往往在子目录里执行，相对路径的起点就变了。

另一小部分是ref写法不完整，比如漏了category/java/前缀，或者单条引用时忘了在斜杠后写规则名。这种错误在本地可能因为别的规则集碰巧也有同名规则而蒙混过关，换台机器就暴露。

解决方式很直接：规则文件路径一律用绝对路径或者基于项目根目录变量拼出来，Maven 用${project.basedir}，Gradle 用$rootDir，CI 脚本里用$(pwd)拼。ref属性逐个核对，格式只有两种，写全就对了。

5.4 现象：本地和 CI 的违规条数对不上，行号也有偏差

同一份代码，本地扫出 30 条，CI 扫出 47 条，或者同一条违规报在不同行上。原因一般是三件事之一：PMD 版本不同、JDK 版本不同、classpath 不同。

PMD 版本的差异会带来规则本身的新增和删除，这是最直接的原因；JDK 版本不同会影响语法解析，高版本 JDK 的新语法在低版本 PMD 里可能解析失败被跳过；classpath 缺失会让类型解析降级，某些依赖类型判断的规则要么漏报要么误报。

解决办法是把版本和 classpath 都固定下来。CI 镜像里装的 PMD 版本写死，构建工具里用toolVersion或pmdVersion锁定，--aux-classpath在裸跑命令行时必须传。这三项固定之后，两边结果不一致的情况基本消失。

# 打印版本信息，和 CI 日志里的对照 pmd --version java -version

5.5 现象：扫描跑到一半 OOM，或者卡在一个大文件上不动

大项目上很常见。默认堆内存不够是最直接的原因，尤其是规则集里加了复杂的 XPath 规则之后，单文件的分析开销会成倍上升。另一个诱因是没开增量缓存，每次全量重扫，机器再快也扛不住天天跑。

处理顺序是：先加-Xmx，PMD 6 里通过PMD_JAVA_OPTS传给 JVM；再开缓存，PMD 6 加-cache，PMD 7 默认就开着、确认没被--no-cache关掉；最后才是优化规则，把那些扫描代价高、收益又低的 XPath 规则降级或者移到独立的慢速任务里。

# 提高堆上限，同时确认缓存文件落在可持久化的目录 export PMD_JAVA_OPTS="-Xmx3g" pmd check --dir src/main/java -R ./config/pmd/ruleset.xml \ --cache --cache-location build/.pmd-cache -f text

缓存文件位置值得单独说一句。默认缓存写在当前工作目录，CI 上如果工作目录是临时目录，每次构建都是干净的，缓存等于没开。显式指定到一个被 CI 缓存机制覆盖的路径，才能真正生效。反过来也要注意：升级 PMD 版本后缓存格式可能不兼容，遇到莫名其妙的扫描结果缺失，先删缓存文件重跑一次，这是成本最低的排除法。

6. 装完怎么验证：拿一个故意写脏的类跑通全链路

规则文件配好之后，不要拿业务代码去验证。业务代码的问题数量不可预期，跑出来的结果你没法判断是规则生效了还是原本就这么多。我固定用一个三行就能写完的脏类做冒烟测试，它同时触发两条不同类型的规则，一条来自错误倾向分类，一条来自最佳实践分类，正好覆盖单条引用和整类引用两种配置方式。

// config/pmd/smoke/SmokeDemo.java public class SmokeDemo { public int divide(int a, int b) { int unused = 0; // 触发 UnusedLocalVariable try { return a / b; } catch (Exception e) { // 触发 EmptyCatchBlock } return 0; } }

把它放进一个临时目录，用你的 ruleset 扫一遍，期望的产出是两条违规，规则名、优先级都要和规则文件里的配置对得上。

pmd check \ --dir config/pmd/smoke \ --rulesets ./config/pmd/ruleset.xml \ --format text

这个冒烟类的价值在于可重复。每次改完 ruleset、每次升级 PMD 版本、每次调整 CI 配置，都先跑它。两条都出来，说明加载链路是通的；只出来一条，说明另一条规则的引用写法有问题；一条都不出来，问题在路径或版本，不在规则内容。

我还会额外跑一次「反向验证」：把 ruleset 里EmptyCatchBlock那行注释掉，重新扫，确认违规条数从 2 变成 1。如果注释掉之后还是 2，说明这个规则是从别的地方被带进来的——比如构建工具默认规则集没清空，或者 ruleset 里还有一条整类引用把它包含进去了。正向验证只能证明「规则跑起来了」，反向验证才能证明「规则是从你以为的那个地方来的」。

这套 ruleset 骨架、冒烟类和三份构建配置我整理在一起放在下载包里了，目录结构和本文的章节一一对应，解压后按项目路径替换就能用，不用从零拼。

从那以后我每次接新项目，都会先把那个三行的脏类复制进去跑一遍，确认规则文件真的被加载、真的按配置的优先级输出，再动业务代码。静态扫描最怕的不是误报多，而是你以为它在看着，其实它一直没睁眼。希望帮到你。

本文还有配套的精品资源，点击获取