最常见原因是源文件路径与包结构不匹配或类路径设置错误：需按package建目录、从外层执行javac/java，且确保JAVA_HOME指向JDK、PATH含bin、无中文路径和空格问题。
javac 编译失败：找不到类或符号
最常见原因是当前目录没在源文件所在路径，或者 javac 没识别到 .java 文件的包结构。比如你写了 package com.example;，但把 MyApp.java 直接放在桌面运行 javac MyApp.java，编译器会报 error: class MyApp is public, should be declared in a file named MyApp.java 或更隐蔽的“找不到符号”。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 先用
cd进入源文件所在目录（不是父目录，也不是 IDE 项目根目录） - 如果含
package声明，必须按包名建子目录：比如package com.example;，就要把文件放在com/example/MyApp.java，然后从com的上一级目录执行javac com/example/MyApp.java - 确认文件名和
public class名完全一致（大小写敏感） - 别用中文路径——
javac在 Windows 上遇到中文路径可能静默失败
java 命令运行时报 NoClassDefFoundError 或 Could not find or load main class
这不是代码错了，而是类路径（-cp 或 -classpath）没设对。编译生成的 .class 文件必须能被 java 找到，且包结构、类名、入口方法签名三者必须严格匹配。
实操建议：
立即学习“Java免费学习笔记（深入）”；
-
java后面跟的是**类名**，不是文件名，也不带.class后缀；例如运行MyApp.class，命令是java MyApp - 如果有
package，运行时必须在包的**外层目录**执行，并显式指定类路径：java -cp . com.example.MyApp - 不要在
MyApp.class所在目录直接运行java MyApp—— 如果有 package，这会失败 - 检查
main方法是否为public static void main(String[] args)，少一个修饰符或参数类型错都会报错
Windows / macOS / Linux 下路径分隔符和 shell 行为差异
同一套命令，在不同系统上可能因路径写法或 shell 解析方式出问题。比如 Windows 的 ; 和 macOS/Linux 的 : 作类路径分隔符，或者 PowerShell 对引号、空格的处理比 cmd 更严格。
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 类路径中多个路径用
:（macOS/Linux）或;（Windows），别混用；可以用echo $CLASSPATH或echo %CLASSPATH%看环境变量是否干扰 - 路径含空格时，整个路径用英文双引号包裹：
java -cp "lib/my-tool.jar:." MyApp - PowerShell 中，
java可能被别名覆盖（比如指向java.exe但版本不对），用Get-Command java确认实际调用路径 - Mac 上通过 Homebrew 安装的 JDK，
java -version显示正常，但javac可能不在$PATH—— 检查which javac
没有 IDE 时怎么快速验证 Java 环境是否真可用
别急着写业务逻辑，先用最小闭环验证 JDK 安装、编译、运行三步都通。很多人卡在“以为装好了”，其实 JAVA_HOME 指向了 JRE 而非 JDK，或 PATH 漏了 bin 目录。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 新建一个纯文本文件
Hello.java，内容就一行：class Hello { public static void main(String[] args) { System.out.println("OK"); } } - 终端执行：
javac Hello.java && java Hello—— 如果输出 OK，说明基础链路通了 - 如果报
command not found: javac，说明javac不在PATH；检查JAVA_HOME是否指向 JDK 根目录（不是 JRE），并确认$JAVA_HOME/bin已加入PATH - Linux/macOS 上，别用
sudo apt install default-jdk后就完事——某些发行版默认装的是 OpenJDK 的 JRE 包，得明确装openjdk-17-jdk这类完整包
最容易被忽略的是包声明与目录结构的强绑定关系，以及 java 命令对类路径的“绝对路径感”——它不猜，也不递归找，你指哪它打哪。稍微偏一格，就报错，而且错误信息往往不直说“你路径错了”，只说“找不到类”。
