"Chạy trên máy tôi bình thường mà": quy trình debug 7 bước

Có lẽ đây là câu nói nổi tiếng nhất ngành phần mềm, nổi tiếng tới mức đã thành meme, thành sticker, thành áo thun. Và đáng buồn là nó thường đúng: code chạy hoàn hảo trên máy bạn, nhưng hỏng trên máy đồng nghiệp, trên server kiểm thử, hoặc tệ nhất là trên môi trường thật.

Bản chất của vấn đề không nằm ở 'lỗi code'

Câu nói ấy không sai, nó chỉ chưa đầy đủ. Lẽ ra chúng ta nên hỏi tiếp: "…vậy thì hai máy khác nhau ở điểm nào?".

Mã nguồn giống hệt nhau nhưng kết quả khác nhau nghĩa là thứ khác nhau nằm ngoài code. Dưới đây là những khác biệt hay gặp nhất:

• Runtime: Phiên bản ngôn ngữ (Node.js 14 vs 16), JVM, hoặc thư viện.

• Cấu hình: Biến môi trường và file cấu hình bị thiếu hoặc sai.

• Dữ liệu: Cơ sở dữ liệu trống, dữ liệu mẫu không đồng nhất.

• Hệ thống file: Cách phân biệt chữ hoa/thường (macOS/Windows vs Linux).

• Địa lý: Múi giờ, ngôn ngữ và định dạng vùng miền.

• Mạng: Quyền truy cập, cổng giao tiếp và tường lửa.

Quy trình 7 bước giải quyết vấn đề có hệ thống

Dưới đây là quy trình 7 bước giúp trả lời câu hỏi "khác nhau ở đâu" một cách có hệ thống.

Bước 1: Tái hiện lỗi một cách chắc chắn

Mục tiêu của bước này là có một chuỗi thao tác mà cứ làm theo là lỗi xuất hiện. Nếu không tái hiện được lỗi, mọi thao tác sửa chỉ là đoán. Hãy thu thập đủ thông tin chi tiết: lỗi xảy ra ở môi trường nào, trình duyệt gì, dữ liệu đầu vào cụ thể ra sao.

Bước 2: So sánh môi trường (Compare Environment)

Bắt đầu so sánh hai môi trường cạnh nhau, bắt đầu từ những thứ dễ kiểm tra nhất.

Bash

# So sánh phiên bản ngôn ngữ
node --version

# So sánh phiên bản thư viện
npm ls <tên-thư-viện>

# Liệt kê và so sánh biến môi trường
printenv | sort

Ví dụ kinh điển: Import ./components/button trong khi file thật tên là Button.tsx. Trên macOS và Windows, hệ thống file mặc định không phân biệt chữ hoa chữ thường nên vẫn chạy. Trên server Linux, file đó "không tồn tại" và bản build hỏng ngay.

Bước 3: Đọc log ở đúng nơi xảy ra lỗi

Rất nhiều người chỉ đoán nguyên nhân dựa trên log ở máy mình, trong khi lỗi xảy ra ở server. Hãy đọc log ở chính môi trường bị lỗi và đọc toàn bộ thông báo lỗi. Nguyên nhân thật thường nằm ở những dòng "caused by" phía dưới.

Bước 4: Thu hẹp phạm vi

Lỗi có xảy ra khi bỏ qua bước A không? Có xảy ra với dữ liệu đơn giản hơn không? Nếu lỗi mới xuất hiện sau một đợt cập nhật, git bisect giúp tìm đúng commit gây lỗi:

Bash

git bisect start
git bisect bad                 # phiên bản hiện tại bị lỗi
git bisect good a1b2c3d        # phiên bản cũ còn chạy tốt

# kiểm tra từng phiên bản Git gợi ý, rồi đánh dấu good hoặc bad
git bisect good/bad

git bisect reset               # quay về như cũ khi tìm xong

Bước 5: Đặt giả thuyết và kiểm chứng từng cái một

Viết ra giả thuyết cụ thể: "Lỗi xảy ra vì server thiếu biến môi trường khoá thanh toán". Sau đó, thiết kế cách kiểm chứng giả thuyết đó và chỉ thay đổi một thứ mỗi lần.

Bước 6: Sửa nguyên nhân gốc, đừng vá triệu chứng

Hãy tự hỏi: Vì sao điều này xảy ra? Vá triệu chứng giống như dán băng dính lên đèn cảnh báo trên xe — đèn tắt, nhưng động cơ vẫn hỏng.

Bước 7: Chặn lỗi quay lại

Vài cách phòng ngừa:

• Test case: Viết một bài kiểm thử tái hiện đúng tình huống gây lỗi.

• Cố định phiên bản: Sử dụng file .nvmrc và file khoá phiên bản của trình quản lý gói.

• Containerization: Chạy ứng dụng trong Docker container để môi trường phát triển giống môi trường thật.

Lời kết

Lần tới khi định nói "chạy trên máy tôi mà", hãy nói tiếp: "…để tôi xem hai máy khác nhau ở đâu". Câu thứ hai mới là câu giải quyết được vấn đề.