什么是 Classpath？
Classpath（类路径）是 Java 虚拟机 用来查找类（.class 文件）和资源（如配置文件、图片等）的路径列表，当你的 Java 代码中引用了一个类（import com.example.MyClass;），JVM 就会在 Classpath 中指定的所有目录和 JAR 文件里去寻找 com/example/MyClass.class 这个文件。
Classpath 告诉 JVM：“去哪里找我需要的类文件”。
Classpath 的配置方式
Classpath 的配置方式主要有三种,按推荐程度和现代使用频率排序：
module-path(模块路径) - Java 9+ 引入,用于模块化系统。classpath(类路径) - 传统方式,至今仍然广泛使用。-Djava.class.path系统属性 - 最底层的方式,不推荐日常使用。
下面我们详细讲解这几种方式,特别是最常用的命令行方式和构建工具方式。
命令行方式
这是最基础也是最直接的方式，通过 java 命令的参数来指定 Classpath。
a) -cp 或 -classpath 参数
这是指定 Classpath 最标准的方法。
语法：
java -cp <路径1>;<路径2>;... <主类名>
或者
java -classpath <路径1>:<路径2>:... <主类名>
注意：
- Windows 系统使用分号 来分隔路径。
- Linux / macOS 系统使用冒号 来分隔路径。
路径可以是：
- 目录: JVM 会递归查找该目录下的所有
.class文件。 - JAR/ZIP 文件: JVM 会直接在该归档文件中查找类。
实战示例
假设我们有以下项目结构：
my-project/
├── src/
│ └── com/
│ └── example/
│ └── Main.java
├── lib/
│ └── gson-2.10.1.jar (一个第三方库)
└── out/
└── production/
└── classes/
└── com/
└── example/
└── Main.class (编译后的文件)步骤 1：编译代码
我们需要把 src 目录下的 .java 文件编译到 out/production/classes 目录中。
# -d 指定编译后的 .class 文件输出目录 javac -d out/production/classes src/com/example/Main.java
步骤 2：运行程序
现在我们需要运行 Main.class，它依赖于 gson.jar，Classpath 必须包含：
- 包含我们编译好的类的目录：
out/production/classes - 包含依赖库的 JAR 文件：
lib/gson-2.10.1.jar
在 Windows 上：
java -cp "out/production/classes;lib/gson-2.10.1.jar" com.example.Main
注意：路径中如果包含空格，需要用双引号 括起来。
在 Linux / macOS 上：
java -cp "out/production/classes:lib/gson-2.10.1.jar" com.example.Main
b) 使用通配符
为了避免手动列出所有 JAR 文件，可以使用通配符 来匹配目录中的所有 JAR 文件。
语法：
java -cp "<目录路径>/*" <主类名>
示例： 继续上面的项目结构,我们可以这样运行：
# Windows java -cp "out/production/classes;lib/*" com.example.Main # Linux / macOS java -cp "out/production/classes:lib/*" com.example.Main
JVM 会自动将 lib 目录下的所有 .jar 文件（如 gson-2.10.1.jar, another-lib.jar）都添加到 Classpath 中。
构建工具方式 (强烈推荐)
在真实的项目开发中，手动管理 Classpath 是非常繁琐且容易出错的，我们几乎从不直接使用命令行的 -cp 参数，而是使用构建工具来自动管理依赖和 Classpath。
a) Maven
Maven 使用 pom.xml 文件来管理项目结构和依赖。
pom.xml 示例：
<project ...>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>my-app</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- 声明一个依赖 -->
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>
</dependencies>
</project>
如何运行？
你只需要在项目根目录下执行 Maven 的 exec:java 插件（需要先配置）或者更常见的 package 命令。
-
编译和打包：
mvn clean package
这个命令会：
clean: 删除之前的target目录。compile: 编译src/main/java下的代码。package: 打包成一个可执行的 JAR 文件（默认在target/目录下，如my-app-1.0-SNAPSHOT.jar）。
-
运行打包好的 JAR： Maven 会自动将所有依赖（包括
gson.jar）打包到最终的 JAR 中，并生成一个包含正确 Classpath 的 MANIFEST.MF 文件。java -jar target/my-app-1.0-SNAPSHOT.jar
b) Gradle
Gradle 使用 build.gradle (或 build.gradle.kts) 文件来管理项目。
build.gradle 示例：
plugins {
id 'java'
id 'application' // 应用插件，方便运行
}
group 'com.example'
version '1.0-SNAPSHOT'
repositories {
mavenCentral() // 使用中央仓库
}
dependencies {
// 声明一个依赖
implementation 'com.google.code.gson:gson:2.10.1'
}
// 指定主类，让 'run' 任务能直接执行
application {
mainClass = 'com.example.Main'
}
如何运行？
-
编译和打包：
gradle build
这个命令会编译代码、运行测试并打包，打包后的文件也在
build/libs/目录下。 -
直接运行（无需打包）： Gradle 的
run任务非常方便，它会自动设置好 Classpath 并运行主类。gradle run
-
运行打包好的 JAR：
java -jar build/libs/my-app-1.0-SNAPSHOT.jar
系统属性方式 (不推荐)
可以通过启动 JVM 时设置系统属性 java.class.path 来指定 Classpath。
java -Djava.class.path="out/production/classes;lib/*" com.example.Main
这种方式与 -cp 参数效果相同，但 -cp 是专门为此设计的，可读性更好,因此更常用。
模块路径 (Java 9+)
从 Java 9 开始，引入了模块系统，Classpath 概念被分为了两种：
- 模块路径 (
--module-path): 用于存放模块化的 JAR 文件（带有module-info.class的 JAR）,模块之间有明确的依赖关系。 - 类路径 (
-classpath或--class-path): 用于存放传统的、非模块化的 JAR 文件和目录。
混合使用示例： 假设你的项目是模块化的，但需要依赖一个传统的 JAR 库。
java --module-path mods -cp "lib/*" com.example.Main
--module-path mods: JVM 会在mods目录中查找模块。-cp "lib/*": JVM 会在lib目录中查找传统的类。
重要提示： 当同时使用模块路径和类路径时，类路径中的所有代码都会被视为一个“未命名模块”，这会限制模块系统的一些特性（如强封装）。
总结与最佳实践
| 配置方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
命令行 -cp |
简单直接，无需工具 | 手动管理繁琐，易出错，不适合复杂项目 | 学习、快速测试、非常小的脚本 |
| 构建工具 (Maven/Gradle) | 强烈推荐，自动化管理依赖和 Classpath，标准化构建流程 | 需要学习构建工具的配置 | 几乎所有 Java 项目开发、企业级应用 |
系统属性 -Djava.class.path |
功能与 -cp 相同 |
可读性差，不推荐 | 特殊脚本或需要通过编程设置 Classpath 的场景 |
模块路径 --module-path |
现代 Java 标准，提供更好的封装和依赖管理 | 需要理解模块化概念，迁移成本高 | Java 9+ 的新项目，特别是大型、复杂的应用 |
核心建议：
- 对于任何非 trivial（非简单）的项目，请使用 Maven 或 Gradle。 这是行业标准,能让你从繁琐的依赖管理中解放出来。
- 学习命令行
-cp是必要的，因为它能帮助你理解 Classpath 的底层工作原理,在排查问题时非常有用。 - 拥抱模块化，如果你开始一个全新的 Java 9+ 项目，考虑使用 JPMS (Java Platform Module System)。
