Lombok 不生效 —— 从排查到可运行 Demo（含实战解析）

网罗开发（小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

前言

先说结论：Lombok 常见“不生效”的原因通常不是 Lombok 本身坏了，而是 IDE/构建器/项目配置没把注解处理（annotation processing）和依赖装好。下面用一个可运行的 Maven Demo把问题复现、讲清原因、给出逐步解决方案，并把常见坑和场景经验都写清楚，方便你在真实项目里快速定位。

语言风格尽量口语化、贴近日常交流。每个部分都给出足够细节，代码模块给出完整文件，方便你复制跑起来。

问题复现

我们做一个最简单的例子：用 Lombok 的 @Data 注解在 Person 上，然后在 Main 里 new 一个 Person 并调用 getName()。如果 Lombok 不生效，IDE 会提示找不到 getName() 或者编译期/运行期报错。

项目结构（Maven）：

lombok-demo/
├─ pom.xml
└─ src/└─ main/└─ java/└─ com/example/├─ Main.java└─ Person.java

Person.java（期望 Lombok 生成 getter/setter）:

package com.example;import lombok.Data;@Data
public class Person {private String name;private int age;
}

Main.java:

package com.example;public class Main {public static void main(String[] args) {Person p = new Person();p.setName("Alice");System.out.println("name = " + p.getName());}
}

如果 Lombok 不生效，IDE 会红线 setName/getName 或者 mvn package 报错：cannot find symbol: method setName(java.lang.String)。

为什么会不生效

1. IDE 没安装 Lombok 插件

   • IntelliJ IDEA：需要安装 Lombok 插件以便 IDE 识别 Lombok 生成的结构（否则你会看到红线，尽管 Maven 编译可能能通过）。
   • Eclipse：需要 Lombok jar 安装到 Eclipse。

2. 注解处理器（Annotation Processors）没开启

   • Lombok 生成代码依赖编译时注解处理，IDE 中必须开启注解处理，否则即便依赖在 pom/gradle 中，IDE 在编译/提示时也不会运行注解处理器。

3. 依赖引入方式不对（作用域错误）

   • 常见错误：把 Lombok 设为 provided（Maven）或 compileOnly（Gradle）在 IDE 中没有相应配置时导致编译器不跑注解处理。
   • 正确做法：Maven 使用 compile（或默认），Gradle 推荐 compileOnly + annotationProcessor 配置（见下方样例）。

4. 模块化 (module-info.java) 问题

   • 在使用 Java Module 时，Lombok 和注解处理可能需要额外配置或额外 opens / exports。某些情况下需要在 javac 参数里加上 --add-exports/--add-opens。

5. IDE 缓存或索引问题

   • 有时插件安装/配置后需要重启 IDEA 或者 Invalidate Caches & Restart。

6. Lombok 版本与 JDK 不兼容

   • 用非常新的 JDK（比如 21+）时要确认 Lombok 版本支持该 JDK。更新 Lombok 到最新稳定版通常能解决。

7. 构建工具配置问题（Gradle/Maven）

   • Gradle：如果只加了 compileOnly 没加 annotationProcessor，命令行编译可能会失败或生成代码不完整。
   • Maven：通常只加依赖即可，但如果你使用 maven-compiler-plugin 的自定义配置，要确认 annotation processors 没被关闭。

一步一步解决方案（IDE + 构建工具）

下面把常见场景按步骤写清楚，方便你逐项排查。

1) IntelliJ IDEA（最常见）

• 安装插件：Settings / Plugins -> 搜索 Lombok -> 安装 -> 重启 IDEA。
• 开启注解处理：Settings / Build, Execution, Deployment / Compiler / Annotation Processors -> 勾选 Enable annotation processing。
• 重启项目：Build -> Rebuild Project。若仍红线：File -> Invalidate Caches / Restart。
• 若使用 module-info.java：需要确保 module 描述里包含 opens/exports（视情况而定）。

2) Maven 项目

在 pom.xml 中添加依赖（示例使用较新稳定版本）：

<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.32</version><scope>provided</scope> <!-- IDEA 识别要插件，Maven 构建可用另外配置（可用 compile） -->
</dependency>

说明：很多人用 provided，但这会让 IDE 在某些配置下不触发注解处理。比较稳妥的是不指定 provided，即默认 compile，或者如果你更想用 provided（运行时不需要），确保注解处理器在构建时能被找到。

如果你使用 maven-compiler-plugin 有自定义 annotationProcessorPaths，可以把 Lombok 放进去：

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.32</version></path></annotationProcessorPaths></configuration>
</plugin>

然后在终端运行：

mvn clean package
# 或者直接运行类
mvn -q exec:java -Dexec.mainClass="com.example.Main"

3) Gradle 项目

build.gradle（Groovy）示例：

plugins {id 'java'id 'application'
}group 'com.example'
version '1.0-SNAPSHOT'
mainClassName = 'com.example.Main'repositories {mavenCentral()
}dependencies {// Lombok 用 compileOnly + annotationProcessor 的组合compileOnly 'org.projectlombok:lombok:1.18.32'annotationProcessor 'org.projectlombok:lombok:1.18.32'testImplementation 'junit:junit:4.13.2'
}

然后

./gradlew clean build
./gradlew run

完整 Maven 可运行 Demo

