java -jar 不支持从主 JAR 内部直接加载其他 JAR（即“JAR-in-JAR”），Class-Path 清单属性仅解析同级目录下的外部 JAR，因此将 snakeyaml-1.28.jar 直接放入主 JAR 包内无效。
`java -jar` 不支持从主 jar 内部直接加载其他 jar（即“jar-in-jar”），`class-path` 清单属性仅解析同级目录下的外部 jar，因此将 `snakeyaml-1.28.jar` 直接放入主 jar 包内无效。
在 Java 标准运行机制中，java -jar 命令会严格遵循 JAR 规范：它仅读取 META-INF/MANIFEST.MF 中 Class-Path 指定的路径，并将这些路径视为相对于主 JAR 所在目录的文件系统路径，而非 JAR 内部路径。这意味着即使你把 snakeyaml-1.28.jar 放进 compare-yaml.jar 的根目录下，JVM 也不会从中解压或扫描该嵌套 JAR —— 它根本不会被识别为有效类路径条目。
✅ 正确做法一：使用 Shadow JAR（推荐）
Gradle 用户可借助 shadow 插件一键打包所有依赖到单个可执行 JAR 中：
// build.gradle
plugins {
id 'com.github.johnrengelman.shadow' version '8.1.1' apply true'
id 'java'
}
shadowJar {
archiveBaseName.set('compare-yaml')
archiveClassifier.set('')
archiveVersion.set('')
mergeServiceFiles() // 合并 META-INF/services（对 SnakeYAML 等 SPI 组件至关重要）
}执行 ./gradlew shadowJar 后，生成的 build/libs/compare-yaml-all.jar 将包含 YamlParser.class 和全部 snakeyaml 字节码（已解压合并），此时可直接运行：
java -jar build/libs/compare-yaml-all.jar a.yaml b.yaml
? Maven 用户可使用 maven-shade-plugin 实现同等效果，配置中务必启用 ServicesResourceTransformer 以正确合并 YAML 解析器所需的 META-INF/services/... 文件。
java-api-doc-generator下载分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
✅ 正确做法二：显式指定外部依赖路径
若需保留原始结构，可将依赖 JAR 放在主 JAR 同级目录，并改用 -cp（或 -classpath）启动：
# 目录结构： # ├── compare-yaml.jar # └── snakeyaml-1.28.jar java -cp "compare-yaml.jar:snakeyaml-1.28.jar" YamlParser a.yaml b.yaml
⚠️ 注意：Windows 下分隔符应为 ;（如 compare-yaml.jar;snakeyaml-1.28.jar），且此时 必须显式指定主类名 YamlParser，不能再用 -jar。
❌ 错误认知澄清
- Class-Path: snakeyaml-1.28.jar 在 MANIFEST.MF 中 不表示“从当前 JAR 内加载”，而是“从当前 JAR 所在目录加载同名文件”；
- Java 运行时 原生不支持 JAR-in-JAR，任何试图通过修改 ClassLoader 或自定义 URLClassLoader 在 main() 中手动加载嵌套 JAR 的方式，均无法解决 NoClassDefFoundError —— 因为类加载发生在 main 执行前，由启动类加载器（Bootstrap/App ClassLoader）完成，而它们不识别 ZIP 内的 ZIP。
总结
| 方案 | 是否需修改构建流程 | 是否单文件部署 | 是否兼容标准 JVM |
|---|---|---|---|
| Shadow JAR（All-in-One） | ✅ 是（推荐 Gradle/Maven 插件） | ✅ 是 | ✅ 是 |
| 外部依赖 + -cp 启动 | ❌ 否（仅调整部署结构） | ❌ 否（需多个文件） | ✅ 是 |
| 嵌套 JAR + Class-Path | ❌ 无效（JVM 不支持） | — | ❌ 不生效 |
选择 Shadow JAR 是最健壮、可维护性最强的方案，尤其适用于命令行工具类项目。它消除了部署时的路径依赖，也规避了因 JDK 版本差异导致的类加载行为不确定性。
