Java 新手十大常見錯誤與避坑指南：從編譯失敗到邏輯陷阱的完整解析

每個 Java 開發者的成長之路，都伴隨著無數次「為什麼不工作？」的深夜除錯。本文系統整理了從**環境配置、語法誤解、面向對象誤區、集合陷阱、併發隱患**五大維度的十大高頻錯誤，提供**錯誤代碼、報錯特徵、根因分析、最佳實踐**四步法解析，助您建立「防禦性編程」肌肉記憶，少走彎路。

一、環境與構建篇

1. 錯誤：`錯誤: 找不到或無法載入主類` / `error: cannot find symbol`

// ❌ 現象：javac 編譯通過，java 運行報錯
// 原因 1: 類名與檔案名不符 (Public 類必須與 .java 同名)
// 原因 2: package 聲明與目錄結構不匹配
// 原因 3: CLASSPATH 環境變量汙染或未包含當前目錄 (.)
// 原因 4: 未進入正確目錄執行 java 命令

// ✅ 最佳實踐
// 1. 严格遵循: Public 類名 == 檔案名 (區分大小寫)
// 2. 目錄結構 = 包結構: com/example/App.java -> package com.example;
// 3. **拒絕設定全局 CLASSPATH 環境變量** (汙染極大)
// 4. 使用構建工具 統一管理依賴與編譯運行
// 5. IDE 開發時信任 IDE 內建構建系統，命令行僅用於構建產物驗證

2. 錯誤：`UnsupportedClassVersionError` / `class file has wrong version`

• 現象： 編譯用 JDK 17，運行環境 JRE 8。
• 根因： Class 文件版本號不向下相容 (JDK 17 = 61, JDK 8 = 52)。
• 對策： `javac --release 8` (JDK 9+) 強制生成兼容字節碼，或統一開發/生產 JDK 版本 (推薦 LTS: 17/21)。

二、語法與核心語義篇

3. 錯誤：`switch` 穿透 / 忘記 `break`

// ❌ 經典災難
int day = 2;
switch (day) {
    case 1: System.out.println("Mon");
    case 2: System.out.println("Tue"); // 會打印 Tue, Wed, Thu...
    case 3: System.out.println("Wed");
    default: System.out.println("Other");
}

// ✅ Java 12+ Switch Expression (無穿透、返回值、箭頭語法)
String dayName = switch (day) {
    case 1 -> "Mon";
    case 2 -> "Tue";
    case 3 -> "Wed";
    default -> "Other";
};

// ✅ 必須用 break (舊版) 或 yield (塊語法)
switch (day) {
    case 1: System.out.println("Mon"); break;
    case 2: System.out.println("Tue"); break;
    // ...
}

4. 錯誤：`==` 比較物件內容 (String, Integer, 自定義類)

// ❌ 比較引用地址，非內容
String s1 = new String("hello");
String s2 = new String("hello");
System.out.println(s1 == s2); // false (不同對象)
System.out.println(s1.equals(s2)); // true

// ⚠️ 整數緩存陷阱 (-128 到 127)
Integer a = 127, b = 127; System.out.println(a == b); // true (緩存)
Integer c = 128, d = 128; System.out.println(c == d); // false (新對象!)

// ✅ 鐵律：比較內容永遠用 .equals()
// ✅ 基本類型才用 ==
// ✅ 枚舉比較可用 == (單例保證) 或 .equals()

5. 錯誤：浮點數精度失真與 `==` 比較

// ❌ 0.1 + 0.2 != 0.3
System.out.println(0.1 + 0.2); // 0.30000000000000004
if (0.1 + 0.2 == 0.3) ... // 永遠 false

// ✅ 金融/精確計算：BigDecimal
BigDecimal bd1 = BigDecimal.valueOf(0.1);
BigDecimal bd2 = BigDecimal.valueOf(0.2);
System.out.println(bd1.add(bd2)); // 0.3

// ✅ 科學計算/容差比較
double eps = 1e-9;
if (Math.abs((0.1+0.2) - 0.3) < eps) ... // 相對/絕對誤差判斷

6. 錯誤：陣列/集合索引越界

