Khắc phục lỗi cấu hình không hợp lệ '.prettierrc' trong VS Code

Thông báo lỗi

Bạn nhấn Lưu (Save), mong đợi mã nguồn của mình sẽ tự động căn chỉnh, nhưng không có gì xảy ra. Thay vì một tệp sạch đẹp, bạn thấy một biểu tượng cảnh báo nhỏ ở góc dưới bên phải của VS Code. Khi kiểm tra nhật ký (logs), bạn sẽ thấy thông báo chính xác như sau:

Error: Invalid configuration file: .prettierrc

Tại sao lỗi này xảy ra

Prettier rất khắt khe. Chỉ cần một dấu phẩy đặt sai vị trí hoặc một phím tab vô tình trong tệp YAML sẽ làm hỏng toàn bộ trình định dạng cho dự án của bạn. Thông thường, trình phân tích cú pháp gặp phải một ký tự không mong muốn, dẫn đến việc từ bỏ việc đọc toàn bộ tệp. Ngay cả khi 99% cài đặt của bạn là đúng, một lỗi cú pháp nhỏ cũng khiến toàn bộ tệp không thể đọc được.

Bước 1: Kiểm tra nhật ký đầu ra (Output Logs) của Prettier

Cảnh báo trên giao diện người dùng thường khá mơ hồ, nhưng nhật ký nội bộ lại rất cụ thể. Để tìm chính xác dòng gây ra sự cố, bạn cần đi sâu vào đầu ra của extension.

Mở bảng Output trong VS Code (Ctrl+Shift+U hoặc Cmd+Shift+U).
Trong menu thả xuống ở phía bên phải của bảng, chọn Prettier.
Cuộn xuống dưới cùng. Bạn sẽ thấy một stack trace với con trỏ cụ thể, ví dụ: "Unexpected token } in JSON at position 145".

Bước 2: Khắc phục các lỗi cú pháp phổ biến

Lỗi cú pháp khác nhau tùy thuộc vào định dạng bạn chọn cho tệp .prettierrc. Hãy kiểm tra các nguyên nhân phổ biến này trước.

Nếu sử dụng JSON (.prettierrc tiêu chuẩn)

JSON là định dạng phổ biến nhất, nhưng cũng dễ xảy ra lỗi nhất. Nó không hỗ trợ chú thích (comments) hoặc dấu phẩy cuối cùng (trailing commas). Ví dụ, cấu hình sau sẽ bị lỗi do dấu phẩy sau giá trị cuối cùng:

{
  "semi": true,
  "singleQuote": true,
  "printWidth": 80, // <--- Dấu phẩy này sẽ làm hỏng Prettier
}

Hãy xóa dấu phẩy cuối cùng đó và bất kỳ // chú thích nào để khắc phục.

Nếu sử dụng YAML

Lỗi YAML thường liên quan đến việc sử dụng "Tab hay Khoảng trắng". Prettier yêu cầu sử dụng khoảng trắng để thụt lề. Nếu bạn vô tình nhấn phím Tab, trình phân tích cú pháp sẽ báo lỗi ngay lập tức. Hãy đảm bảo việc thụt lề nhất quán—thường là hai khoảng trắng cho mỗi cấp độ.

semi: true
trailingComma: "all"
singleQuote: true
# Đảm bảo không có phím tab ẩn trước các dòng này

Bước 3: Kiểm tra bằng công cụ chuyển đổi

Nếu tệp trông có vẻ ổn nhưng vẫn báo lỗi, hãy thử một công cụ kiểm tra. Tôi thường sử dụng Công cụ chuyển đổi YAML ↔ JSON để xem cấu trúc có hợp lệ không. Nó chạy hoàn toàn trong trình duyệt, vì vậy cấu hình dự án của bạn vẫn được bảo mật. Nếu công cụ chuyển đổi không thể phân tích mã của bạn, Prettier chắc chắn cũng sẽ không thể.

Bước 4: Kiểm tra các ký tự ẩn (BOM)

Người dùng Windows nên lưu ý về Byte Order Mark (BOM). Một số trình chỉnh sửa lưu tệp UTF-8 với các ký tự ẩn ở ngay đầu tệp. Prettier thường gặp lỗi với những ký tự này. Hãy nhìn vào thanh trạng thái ở góc dưới bên phải trong VS Code. Nếu nó hiển thị UTF-8 with BOM, hãy nhấp vào đó, chọn Save with Encoding, và chọn UTF-8 thông thường.

Bước 5: Sử dụng phần mở rộng tệp rõ ràng

Khi bạn sử dụng tệp .prettierrc không có phần mở rộng, Prettier phải tự đoán định dạng. Nếu có một ký tự lạ, nó có thể đoán sai. Hãy thử đổi tên tệp thành .prettierrc.json hoặc .prettierrc.yaml. Điều này buộc trình chỉnh sửa sử dụng đúng trình phân tích cú pháp và thường làm lộ ra các lỗi tô sáng cú pháp mà bạn đã bỏ lỡ.

Xác minh kết quả

Sau khi bạn đã dọn dẹp cú pháp, hãy làm theo các bước sau để đặt lại extension:

Lưu tệp .prettierrc.
Mở Command Palette (F1 hoặc Cmd+Shift+P).
Nhập "Prettier: Restart Server" và nhấn Enter.
Mở một tệp nguồn (như index.js) và thực hiện lưu tệp. Bây giờ nó sẽ định dạng chính xác.

Mẹo phòng ngừa

Thêm Schema: Thêm "$schema": "http://json.schemastore.org/prettierrc" vào đầu cấu hình JSON của bạn. Điều này sẽ hiển thị gạch chân đỏ ngay khi bạn mắc lỗi.
Giữ mọi thứ đơn giản: Tránh các logic phức tạp hoặc định dạng bất thường. Một tệp .prettierrc.json đơn giản là lựa chọn tương thích nhất cho hầu hết các nhóm.
Tự động hóa kiểm tra: Sử dụng các công cụ như husky để chạy prettier --check . trước khi commit mã nguồn. Điều này giúp phát hiện các cấu hình bị lỗi trước khi chúng đến tay đồng nghiệp.