Hướng dẫn đổi JDK mặc định trong IntelliJ IDEA

Khi làm việc với Java trong IntelliJ IDEA, rất nhiều lỗi “khó hiểu” thực ra không đến từ code mà đến từ việc IDE đang dùng sai JDK mặc định. Có lúc project chạy bằng Java 17, nhưng IntelliJ lại index theo Java 21. Có lúc Maven, Gradle, và Run Configuration mỗi nơi trỏ một phiên bản khác nhau. Kết quả là code nhìn đúng nhưng build thất bại, hoặc máy chạy được mà máy đồng đội lại lỗi.

Nếu bạn đang chuẩn bị nâng cấp dự án, mở một codebase cũ, hoặc đơn giản là muốn IntelliJ luôn dùng đúng JDK từ đầu, việc hiểu rõ “JDK mặc định” là rất quan trọng. Bài này của Kho Tàng Kiến Thức VN sẽ đi từ khái niệm nền tảng đến cách đổi đúng chỗ, để bạn không nhầm giữa JDK của IDE, JDK của project và JDK của công cụ build.

JDK mặc định trong IntelliJ IDEA là gì

Trong IntelliJ IDEA, từ “JDK mặc định” thường bị dùng chung cho nhiều lớp cấu hình khác nhau. Thực tế có ít nhất ba nơi bạn cần phân biệt. Một là JDK mà IntelliJ dùng để chạy chính IDE hoặc các tác vụ nội bộ. Hai là Project SDK, tức JDK mà project Java của bạn sử dụng khi biên dịch, gợi ý code và phân tích cú pháp. Ba là JDK mà Maven, Gradle hoặc từng Run Configuration riêng lẻ sử dụng khi build và chạy ứng dụng.

Nhiều người chỉ đổi một chỗ rồi tưởng đã xong, nhưng IntelliJ không hoạt động như một công tắc duy nhất. Ví dụ, bạn có thể đã đặt Project SDK là Java 21, nhưng Gradle vẫn dùng Java 17 nếu Gradle JVM chưa đổi. Hoặc project mới tạo ra vẫn mặc định bám theo một JDK cũ vì cấu hình template của IDE chưa được cập nhật. Vì vậy, muốn sửa dứt điểm, phải xác định bạn đang muốn đổi JDK cho mục đích nào.

Về mặt kỹ thuật, JDK là bộ phát triển Java gồm compiler, runtime và các thư viện cần thiết để build dự án. IntelliJ dựa vào JDK này để hiểu ngôn ngữ, suy luận kiểu dữ liệu, kiểm tra annotation, và chạy các tác vụ như test, debug hay code analysis. Nếu JDK bị lệch, IDE có thể hiển thị lỗi giả, hoặc tệ hơn là che mất lỗi thật vì nó đang phân tích theo một chuẩn khác với môi trường triển khai. Cơ chế này giải thích vì sao cùng một source code, chỉ cần đổi JDK là biểu hiện lỗi đã thay đổi ngay.

Cách đổi JDK mặc định cho project hiện tại

Nếu mục tiêu của bạn là đổi JDK cho project đang mở, nơi cần chỉnh đầu tiên là phần Project Structure. Trong IntelliJ, bạn vào File rồi chọn Project Structure, sau đó kiểm tra mục Project SDK và Project language level. Đây là cặp cấu hình quan trọng nhất vì nó quyết định project đang được IDE hiểu theo phiên bản Java nào. Nếu project cũ đang dùng Java 8 nhưng bạn chuyển sang JDK 21, cần bảo đảm language level cũng tương thích với code hiện tại, tránh dùng tính năng ngôn ngữ chưa được nâng cấp đồng bộ.

Sau khi đổi Project SDK, hãy kiểm tra tiếp từng module nếu project của bạn là multi-module. Một số dự án lớn có module core, module api, module test tách riêng, và mỗi module có thể kế thừa hoặc ghi đè SDK. Nếu module nào vẫn bám JDK cũ, bạn sẽ gặp hiện tượng một phần project báo lỗi đỏ còn phần khác thì bình thường. Với các dự án dùng .idea và file XML cấu hình cũ, IntelliJ đôi khi giữ lại cache của SDK trước đó, nên sau khi đổi xong bạn nên để IDE reimport hoặc refresh project để nó đồng bộ lại toàn bộ index.