下面给出完整 pom.xml、两个 Java 源文件、以及一个单元测试，按着目录直接粘到本地运行。

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>lombok-demo</artifactId><version>1.0-SNAPSHOT</version><properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target></properties><dependencies><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.32</version><scope>provided</scope></dependency><dependency><groupId>junit</groupId><artifactId>junit</artifactId><version>4.13.2</version><scope>test</scope></dependency></dependencies><build><plugins><!-- 用 maven-compiler-plugin 指定 annotationProcessorPaths，保证命令行编译时 Lombok 可用 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><annotationProcessorPaths><path><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.32</version></path></annotationProcessorPaths></configuration></plugin><!-- exec 插件，用来直接运行 Main --><plugin><groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.1.0</version></plugin></plugins></build>
</project>

src/main/java/com/example/Person.java

package com.example;import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.AllArgsConstructor;
import lombok.Builder;@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Person {private String name;private int age;
}

src/main/java/com/example/Main.java

package com.example;public class Main {public static void main(String[] args) {// 使用 Lombok 生成的 builder、setter/getterPerson p = Person.builder().name("Alice").age(28).build();System.out.println("name = " + p.getName() + ", age = " + p.getAge());// 使用无参构造 + setterPerson p2 = new Person();p2.setName("Bob");p2.setAge(35);System.out.println("p2 = " + p2);}
}

src/test/java/com/example/PersonTest.java

package com.example;import org.junit.Test;
import static org.junit.Assert.*;public class PersonTest {@Testpublic void testLombokGeneratedMethods() {Person p = new Person();p.setName("Test");assertEquals("Test", p.getName());}
}

运行方法：

mvn clean test
mvn -q package
mvn -q exec:java -Dexec.mainClass="com.example.Main"

期望输出：

name = Alice, age = 28
p2 = Person(name=Bob, age=35)

如果运行报错或 IDEA 中看到红线，回到“第三节逐项解决”按步骤检查。

真实场景下的经验与注意事项

1. 公司项目里多模块（multi-module）时，某个子模块没正确引入 Lombok 或 annotationProcessorPaths，只有在顶层看不出问题。建议检查每个模块 pom.xml 或 build.gradle。

2. CI（持续集成）环境：有时本地 IDE 编译通过，但 CI 报错，常见原因是 CI 的 JDK 版本或编译器插件配置不同。建议在 CI 中也声明 maven-compiler-plugin 的 annotationProcessorPaths，保证构建一致性。

3. module-info.java：如果项目使用 Java 模块化（module-info），需要注意反射访问问题，某些 Lombok 功能或生成的代码在模块访问限制下可能需在 module-info 中添加 opens。

4. IDEA vs 命令行：有时 IDEA 能通过（因为 plugin 做了处理），而 mvn package 失败，或者反过来。要同时保证 IDE 和命令行构建都通过，建议：

   • 在 pom/gradle 中显式配置 annotation processor（如上示例）。
   • 在 IDEA 中打开注解处理器。

5. JDK 版本兼容性：Lombok 团队会尽快跟进新 JDK，但如果你用的是非常新的 JDK（比如刚出的 major release），先查看 Lombok 的 release notes，必要时升级 Lombok。

6. 框架集成：Spring Boot 等框架通常对 Lombok 友好，但若使用 AOT、native-image（GraalVM）等高级功能时，需要额外注意 Lombok 生成的代码是否兼容。

常见问题排查清单

按下面顺序逐项检查，99% 的 Lombok 不生效问题能被解决：

1. IDEA 是否安装 Lombok 插件并已重启？
2. IDEA 注解处理器是否启用？（Settings -> Compiler -> Annotation Processors）
3. pom.xml / build.gradle 是否引入 Lombok？（Maven: dependency + annotationProcessorPaths；Gradle: compileOnly + annotationProcessor）
4. 是否使用了 module-info.java？需要额外 opens/exports？
5. Lombok 版本是否与 JDK 兼容？尝试升级 Lombok 版本。
6. 清理并重建：mvn clean package 或 ./gradlew clean build，IDEA 执行 Invalidate Caches & Restart。
7. CI 报错：检查 CI JDK 版本、maven-compiler-plugin 配置是否与本地一致。
8. 若仍旧异常，使用 Lombok 的 delombok（将 Lombok 注解展开为真实源代码）来调试：mvn lombok:delombok 或在 IDE 的 Lombok 插件里使用 delombok 功能，看看实际生成的代码是什么样子。

delombok 与源码查看

delombok 可以把注解展开生成真实 Java 源代码，便于查看实际生成结果。

如果你用 Maven，可以把 lombok-maven-plugin 加入来 delombok：

<plugin><groupId>org.projectlombok</groupId><artifactId>lombok-maven-plugin</artifactId><version>1.18.32.0</version><executions><execution><phase>generate-sources</phase><goals><goal>delombok</goal></goals></execution></executions>
</plugin>

执行后在 target/delombok 下会看到展开后的 Java 文件。

总结

如果你要在专访或团队内讲，推荐这样一句总结口语化表达：

“Lombok 出问题十有八九是配置问题，不是 Lombok 坏了。先装插件、开注解处理器、确认构建工具里把 annotation processor 配置好，再重建。实务中我常用 delombok 看生成代码，CI 里也会强制声明 maven-compiler-plugin 的 annotationProcessorPaths，保证本地和 CI 的一致性。”