java中无法导入自定义类，通常源于包声明、目录结构、编译路径或ide配置不一致；本文系统讲解包导入的必备条件、常见错误及完整解决方案。
在Java中，import语句本身只是为类名提供简写引用方式，它并不能“让类变得可访问”——真正决定类能否被导入和使用的，是包结构、源码组织、编译路径（classpath）以及IDE项目配置三者的严格一致性。你遇到的 The import shui.utility cannot be resolved 错误，并非 import 语法失效，而是编译器根本找不到 shui.utility 这个包对应的字节码或源码。
✅ 正确导入自定义类的四大前提
-
包声明（package）必须存在且匹配目录结构
在 Utility.java 文件顶部，必须明确声明：package shui.utility; public class Utility { public static void log(String msg) { System.out.println("[UTIL] " + msg); } }对应的文件路径必须为：src/shui/utility/Utility.java（若使用标准Maven/Gradle结构）或 shui/utility/Utility.java（若直接编译）。
-
导入语句语法正确，且目标类为 public
在另一个类（如 Main.java）中，需使用完整包名导入：package shui.app; // 当前类所在包（可选，但推荐显式声明） import shui.utility.Utility; // ✅ 正确：导入具体类 // 或导入整个包（不推荐用于生产环境，易引发命名冲突） // import shui.utility.*; public class Main { public static void main(String[] args) { Utility.log("Hello from utility!"); // ✅ 可调用 } } -
编译与运行时 classpath 必须包含源码根目录
假设项目结构如下：project/ ├── src/ │ ├── shui/ │ │ ├── utility/ │ │ │ └── Utility.java │ │ └── app/ │ │ └── Main.java
编译命令需从 project/ 目录执行，并指定 src 为源路径：
# 编译所有 .java 文件（自动处理依赖） javac -d bin -sourcepath src src/shui/app/Main.java # 运行（确保 bin 是 classpath） java -cp bin shui.app.Main
⚠️ 注意：-sourcepath 指向源码根目录（src），而非 src/shui；-d bin 表示将 .class 输出到 bin/，保持包目录结构。
-
IDE 配置需识别源码根目录
立即学习“Java免费学习笔记（深入）”；
- Eclipse：右键项目 → Properties → Java Build Path → Source → 确保 src/ 被标记为 Source folder。
-
IntelliJ IDEA：右键 src 文件夹 → Mark Directory as → Sources Root。
若之前能正常工作而突然失败，大概率是 IDE 缓存损坏或项目结构被意外修改（如 src 失去源码根标记、.classpath 文件被覆盖等）。此时建议：
→ 清理项目（Eclipse: Project → Clean；IDEA: File → Invalidate Caches and Restart）
→ 重新导入项目（尤其 Maven/Gradle 项目务必执行 Reload project）
? 排查清单（快速定位问题）
- [ ] Utility.java 第一行是否为 package shui.utility;？
- [ ] 文件是否真实位于 src/shui/utility/Utility.java？
- [ ] Main.java 中 import shui.utility.Utility; 是否拼写准确（大小写敏感！）？
- [ ] Utility 类是否为 public class Utility？（非 public 类无法被其他包访问）
- [ ] IDE 是否将 src 正确识别为源码根目录？
- [ ] 是否尝试过命令行编译验证？排除 IDE 干扰。
✅ 总结
Java 的包导入机制是约定优于配置的典型体现：它不依赖配置文件，而严格依赖物理路径、package 声明与 import 语句三者的一致性。所谓“昨天还能用，今天不能用”，绝大多数情况是开发环境发生了静默变更（如IDE缓存异常、文件移动未同步更新package、构建工具清理了输出目录等）。坚持“结构即契约”的原则，配合上述四步验证与排查清单，99% 的自定义包导入问题均可快速解决。
