Từ ngày 17/11/2026, các JavaScript Worker có compatibility date từ 2026-11-17 trở đi sẽ dùng module registry mới theo mặc định, không cần bật cờ new_module_registry nữa. Worker Python giữ nguyên registry cũ, và Worker hiện tại không tự đổi hành vi cho tới khi bạn thay compatibility date hoặc cờ tương thích.

Vì sao đáng đọc? Module registry là bộ phận tìm và nạp các module JavaScript trong Worker. Khi cách nạp tiến gần hơn tới chuẩn JavaScript và Node.js, code chuẩn sẽ ít phải “uốn” theo nền tảng hơn — nhưng đổi mặc định cũng có thể làm gãy thói quen cũ ngay lúc deploy nếu bạn không kiểm tra trước.

require() nạp được ES module — với một điều kiện cứng

Với Worker bật tương thích Node.js, bạn có thể dùng require() để nạp ES module, với điều kiện module đó và toàn bộ dependency không dùng top-level await. Chỉ cần một dependency trong cây dùng top-level await, lệnh require() sẽ thất bại — và lỗi có thể nằm sâu trong dependency, không phải module bạn gọi trực tiếp.

import.meta: biết mình là ai, trỏ tới module khác mà không cần nạp

Bạn có thể dùng import.meta để lấy thông tin về module hiện tại và tìm URL của một module khác mà không cần nạp nó:

export default {
  fetch() {
    return Response.json({
      moduleUrl: import.meta.url,
      isEntrypoint: import.meta.main,
      helperUrl: import.meta.resolve("./helper.js"),
    });
  },
};

Trong đó, import.meta.url là URL của module hiện tại, import.meta.main cho biết module có phải entrypoint hay không. Còn import.meta.resolve(“./helper.js”) trả về một URL trong bundle; việc resolve không kiểm tra module có tồn tại hay không và không tải gì qua mạng. Build tool có thể biến đổi import.meta.

Hai điểm có thể làm gãy Worker của bạn

Thứ nhất, registry mới từ chối các import attributes không hợp lệ — thứ trước đây có thể lọt qua nay sẽ bị chặn. Thứ hai, require() thất bại khi cây dependency chứa top-level await. Cả hai đều là lỗi lúc nạp hoặc lúc chạy, nên bạn chỉ phát hiện khi đã deploy nếu không test trước.

Worker cũ không tự đổi — nhưng bạn vẫn cần chủ động

Worker hiện tại giữ nguyên hành vi cho tới khi bạn thay compatibility date hoặc cờ. Muốn thử registry mới trước ngày 17/11, giữ nguyên date và thêm cờ new_module_registry. Muốn giữ registry cũ sau ngày 17/11 dù đã nâng date lên 2026-11-17 trở đi, thêm cờ legacy_module_registry.

Điều này có ý nghĩa gì với bạn

Đừng nâng compatibility date của Worker production ngay ngày 17/11 chỉ vì “mặc định mới nghe hay hơn”. Trình tự an toàn hơn: kiểm tra date hiện tại, rà soát dependency xem có import attributes lạ hay top-level await trong cây require() không, bật cờ new_module_registry trên staging để chạy thử, rồi mới nâng date ở production. Worker Python không cần làm gì thêm vì vẫn dùng legacy registry. Nếu nâng date mà Worker lỗi, cờ legacy_module_registry là cách quay lại nhanh nhất.

Bài viết liên quan

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

Compatibility date là gì?

Đó là mốc ngày trong cấu hình Worker, cho Cloudflare biết Worker “nhắm tới” hành vi của nền tảng ở thời điểm nào. Đổi mốc này có thể bật hành vi mặc định mới, trong đó có module registry mới từ mốc 2026-11-17.

Python Workers có bị ảnh hưởng không?

Không. Theo Cloudflare, Python Workers tiếp tục dùng legacy registry, nên thay đổi này chỉ áp dụng cho JavaScript Worker.

Lỡ nâng compatibility date mà Worker lỗi thì làm sao?

Gắn cờ legacy_module_registry để quay lại registry cũ trong lúc khắc phục, sau đó sửa nguyên nhân gốc — thường là import attributes không hợp lệ hoặc top-level await — rồi thử lại trên staging.

💬 Tin này ảnh hưởng tới dự án của bạn thế nào? Chia sẻ góc nhìn của bạn trong phần bình luận — mình đọc hết và sẽ tổng hợp những ý hay nhất.

Nguồn tham khảo