Cơ chế ở đây khá rõ: IntelliJ không chỉ biên dịch theo một “biến toàn cục”, mà dùng cấu hình theo tầng. Project SDK là nền móng, module SDK có thể là lớp override, còn language level là bộ quy tắc ngữ pháp. Nếu ba lớp này không khớp, IDE sẽ phân tích source theo một chuẩn nhưng compiler lại chạy theo chuẩn khác. Điều đó tạo ra những lỗi rất khó đoán, nhất là ở dự án dùng tính năng mới như record, sealed class hay pattern matching. Vì thế, khi đổi JDK cho project hiện tại, đừng chỉ chọn một phiên bản Java cao hơn rồi bỏ qua các layer còn lại.

Đặt JDK mặc định cho project mới

Nếu bạn thường xuyên tạo project mới, việc chỉ sửa project hiện tại là chưa đủ. IntelliJ có thể dùng một JDK khác làm mặc định cho các project tiếp theo, và đây mới là bước giúp tiết kiệm thời gian về lâu dài. Thông thường, bạn vào File rồi mở New Projects Setup hoặc Settings for New Projects, sau đó chỉnh Project Structure hoặc Build, Execution, Deployment tùy phiên bản IntelliJ. Mục tiêu là đặt trước một Project SDK chuẩn để mọi project mới mở ra đều kế thừa đúng phiên bản đó.

Với người làm Java chuyên nghiệp, đây là chỗ nên đồng bộ với chuẩn đội nhóm. Nếu công ty đang dùng Java 17 cho sản phẩm production, nhưng cá nhân bạn cài Java 21 để thử nghiệm, hãy tách rõ JDK mặc định cho project mới và JDK phục vụ thử nghiệm. Điều này giúp giảm xung đột giữa môi trường local và CI. Trong nhiều đội, vấn đề không nằm ở code mà nằm ở việc mỗi lập trình viên tạo project mới với một default khác nhau, dẫn đến file cấu hình bị commit lẫn phiên bản Java không thống nhất.

Về cơ chế, IntelliJ thường lưu cấu hình mặc định cho project mới ở cấp application settings, không phải trong từng project riêng lẻ. Nghĩa là khi bạn đổi một project đang mở, những project sau này chưa chắc tự đổi theo. Đây là lý do nhiều người làm xong một project vẫn phải lặp lại thao tác cho project kế tiếp. Nếu bạn làm việc lâu dài với Java, đặc biệt khi chuyển giữa nhiều phiên bản như 8, 11, 17 và 21, việc chuẩn hóa default ngay từ đầu sẽ ổn định hơn rất nhiều. Trong các bài hướng dẫn nội bộ, Kho Tàng Kiến Thức VN thường xem đây là bước “đỡ lỗi ngầm” quan trọng nhất trước khi đụng vào code.

Đồng bộ JDK với Maven, Gradle và Run Configuration

Đây là phần dễ bị bỏ sót nhất. Nhiều người đã đổi Project SDK nhưng vẫn thấy build lỗi hoặc test chạy sai phiên bản Java. Lý do là Maven và Gradle có thể dùng JDK riêng. Với Gradle, bạn cần kiểm tra Gradle JVM trong phần settings của Gradle. Với Maven, IntelliJ có thể dùng JDK của import hoặc JDK của từng runner tùy cấu hình. Còn với Run Configuration, mỗi cấu hình chạy ứng dụng hay test cũng có thể chỉ định một JDK khác nhau.

Nếu bạn đang dùng Gradle, hãy chú ý thêm tới Java toolchain. Đây là cơ chế cho phép Gradle yêu cầu đúng phiên bản Java để compile và test, bất kể IntelliJ đang dùng JDK nào cho giao diện IDE. Toolchain rất hữu ích khi team cần giữ source code ổn định trên một chuẩn Java, nhưng nó cũng tạo ra cảm giác “đã đổi JDK rồi mà sao vẫn không tác dụng” nếu bạn chỉ nhìn ở mức IDE. Trong trường hợp này, IntelliJ chỉ là lớp điều phối, còn Gradle mới là nơi quyết định compiler thực sự chạy bằng phiên bản nào.

Về mặt nguyên lý, build tool và IDE là hai hệ thống độc lập nhưng giao tiếp với nhau qua cấu hình. IntelliJ phân tích code, tạo index, hiển thị gợi ý. Maven hoặc Gradle xử lý dependency graph, task build và test execution. Khi hai hệ thống dùng JDK khác nhau, bạn có thể thấy code completion hợp lệ nhưng build thực tế lại lỗi, hoặc ngược lại. Điều này đặc biệt hay xảy ra khi dự án dùng annotation processor, Lombok, hay plugin build phụ thuộc vào API Java cụ thể. Vì vậy, đổi JDK trong IntelliJ chỉ là bước đầu. Muốn môi trường ổn định, bạn phải đồng bộ cả IDE, build tool và run target.

