Checkstyle插件在IDEA里不生效？先确认是否绑定了正确配置文件
IDEA自带的Checkstyle插件默认不加载任何规则，它只是个壳子，真正起作用的是你指定的checkstyle.xml。常见现象是：插件装了、也启用了，但代码改得再随意也没红标——大概率是配置文件路径填错，或者文件本身语法有误。
实操建议：
- 用
File → Settings → Tools → Checkstyle打开配置页，Configuration File选Use a local Checkstyle file - 路径填绝对路径（比如
/Users/xxx/project/checkstyle.xml），别用相对路径或~符号，IDEA不认 - 点
Next后如果报错Cannot find resource 'google_checks.xml'这类提示，说明你引用了外部资源（如 - 配置文件保存后，务必点
Apply再点OK，只点OK不会生效
Maven中启用Checkstyle执行检查，checkstyle:check总失败？看清楚是哪个阶段触发的
很多人以为加了maven-checkstyle-plugin就能自动拦住不合规代码，结果mvn compile照常通过，直到CI上跑mvn verify才爆红——这是因为Checkstyle默认绑定在verify阶段，不是compile或test。
实操建议：
- 在
pom.xml里确认<execution><id>checkstyle-check</id><phase>verify</phase><goals><goal>check</goal></goals></execution>
- 想让本地开发更敏感，可改成
compile verify - 如果只想检查不中断构建，把
true false，但别在CI里这么干 - 运行命令时明确指定生命周期，比如
mvn checkstyle:check是跳过绑定阶段直接执行，而mvn verify才会触发绑定的检查
自定义规则写进checkstyle.xml没反应？检查模块层级和属性拼写
Checkstyle对XML结构极其敏感，一个s（比如format写成formt），整条规则就静默失效。最典型的是MethodLength写了却不限制方法行数，八成是
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
实操建议：
- 所有规则必须挂载在
TreeWalker子模块，多嵌套一层TreeWalker会导致规则被忽略 - 属性名严格按官方文档来，比如
LineLength用max，MethodLength也用max，不是maxLength或maximum - 正则类规则（如
RegexpSingleline）的format值要转义反斜杠，Java字符串里写\s+，XML里就得写\s+（即四个反斜杠） - 改完配置后，在IDEA里右键单个Java文件选
Check Current File with Checkstyle，比等整个mvn verify快得多，能快速验证规则是否真生效
团队协作时规则不一致？别只靠IDEA插件，Maven配置才是唯一事实源
不同人IDEA里可能选了不同的checkstyle.xml，甚至有人根本没装插件，导致本地“看着没问题”、CI上批量报错。真正的统一控制点只有一个：pom.xml里的插件配置和配套的配置文件。
实操建议：
- 把
checkstyle.xml放在项目根目录（如config/checkstyle/checkstyle.xml），并在pom.xml里用相对路径引用：config/checkstyle/checkstyle.xml - IDEA插件的配置文件路径也指向这个位置，确保和Maven一致
- 在
README.md里写一句：“Checkstyle规则以pom.xml中maven-checkstyle-plugin配置为准”，避免新人乱改IDE设置 - 如果用了Spring Boot，注意它的
spring-boot-starter-parent可能自带Checkstyle配置，会覆盖你自己的，得显式
规则越细，XML里容易漏掉的闭合标签越多；多人共用一个配置文件时，合并冲突最容易破坏结构。每次改完，用mvn checkstyle:check快速过一遍，比等PR被CI打回来省事得多。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
