代码生成器这东西，一旦用顺手就回不去了。建表、写字段注释、点一下按钮，实体类、数据访问层、服务接口、控制器全套吐出来，比自己手敲省下大半天。但工具链一多，环境一换，坑就跟着冒头。前阵子有位同行在群里发了张截图，满屏红色堆栈，最底下那行赫然是java.lang.ClassNotFoundException: freemarker.template.Configuration，配文三个字——“跑不动”。他刚把公司里那套老生成器搬到新工程里，IDE 里能点出模板文件，命令行一执行就翻车。这类问题看着像“少个 jar”，实际上背后可能是依赖没写、作用域写错、父工程只锁版本不引依赖、打包插件把包瘦身掉、IDE 缓存没同步、甚至类加载器隔离搞的鬼。
这篇东西只聊三件事：这个异常在讲什么、不同工程形态下它的每一种真实成因长什么样、以及从五分钟定位到彻底解决的完整路径。适合刚接手代码生成模块的初中级后端、正在维护老脚手架的老手，也适合那些在持续集成流水线上被“本地能跑、打包就炸”折磨过的同学。我不会只给你一句“加个依赖”，因为这句话大多数人在搜索引擎里已经看到过十遍了，照着加了还是报错——那说明问题压根不在“加没加”上。
1. 把这个异常拆开看，别急着粘贴依赖
1.1 ClassNotFoundException 到底在说什么
java.lang.ClassNotFoundException的字面意思非常直白：某个类加载器试图按全限定名加载一个类，翻遍自己负责的路径也没找到对应的字节码。注意这里的关键词是“某个类加载器”——它不是全局判定的“JVM 里没有这个类”，而是“当前这个加载器看不着”。这个区别非常要命，后面讲插件化、热部署场景时全靠它。异常信息里给出的全限定名freemarker.template.Configuration就是加载目标，它对应的是模板引擎的核心配置类，属于那个模板引擎的对外入口。
顺带把一个常被混淆的点说清楚：ClassNotFoundException和NoClassDefFoundError不是一回事。前者通常发生在首次主动加载的时候，比如反射、Class.forName、或者字节码里第一次出现对该类的引用；后者往往表示“这个类之前加载过，现在加载不出来了”，常见于静态初始化块抛异常、或者它依赖的另一个类先缺失了。排查时最有价值的动作不是盯着异常类型，而是把堆栈翻到最底下那几层Caused by，那里才是真正的案发现场。很多时候第一行写的是某个框架的TemplateEngineException，中间套了两层IllegalStateException，最底下才是 ClassNotFound。
1.2 代码生成器为什么绕不开模板引擎
代码生成器本质上是一个“结构化数据 + 文本模板 → 源代码文件”的转换器。表结构元数据是输入，一堆.ftl、.vm、.btl结尾的模板文件是模具，输出就是一个个.java文件。模板引擎负责把数据模型和模板里的占位符渲染到一起。这套设计的好处很明显：新增一种输出格式，比如 MyBatis 的 XML 映射文件，不需要改一行 Java 代码，丢一个模板进去就行；字段命名规则变更，也只改模板。
正因为模板引擎是“外挂”而不是“内核”，它在依赖关系里始终处于一个略显尴尬的位置——对主体业务来说它是可选的，对生成器来说它是必需的。这种“半必需”属性导致了大量工程在依赖声明上做取舍：业务模块为了减小发布包体积把它设成provided，生成器模块因为是“开发期工具”干脆只写在测试作用域，脚手架模板为了通用性把它设成optional。每一条这样的取舍，都可能在某次环境迁移后变成一行 ClassNotFound。
1.3 为什么偏偏是 Configuration 这个类
有人会问，模板引擎里类那么多，为什么报错总是锁死在这个类？因为Configuration是整个模板引擎的配置中心，也是几乎所有生成器代码第一个触碰的类。你写生成器的第一行有效代码大概率是new Configuration(...)，后面所有设置编码、设置模板加载目录、获取模板对象的方法，全都挂在这个实例上。它一旦加载失败，整个链路在第一环就断了，后面的类根本没机会出场。
还有一个隐蔽的原因：这个类的包路径在 2.3.x 这一整个大版本线里是稳定的，但跨大版本会变。如果你不小心引入了某个预览版、变体包、或者被裁剪过的“精简版”模板引擎，类的全名就对不上，JVM 一样会告诉你“找不到”。所以排查时不要默认“我引了模板引擎 = 类一定在”，坐标对、包名对、版本对，三个条件缺一不可。
2. 从依赖视角找根因，比换 JDK 靠谱
2.1 dependencyManagement 只锁版本，它不引依赖
这是我在实际项目里见过频率最高的一种翻车方式，尤其在多模块工程里。父工程的pom.xml里写了一段：
<dependencyManagement> <dependencies> <dependency> <groupId>org.freemarker</groupId> <artifactId>freemarker</artifactId> <version>2.3.32</version> </dependency> </dependencies> </dependencyManagement>写完之后感觉“万事俱备”，子模块里直接调new Configuration(...)，IDE 里还真的没报红——因为父工程所在的工作空间里其他模块引了这个依赖，IDE 的索引把类解析到了，但子模块自己的dependencies里根本没有这个坐标。dependencyManagement的语义是**“如果你引了，就用这个版本”**，它是版本仲裁表，不是引入声明。子模块必须老老实实再写一遍不带<version>的依赖块。
更迷惑的地方在于：IDE 的代码补全和跳转会让人产生“类存在”的错觉，而实际的编译期和运行期类路径完全不同。判断方法很简单，打开子模块的target/classes和它的target下的依赖清单，或者直接在子模块目录下执行依赖树命令，看这个坐标是否出现在结果里。只要不在，加依赖就完事了，别浪费时间怀疑人生。
2.2 scope、optional、exclusion 三重门
依赖引了还是找不到，大概率是撞上了这三道门之一。作用域scope决定依赖在哪些阶段进入类路径：compile全阶段可见；provided编译和测试可见，运行时不带上；runtime编译不可见但运行可见；test只在测试阶段可见；system走本地路径，极其不推荐。生成器模块如果被打包成独立可执行的 jar 分发出去，而依赖写成了provided，那在目标机器上必然报 ClassNotFound，因为打包工具老老实实按规则把它排除了。
optional是第二道门，它只影响传递性。A 依赖了模板引擎并标记optional，B 依赖 A 时不会自动获得模板引擎。这在框架类库、脚手架内核里非常常见——作者认为“用不用模板引擎是你的自由”，于是把它设成可选。结果就是你自己的工程里明明间接依赖了那个框架，却怎么都拿不到引擎的类。
exclusion是第三道门，也是最难查的一道。某个中间依赖为了“避免版本冲突”，把模板引擎排掉了；或者你自己在某次排除日志框架冲突时，手滑用通配符把兄弟依赖一起排了。这两类排除不会报任何警告，依赖树里对应分支直接断掉，只有在运行到那一行代码时才炸出来。所以看到 ClassNotFound，第一件要做的事是完整看一遍依赖树，而不是瞄一眼 pom 里有没有那行字。
2.3 用依赖树命令把目标揪出来
Maven 工程下，最直接的诊断手段是依赖树加坐标过滤：
# 只看模板引擎这一支，输出最快 mvn -q dependency:tree -Dincludes=org.freemarker:freemarker # 看完整树，并把被冲突仲裁掉的依赖也显示出来 mvn dependency:tree -Dverbose > dep-tree.txt # 直接列出最终生效的依赖清单（比树更干净） mvn -q dependency:list -DincludeGroupIds=org.freemarker-Dverbose这个参数值得单独强调。它会用(omitted for conflict with x.y.z)这样的备注告诉你：某个版本的模板引擎在依赖树里出现过，但被另一个版本仲裁掉了。如果你看到这行备注，说明模板引擎其实被引了，只是版本被换成了另一个——这时候问题可能不是“没有类”，而是“换成的那个版本里这个类路径不一样”，处理思路完全不同。
还有一条命令强烈推荐加进日常排查清单：
mvn dependency:analyze它会输出 “Used undeclared dependencies found”，意思是代码里用到了但 pom 里没显式声明的依赖。这几乎就是为本文这个场景量身定做的检测器。它会明确告诉你某个坐标在运行时被用到但没声明，那么把它补进dependencies就完事了。这种“靠着别的依赖顺带引入”的隐性依赖，正是环境一换就崩的常见诱因。
2.4 Gradle 与多模块工程的等价操作
Gradle 的排查思路一致，只是命令换了：
# 查看运行时类路径的依赖树 ./gradlew dependencies --configuration runtimeClasspath # 依赖洞察报告，能把冲突和版本仲裁讲得非常清楚 ./gradlew dependencyInsight --dependency freemarker --configuration runtimeClasspathdependencyInsight是我在 Gradle 项目里最喜欢的一条命令，它会明确列出“为什么这个依赖被选中、哪些路径把它带进来、哪些路径被它顶掉”。多模块 Gradle 工程里，还可以在根目录跑./gradlew :generator:dependencies只查目标模块，避免几十个模块的树刷屏。
多模块场景还有一个容易被忽略的细节：依赖是跟着模块走的，不是跟着工程走的。根build.gradle里写了subprojects { implementation '...' }，看起来所有模块都有，但如果某个子模块自己覆盖了configurations，或者用了compileOnly重新声明，实际效果就未必了。遇到这种问题，别信“我在根配置里写了”，只信命令输出的结果。
3. 六类真实场景，对症下药才有效
3.1 场景一：依赖根本没引，最朴素也最常见
新建的生成器模块，或者从别处拷过来的半成品工程，最典型的状态就是“代码有、依赖没配”。这类情况的特征是：IDE 的编辑器里import那一行飘红，但在某些版本里因为工作空间索引的存在，红色被掩盖了，或者被自动导入的候选列表糊弄过去了。第一次编译就报错，连运行的机会都没有。
解决方式就是加上依赖，注意新老坐标的区别。较新的版本使用org.freemarker作为 groupId，早期的老版本用的是freemarker，两个坐标指向的构件不同，混用会导致依赖树里出现两个同名不同组的家伙。这里给一份标准写法，直接抄：
<dependency> <groupId>org.freemarker</groupId> <artifactId>freemarker</artifactId> <version>2.3.32</version> </dependency>Gradle 项目等价写法：
implementation 'org.freemarker:freemarker:2.3.32'如果你所在的工程已经通过父工程统一管理版本，那就省掉<version>，只保留前两行。但请务必确认父工程里管理的是org.freemarker这个坐标，而不是老的freemarker坐标——这一步没对齐，等于白写。
3.2 场景二：IDE 里好好的，打包后一跑就炸
这个场景我印象极深。本地跑生成器一切正常，打包成可执行 jar 丢到另一台机器上，java -jar一执行立刻一串红字。原因通常有两个：一是依赖被声明成了provided，打包插件按规则不把它放进最终产物；二是打包方式用的是“瘦包 + 外部依赖目录”，但启动脚本没有正确指定类路径。
第一类问题，先确认 pom 里作用域是不是写成了provided或test。生成器如果作为独立工具分发，作用域必须是compile或runtime。第二类问题，验证方式非常直接：
# 看看最终产物里到底有没有模板引擎的类 jar tf target/generator-app.jar | grep "freemarker/template/Configuration.class" # 或者统计一下模板引擎的条目数量 jar tf target/generator-app.jar | grep -c "^freemarker/"只要输出为空，就说明类压根没进包，压根不用往下查。如果是用“瘦包 + lib 目录”的方案，就去lib目录里数一数 jar 数量对不对，再检查启动脚本里的-cp参数有没有覆盖整个目录。这里有个经典细节：Linux 下的类路径分隔符是冒号，脚本里要写成-cp "app.jar:lib/*"；如果脚本是从 Windows 环境拷过来的，用了分号，冒号分号搞混一个字，整个依赖目录就形同虚设。
3.3 场景三：依赖树里有，运行时还是找不到
这一种最消耗耐心。依赖树明明列出了模板引擎的坐标，版本也正常，运行时依旧抛 ClassNotFound。可能的原因有三层。第一层是依赖树查询的配置和实际运行的配置不是同一个，比如你查的是compile类路径，实际运行用的是runtimeClasspath，或者反过来。第二层是本地仓库里的 jar 损坏，下载中断留下了.lastUpdated文件，jar 文件本身是 0 字节或者半截。第三层是同一个构件在工程里出现了两次，通过不同路径引入了不同版本，运行时加载到了错误的那个。
第一层的应对是把查询命令限定到和运行一致的范围。第二层的处理很粗暴但有效：去本地仓库找到对应目录，把.lastUpdated和疑似残损的 jar 删掉，然后加-U参数强制重新拉取。第三层则需要靠-Dverbose的仲裁提示来判断，必要时用dependencyManagement显式锁定一个版本，把所有旁支统一掉。
还有一种很隐蔽的情况：工程里同时存在freemarker和某个“同包不同名”的变体构件，两个都提供freemarker.template包下的类，但内容和版本不一致。这种情况下import能解析、编译能过、运行时报错，排查成本极高。判断方法是在本地仓库里把相关目录都列一遍，看是否存在多个 groupId 下的类似构件，如果有，坚决只留一个。
3.4 场景四：模板引擎被“瘦身”，或者坐标被换掉
有些团队为了压缩发布包体积，会对依赖做裁剪，用自研的精简版替换掉完整版模板引擎的内部实现。这类裁剪包往往只保留渲染必需的部分，把配置类的构造方法、静态常量、异常处理器等等周边能力砍掉。结果是：你以为引的是原版，运行时加载到的却是残废版。
判断这个问题的关键在于打印类的来源。写一个几行的探针程序，把类从哪个 jar 里加载出来这件事问清楚：
public class ClassOriginProbe { public static void main(String[] args) { String target = "freemarker.template.Configuration"; ClassLoader cl = Thread.currentThread().getContextClassLoader(); while (cl != null) { try { Class<?> clazz = cl.loadClass(target); System.out.println("命中: " + clazz.getName()); System.out.println("来源: " + clazz.getProtectionDomain() .getCodeSource().getLocation()); return; } catch (ClassNotFoundException e) { System.out.println("未命中: " + cl); } cl = cl.getParent(); } System.out.println("整条加载器链都没有找到 " + target); } }这段代码的价值在于：它不仅回答“有没有”，还回答“从哪来”和“被谁加载”。输出里如果出现了一个你完全不认识的自研 jar 路径，答案就呼之欲出了——去查那个 jar 是谁带进来的，然后把它排除掉，换成官方坐标。如果整条链都没命中，那就回到第 2 章的依赖树排查流程。
3.5 场景五：类加载器隔离与线程上下文
当生成器不是一个独立应用，而是嵌在某个平台里作为一个功能模块运行的时候，类加载器问题就会出现。平台为了保证插件之间互不污染，往往为每个插件创建独立的加载器，父加载器指向平台主加载器。这种结构下，判断“类在不在”的答案取决于你从哪个加载器的视角去看。平台主加载器里明明有模板引擎，但插件加载器如果破坏了双亲委派，或者反过来不接受父加载器的类，就表现为找不到。
理论讲再多不如一个动作：在真正抛异常的那个方法附近，把线程上下文类加载器和当前类的加载器都打出来，对比一下：
ClassLoader ctx = Thread.currentThread().getContextClassLoader(); ClassLoader cur = MyGenerator.class.getClassLoader(); System.out.println("context = " + ctx); System.out.println("current = " + cur);如果两者不是同一个对象，说明上下文加载器被换过，这是很常见的“框架为了加载业务类而临时切换上下文”的做法。此时在关键代码前后手动设置和还原上下文加载器，往往能直接解决问题：
ClassLoader origin = Thread.currentThread().getContextClassLoader(); try { Thread.currentThread().setContextClassLoader(MyGenerator.class.getClassLoader()); // 在这里执行模板加载与渲染 } finally { Thread.currentThread().setContextClassLoader(origin); }一定要用try-finally还原，别图省事只设不还。线程池复用的场景下，不还原上下文加载器会污染后续任务，排查起来比原问题还难。
3.6 场景六：本地仓库损坏与离线构建
这一条单独拎出来说，是因为它极其容易被忽略。表现是：pom 写得完全正确，依赖树能查出来，jar 目录也在，但运行就是报错，而且时好时坏，换一台机器就正常。原因可能是本地仓库里那个 jar 在半途下载中断之后被标记成了“已处理”，后续构建再也不去重新拉取。或者团队配置了内网镜像，镜像里同步的是不完整版本。
标准处理动作：
# 强制刷新快照与依赖，绕过本地缓存标记 mvn -U clean install # 精准清理单个构件的本地缓存目录后重试 rm -rf ~/.m2/repository/org/freemarker/freemarker离线构建场景还要额外注意：如果构建机禁止联网，而本地仓库里恰好缺这个构件，Maven 会在日志里给出“offline mode”相关的警告并跳过，某些配置下甚至只是把依赖标记为缺失然后继续构建，最后在运行期才发现。看到构建日志里出现与依赖下载相关的 WARN，一定要当成错误对待，别让它在海量日志里溜过去。
4. 一套可以直接抄的生成器工程配置
4.1 最小可用依赖清单
把生成器做成一个独立模块的时候，我习惯把依赖分成三层：模板引擎本体、生成器框架内核、以及可选的日志桥接。最小可运行的组合大概是这样：
<dependencies> <!-- 模板引擎本体，必须有 --> <dependency> <groupId>org.freemarker</groupId> <artifactId>freemarker</artifactId> <version>2.3.32</version> </dependency> <!-- 生成器内核，如果用的是第三方实现，版本要与模板引擎匹配 --> <dependency> <groupId>com.example.codegen</groupId> <artifactId>codegen-core</artifactId> <version>1.4.0</version> <!-- 内核若把模板引擎设为 optional，这里必须显式再引一次 --> </dependency> </dependencies>注意第三行那个注释，是整段配置里最有信息量的一句话。很多生成器内核的实现都选择把模板引擎设为optional，理由是“用户可能有自己的模板方案”。如果你的工程只引了内核没引引擎，编译能过、运行必炸，而且异常信息就是本文开头那一行。所以判断标准很简单：只要你的代码里有任何一行直接 new 或 import 了这个配置类，就必须显式声明引擎依赖，不能指望内核帮你带进来。
4.2 版本对齐与冲突处理
模板引擎的版本不是随便挑一个就行。生成器内核、脚手架框架内部往往已经绑定了某个版本，你强行指定一个差距较大的版本，可能出现方法签名不兼容、常量被移除之类的问题。我的做法是先跟着“上游”走，跑通了再考虑升级。版本对齐下面这张表可以当参考，实际以你所用内核的官方说明为准：
| 关注点 | 常见做法 | 判断依据 |
|---|---|---|
| 坐标选择 | 使用org.freemarker组 | 老坐标只存在于很早期的版本 |
| 版本来源 | 优先跟随内核的传递版本 | 减少不兼容风险 |
| 显式锁版本 | 用dependencyManagement统一 | 多模块下避免版本漂移 |
| 冲突仲裁 | 看-Dverbose的 omitted 提示 | 有提示说明被顶掉过 |
| 作用域 | 分发型工具用compile | provided会导致运行时缺失 |
真正动手时，最容易犯的错误是“顺手升级到最新版”。模板引擎这类文本渲染工具，大版本内部的小版本升级通常安全，但跨大版本升级的改动面会非常大，配置项的默认值、异常体系、缓存策略都可能变。生成器代码本身不复杂，往往体会不到破坏性，可一旦出了问题，堆栈会指向模板内部，排查难度陡增。
4.3 把模板引擎做成可替换的抽象层
如果这个生成器是要长期维护、甚至要给多个团队用，我建议在引擎外面包一层薄薄的接口。理由很实际：模板引擎的依赖问题、版本问题、类加载问题，只要有替换方案，永远都有退路。接口可以简单到只有三个方法：
public interface TemplateRenderer { void init(String templateDir, String encoding); String render(String templateName, Map<String, Object> model); void refresh(); }实现类内部封装那个配置对象的创建、目录设置、编码设置和渲染异常转换。上层生成器代码只依赖这个接口，不依赖任何具体引擎的类。这么做的直接收益是：引擎的类找不到时，你会在自己的实现类的加载阶段就看到清晰的错误，而不是在某个深度嵌套的框架调用栈底部；次要收益是，将来想换引擎或者加缓存，改动面被限制在一个文件里。
这层抽象还顺带解决了一个常见困扰：模板目录的定位。抽象层里可以统一处理“从类路径加载”和“从文件系统加载”两种模式，前者适合打成 jar 分发，后者适合本地开发时改模板即时生效。这个区分如果散落在业务代码里，早晚会有人在打包后忘记把模板放进资源目录，然后在生产环境收获一个找不到模板的异常。
5. 排查 SOP 与踩坑实录
5.1 五分钟定位流程
异常出现时，别急着搜索。按下面这个顺序走一遍，绝大多数情况能在五分钟内锁定方向：
- 看堆栈最底层。翻到最后一个
Caused by，确认是不是真的就是类缺失，而不是被包装过的其他异常。 - 跑一次依赖树过滤。
mvn -q dependency:tree -Dincludes=org.freemarker:freemarker，没有输出就是没引，有输出就记下版本。 - 检查作用域。依赖树的每一行末尾都标着
:compile、:provided之类，不在compile/runtime的直接改配置。 - 检查最终产物。
jar tf数一下类在不在包里，这一步能立刻区分“构建期问题”和“运行期问题”。 - 打印类来源。用前面那个探针程序，看看到底从哪个 jar 加载，或者压根没加载到。
- 清理重建。
mvn -U clean install走一遍，排除缓存污染。
这套流程的设计逻辑是从“成本最低、信息量最大”的动作开始。第一步几乎零成本，却能排除掉一半的误判；第二步和第三步合起来能覆盖掉大部分配置类问题；第四步往后才是真正的疑难杂症。反过来的顺序，也就是先清缓存再重装依赖再换 JDK，看着很勤奋，实际是在用时间换运气。
5.2 常见报错对照速查表
实际排查中会撞见几种相似但不同的报错，混淆了就会走错方向。下面这张表是我这些年攒下来的对照：
| 报错形态 | 更可能的根因 | 优先动作 |
|---|---|---|
ClassNotFoundException: freemarker.template.Configuration | 依赖缺失、作用域错误、被排除 | 依赖树过滤 |
NoClassDefFoundError: freemarker/template/Configuration | 类曾加载失败、静态初始化异常 | 看根因异常 |
| 编译期飘红但能跑 | IDE 索引与真实类路径不一致 | 刷新工程、重新导入 |
| 本地正常、打包失败 | provided作用域、瘦包未带依赖 | 检查产物内容 |
| 报错信息里出现陌生 jar 路径 | 自研裁剪包或变体构件顶替 | 打印类来源 |
| 偶发、重启后消失 | 本地仓库残损、加载器隔离 | 强制刷新、打印加载器 |
| 模板渲染时数字带逗号 | 数字格式化设置未指定 | 设computer格式 |
表格里最后一行其实不是 ClassNotFound 的范畴，但它是我见过最容易被误判成“环境问题”的一类。生成 Java 代码时，某个Long类型的默认值 1234 被渲染成1,234，生成的源码直接编译不过，而报错信息指向的是生成出来的文件，跟模板引擎一点关系都没有。看到生成结果里有莫名其妙的逗号、日期格式不对、中文乱码，先怀疑格式化设置，别怀疑依赖。
5.3 三个隐形坑，解决报错之后才轮到它们
第一个坑是数字与日期格式化。模板引擎默认会按运行环境的区域设置格式化数字，中文环境下1000000会变成1,000,000。生成配置文件、生成 Java 常量、生成 SQL 的时候，这个逗号是致命的。解决方式是在配置对象初始化时统一指定：
Configuration cfg = new Configuration(Configuration.VERSION_2_3_32); cfg.setDefaultEncoding("UTF-8"); cfg.setNumberFormat("computer"); // 关键：禁用千分位 cfg.setTemplateExceptionHandler( TemplateExceptionHandler.RETHROW_HANDLER); // 关键：模板写错要炸，不要静默 cfg.setLogTemplateExceptions(false);第二行那个computer是引擎内置的格式名，意思是“按计算机可读的方式输出”，效果就是不加千分位、不按区域设置转换。第四行更关键，默认的异常处理器会把模板里的错误吞掉，渲染出一个空字符串，结果你得到一堆字段全是空的实体类，还以为是数据模型传错了。设成直接抛出之后，模板里写错字段名会立刻报错，定位成本从半小时降到十秒。
第二个坑是模板缓存导致改模板不生效。配置对象一旦加载过模板就会缓存，本地开发时改了.ftl文件，重新跑生成器发现输出没变，很容易怀疑人生。开发期把缓存延迟调成 0 即可：
cfg.setTemplateUpdateDelayMilliseconds(0);生产环境别这么写，缓存是有价值的，模板解析本身有开销。这也是为什么我建议把“开发模式”和“发布模式”的配置分开，用一个开关控制，别图省事一套配置打天下。
第三个坑是相对路径的工作目录依赖。模板目录写成new File("src/main/resources/templates")，在 IDE 里运行没问题，因为工作目录是模块根；用命令行执行时工作目录变了，立刻找不到模板。这种问题不会抛 ClassNotFound，但会抛模板不存在的异常，症状相似，容易被混为一谈。稳妥做法是优先从类路径加载模板，把模板放进资源目录，打包时一并带上；确实需要外部可编辑模板的场景，就用配置项或环境变量指定绝对路径，别依赖相对路径。
5.4 关于版本选择的一点个人看法
我见过不少团队在这个问题上走两个极端。一种是“能跑就别动”，工程里的模板引擎版本停在好几年前，结果遇到安全扫描告警、遇到 JDK 升级不兼容，改起来牵连一大片。另一种是“永远用最新”，每次升级都顺手把所有依赖拉到最新，然后花两天时间处理各种意料之外的兼容问题。
我自己的做法是：跟随上游主框架的版本，不主动超前，但也不放任落后。具体操作是看生成器内核或脚手架框架的依赖声明里用的是哪个版本，直接用那个版本，通过dependencyManagement锁定，让所有模块统一。这样既避免了版本漂移，又不会因为跨大版本升级踩到未知的坑。只有在明确知道某个版本有必须修复的问题时，才单独升级并做完整回归。
另一个实操层面的建议是，把生成器模块和业务模块的依赖管理分开。业务模块的思路是“尽量少、尽量稳”，生成器模块的思路是“工具齐全、随用随加”。这两类模块塞在同一个 pom 里，早晚会因为作用域和体积的取舍打架，最典型的结果就是本文开头那个异常。分成独立模块，各自维护自己的依赖，问题会少很多。
最后分享一个我在实际使用中的习惯：每次接手一个陌生的生成器工程，第一件事不是读代码，而是在它的目录下跑一次依赖树和依赖分析，把模板引擎的位置和作用域先确认清楚。这个动作花不到一分钟，但能省掉后面大量的“为什么本地能跑发布就炸”。依赖这东西，看懂了就没什么神秘的，看不懂的时候，它比任何业务逻辑都难缠。