Lỗi thường gặp sau khi đổi JDK và cách kiểm tra nhanh

Lỗi phổ biến nhất sau khi đổi JDK là IntelliJ vẫn hiển thị đỏ ở các file Java dù project đã trỏ đúng phiên bản mới. Khi đó, nguyên nhân thường không phải do code mà do cache, module SDK hoặc language level chưa khớp. Trường hợp này nên kiểm tra lại Project SDK, Module SDK, Gradle JVM hoặc Maven importer. Nếu mọi thứ đã đúng mà lỗi vẫn còn, hãy để IntelliJ reimport project hoặc invalidates caches theo cách có kiểm soát. Nhiều lỗi index cũ chỉ biến mất sau khi IDE xây lại chỉ mục từ đầu.

Một lỗi khác là cài sẵn nhiều JDK trên máy nhưng IntelliJ tự chọn sai bản. Điều này hay xảy ra khi đường dẫn JDK cũ vẫn còn trong danh sách SDK đã đăng ký. IDE không thể “đoán” mục nào bạn muốn nếu có hai thư mục Java trông gần giống nhau. Với môi trường macOS, Windows hay Linux, cách an toàn nhất là kiểm tra kỹ version của từng JDK đã add vào IntelliJ, rồi gỡ bản không dùng nữa nếu cần. Khi bạn dùng nhiều phiên bản Java song song cho học tập, bài tập hoặc dự án legacy, việc đặt tên rõ ràng cho từng SDK sẽ giảm nhầm lẫn rất nhiều.

Cơ chế kiểm tra nhanh là đối chiếu ba điểm cùng lúc: phiên bản JDK trong Project Structure, phiên bản Java báo trong terminal của IDE, và phiên bản mà build tool thực sự in ra khi chạy task. Ba giá trị này nên khớp với mục tiêu dự án. Nếu một trong ba lệch, bạn đã tìm được nơi gây lỗi. Đây là thói quen nhỏ nhưng rất hiệu quả, nhất là khi làm việc với dự án cũ, nơi source code, dependency và môi trường build thường không cùng thời điểm cập nhật. Chỉ cần kiểm tra theo lớp, bạn sẽ tránh được rất nhiều giờ debug vô ích.

Câu hỏi thường gặp

Đổi JDK mặc định trong IntelliJ có làm hỏng project cũ không?
Không, nếu bạn đổi đúng chỗ và đúng phiên bản tương thích. Project cũ chỉ gặp vấn đề khi code đang dùng API không còn phù hợp hoặc language level bị nâng quá cao so với source hiện tại.

Vì sao đã đổi Project SDK nhưng build vẫn chạy JDK cũ?
Vì Gradle, Maven hoặc Run Configuration có thể đang dùng JDK riêng. IntelliJ không ép tất cả công cụ dùng chung một phiên bản nếu bạn chưa đồng bộ từng nơi.

Nên dùng một JDK cho tất cả project hay tách riêng từng project?
Nếu team chỉ dùng một chuẩn Java thì nên thống nhất một JDK mặc định để giảm lỗi cấu hình. Nếu bạn làm nhiều dự án legacy, nên tách rõ từng project để tránh nhầm giữa Java 8, 11, 17 hoặc 21.

Có cần đổi JDK trong IntelliJ khi máy đã cài JAVA_HOME mới không?
Có thể có. JAVA_HOME ảnh hưởng tới terminal và một số tool bên ngoài, nhưng IntelliJ vẫn có thể giữ SDK riêng trong settings của nó. Hai nơi này không luôn đồng bộ tự động.

Sau khi đổi JDK, IntelliJ vẫn báo lỗi đỏ thì nên làm gì trước?
Hãy kiểm tra lại Project SDK, Module SDK, Gradle JVM hoặc cấu hình Maven trước. Nếu tất cả đã đúng mà lỗi vẫn còn, mới tính đến việc refresh project hoặc làm sạch cache của IDE.

Khi đổi JDK trong IntelliJ IDEA, điều quan trọng nhất không phải là bấm đúng một nút, mà là hiểu đúng lớp cấu hình nào đang điều khiển lớp nào. Chỉ cần phân biệt rõ JDK của project, JDK của build tool và JDK của IDE, bạn sẽ kiểm soát được hầu hết lỗi môi trường Java trong thực tế.