• 陷阱： `for (int i=0; i<=arr.length; i++)` (應 `<`)、`list.get(list.size())` (最大索引 `size()-1`)。
• 增強 for 迴圈隱性風險： 迴圈中 `list.remove()` 導致 `ConcurrentModificationException`。
• 對策： 統一使用 `for (int i=0; i

三、面向對象與設計篇

7. 錯誤：忽略封裝，濫用 `public` 欄位 / 缺少建構子驗證

// ❌ 貧血模型 + 破壞不變量
public class User {
    public String name; // 直接暴露
    public int age;     // 可設負數
}

// ✅ 封裝 + 不變量保護
public class User {
    private final String name; // 不可變
    private int age;           // 可控變更
    
    public User(String name, int age) {
        if (name == null || name.isBlank()) throw new IllegalArgumentException("姓名不可空");
        if (age < 0 || age > 150) throw new IllegalArgumentException("年齡非法");
        this.name = name;
        this.age = age;
    }
    // Getter/Setter 帶驗證
    public void setAge(int age) { if (age>=0) this.age = age; }
}

8. 錯誤：誤解參數傳遞「引用傳遞」 vs 「值傳遞」

// Java 唯有「值傳遞」：基本類型傳值，引用類型傳「引用的值」(地址副本)
public void swap(String a, String b) { // 無法交換外部引用指向
    String t = a; a = b; b = t; // 僅交換局部變量
}
public void modifyList(List list) {
    list.add("new"); // ✅ 修改對象內容：成功 (同一對象)
    list = new ArrayList<>(); // ❌ 修改引用指向：外部無感 (副本指向新對象)
}

// ✅ 需交換/返回新對象時，返回值或包裝類/陣列/集合
public List addAndReturnNew(List list) {
    List copy = new ArrayList<>(list);
    copy.add("new");
    return copy;
}

四、集合與流式處理篇

9. 錯誤：`HashMap` 多線程下死循環 / `ArrayList` 併發異常

• 現象： 高併發 `HashMap.put()` 導致 CPU 100% (JDK 7 死循環擴容)、`ArrayList` 寫入時讀取拋 `IndexOutOfBoundsException` / `ConcurrentModificationException`。
• 對策：
  • 單線程：`ArrayList`, `HashMap`, `HashSet`。
  • 多線程讀多寫少：`Collections.synchronizedList/Map` (鎖整體，效能一般)。
  • 高併發：`ConcurrentHashMap` (分段鎖/CAS)、`CopyOnWriteArrayList` (讀無鎖、寫複製)。
  • 迭代時修改：用並發集合迭代器 (弱一致性) 或 `removeIf` / 流式處理 `stream().filter().collect()`。

10. 錯誤：`Stream` 濫用 / 捕獲變量修改 / 並行流亂序

// ❌ 陷阱 1: 捕獲局部變量必須 final 或 effectively final
int count = 0;
list.stream().forEach(s -> count++); // 編譯錯誤: count not final
// ✅ 用 AtomicInteger / 長陣列 / 收集器
AtomicInteger cnt = new AtomicInteger();
list.stream().forEach(s -> cnt.incrementAndGet());
// ✅ 或直接用收集器
long count = list.stream().count();

// ❌ 陷阱 2: 並行流無序
list.parallelStream().forEach(System.out::print); // 順序亂
// ✅ 有序需求用 forEachOrdered / 串行流

// ❌ 陷阱 3: 副作用 (修改外部狀態) 違背函數式原則
List result = new ArrayList<>();
list.stream().filter(s -> s.length()>3).forEach(result::add); // 串行勉強可，並行錯
// ✅ 純函數式收集
List result = list.stream().filter(s -> s.length()>3).collect(Collectors.toList());

五、進階避坑清單 (Bonus)

總結：建立「防禦性編程」三大習慣

1. 編譯器是朋友： 開啟所有警告 (`-Xlint:unchecked` 等)，**零警告通過**。
2. 測試先行： 單元測試覆蓋核心邏輯，邊界值、空值、異常路徑必測。
3. 工具鏈護航： SpotBugs/PMD/SonarQube 靜態分析、CI 強制門檻、依賴漏洞掃描 (OWASP Dependency-Check)。

錯誤是學費，但**同樣的錯誤犯兩次就是能力不足**。將這份指南收藏，每次遇到詭異 Bug 時對照排查，您的 Java 功力將在「填坑」中穩步昇華。