Parser Liquid nghiêm ngặt của Shopify: Hướng dẫn cho chủ theme

Một theme Shopify đã dùng vài năm thường chứa những đoạn Liquid chạy được chỉ nhờ may mắn. Có dòng code trông hoàn toàn hợp lý, nhưng parser cũ có thể đã đọc nó theo cách dễ dãi và cho ra kết quả mà không ai chủ ý. Từ ngày 13 tháng 1 năm 2026, Shopify siết chặt điều này cho mọi theme. Ngay cả khi bạn chưa bao giờ mở code editor, việc biết điều gì đã thay đổi và ai bị ảnh hưởng vẫn rất hữu ích.

Shopify thực sự đã thay đổi gì

Changelog dành cho developer của Shopify cho biết parser Liquid nghiêm ngặt hơn được áp dụng cho mọi theme kể từ ngày đó. Mục tiêu được nêu là cải thiện chất lượng code, giảm lỗi cú pháp và tạo chỗ cho các tính năng Liquid mới sau này. Có hai hệ quả đáng chú ý trong thực tế:

Tự động viết lại code. Nếu một file theme chứa Liquid không đạt các quy tắc chặt hơn, Shopify sẽ viết lại giúp bạn. Shopify cho biết theme vẫn giữ nguyên hành vi và giao diện, và mỗi file bị chỉnh sửa đều có một dòng comment mô tả thay đổi.
Yêu cầu cao hơn với bản nộp mới. Theme và theme app extension gửi lên Theme Store hoặc App Store phải parse được theo các quy tắc nghiêm ngặt ngay từ đầu.

Shopify cũng duy trì một migration guide đi qua từng loại lỗi. Ý chính rất đơn giản: code từng bị đọc sai mà không báo gì nay sẽ báo lỗi cú pháp. Ví dụ trong chính hướng dẫn này là một phép gán trộn giá trị false và true bằng or. Với parser cũ, kết quả lặng lẽ là false, hiếm khi đúng ý người viết. Parser nghiêm ngặt từ chối đoán mò.

Những mẫu code dễ gây lỗi

Migration guide liệt kê rất nhiều trường hợp. Được nhóm lại theo chủ đề, đây là những mẫu đáng tìm nhất trong file của bạn.

Tham số truyền vào render

Không được dùng filter bên trong thẻ render. Hãy áp dụng filter trong assign hoặc echo trước, rồi truyền biến kết quả.
Tham số theo vị trí, ví dụ truyền một product rồi đến một collection, cần có tên như product: product.
Mọi tham số dạng keyword đều phải có giá trị. Một cờ đứng trơ trọi sẽ thành flag: true.
Từ khóa with kết hợp với các cặp key-value bị từ chối, và biểu thức điều kiện không được dùng làm tham số. Hãy bọc lệnh render trong một khối if.

Toán tử và cú pháp

Các từ and và or chỉ hợp lệ trong câu lệnh if. Dùng chúng trong assign hoặc case đòi hỏi phải cấu trúc lại code.
Thói quen từ JavaScript như hai ký tự ampersand liền nhau, hai ký tự pipe liền nhau và dấu ngoặc đơn trong điều kiện không phải là Liquid.
Mệnh đề when có dấu mũi tên là lỗi; giá trị phải đứng riêng.
Bên trong thẻ liquid, comment nằm chung dòng với code phải được chuyển xuống dòng riêng.

Dấu ngoặc vuông đứng đầu

Biểu thức bắt đầu bằng dấu ngoặc vuông giờ được dành riêng cho array literal. Nếu bạn từng dùng cách đó để tra cứu một key động ở đầu biểu thức, hãy thêm tiền tố self, để phép tra cứu trở thành self[key]. Các phép tra cứu trên một object có tên, như product[‘title’], không bị ảnh hưởng.

Checklist hợp lý cho chủ theme

Tìm các chỗ Shopify đã viết lại. Mở theme đang chạy và tìm các comment giải thích mà Shopify thêm vào. Biết file nào đã bị sửa cho bạn biết code gốc của mình vi phạm ở đâu.
Đồng bộ repository. Nếu theme của bạn nằm trong Git hoặc bạn deploy từ bản local, hãy kéo các thay đổi trên theme đang chạy về trước lần push tiếp theo. Deploy một bản cũ có thể đưa cú pháp ban đầu quay lại, và Shopify sẽ lại phải viết lại một lần nữa.
Tìm các mẫu nêu trên. Tìm kiếm văn bản cho hai ký tự ampersand liền nhau, hai ký tự pipe liền nhau, hoặc lệnh render có chứa ký tự pipe sẽ nhanh chóng bắt được nhiều trường hợp.
Kiểm tra các trang dùng snippet đã bị sửa. Việc viết lại nhằm giữ nguyên hành vi, nhưng những trang nhiều logic nhất, như trang sản phẩm có swatch biến thể hoặc badge tùy chỉnh, đáng được xem thủ công trên một bản theme nhân bản.
Hỏi nhà cung cấp. Theme đã mua và các app chèn snippet nên có phiên bản cập nhật. Nếu nhà cung cấp đã im hơi lặng tiếng, thì bản thân điều đó cũng là một thông tin hữu ích.

Nếu bạn thuê làm code tùy chỉnh

Hãy yêu cầu bất kỳ ai làm cho bạn bàn giao code parse được theo các quy tắc nghiêm ngặt và thử trên một theme phát triển trước. Đây cũng là lúc nên bỏ những dòng code một dòng “thông minh”: Liquid giản dị, với logic gom trong khối if và giá trị được gán trước khi dùng, dễ review hơn và ít chịu ảnh hưởng bởi các thay đổi parser trong tương lai. Shopify mô tả parser nghiêm ngặt là nền tảng cho các cải tiến sau này, nên code gọn gàng hôm nay nghĩa là bớt bất ngờ về sau.

Khi chọn theme, hãy xem nhà phát triển bảo trì như thế nào chứ không chỉ xem giao diện đẹp ra sao; bạn có thể xem các theme của chúng tôi làm điểm khởi đầu. Nếu bạn muốn nhờ một developer rà soát một cửa hàng cũ, hãy xem dịch vụ của chúng tôi.

Một giới hạn cần nói rõ: cả changelog lẫn migration guide đều không liệt kê mọi cấu trúc gây lỗi, và guide cũng không nêu công cụ nào để tìm chúng hàng loạt. Hãy xem bài viết này là điểm bắt đầu và đọc hướng dẫn chính thức khi một lỗi trỏ đến dòng code bạn không nhận ra.