Hướng dẫn CORS cấu hình API website: preflight, header chuẩn và thực hành trên Next.js
· Tác giả: Trường — Founder Webchốt
Hướng dẫn CORS cấu hình API website thường bắt đầu từ cảm giác “API chạy trên Postman mà lên web thì lỗi” — đó là dấu hiệu bạn đang gặp chính sách cùng nguồn gốc trên trình duyệt, không phải lỗi server trả 500. CORS (Cross-Origin Resource Sharing) quy định khi nào JavaScript ở trang A được phép đọc phản hồi từ API ở trang B. Nếu thiếu header phù hợp, trình duyệt chặn ở tầng client: mạng vẫn tới server, song app React hoặc form fetch không thấy dữ liệu. Với product dùng nhiều subdomain, micro-frontend hoặc partner tích hợp qua script, bạn cần quy ước rõ allowlist origin, phương thức, header tùy chỉnh và cả phản hồi preflight OPTIONS. Bài này đi theo trục thực chiến: giải thích cơ chế, cấu hình an toàn, bảng so sánh nhanh, quy trình năm bước cho team nhỏ, rồi neo lại phạm vụ doanh nghiệp qua dịch vụ triển khai Webchốt khi bạn cần bàn giao tài liệu cho vận hành thay vì vá tạm bằng mở rộng * vô tội vạ.
Minh họa bối cảnh vận hành API: CORS ảnh hưởng trực tiếp tới trải nghiệm gọi dữ liệu từ trình duyệt | Nguồn: webchot.com
Cors api Next.js: Route Handler, middleware và chỗ đặt header cho đúng vòng đời request
Với App Router, cors api Next.js thường được xử lý tại file route.ts trong thư mục app/api hoặc các segment động: bạn trả NextResponse.json kèm Headers khởi tạo cho Access-Control-Allow-Origin và các header đồng hành. Ưu điểm là logic CORS nằm cạnh handler đích, dễ đọc diff trong PR và tái sử dụng helper kiểm tra origin qua biến môi trường ALLOWED_ORIGINS. Middleware có ích khi nhiều route chia sẻ một ma trận rule giống nhau — ví dụ toàn bộ prefix /api/partner — nhưng hãy tránh gắn trùng header ở hai lớp làm client nhận hai giá trị mơ hồ. Edge versus Node runtime có khác biệt nhỏ về thời gian và giới hạn, song nguyên tắc preflight vẫn giữ: OPTIONS phải trả đủ Methods và Headers mà client khai báo trong Access-Control-Request-*.
Nếu API của bạn là proxy sang hệ thống nội bộ, hãy phân tách: header CORS chỉ nên mô tả quan hệ giữa trình duyệt và domain Next của bạn; chứng thực server-to-server nằm ở lớp khác. Team frontend chỉ cần biết endpoint public đã mở đúng origin staging và production. Khi cần neo chi phí và phạm vi, hãy đối chiếu nhanh với bảng giá Webchốt để bố trí cả tài liệu bàn giao lẫn thời gian rà soát bảo mật trước khi bật tích hợp cho đối tác bên ngoài.
Header CORS cốt lõi: Allow-Origin, Methods, Headers và lúc nào cần Max-Age
Access-Control-Allow-Origin xác định origin nào được phép đọc phản hồi. Dùng danh sách cố định thay vì phản chiếu mù quáng mọi giá trị Origin từ request, trừ khi bạn hiểu rõ rủi ro lừa trình duyệt. Access-Control-Allow-Methods liệt kê GET, POST, PUT, DELETE cần thiết; thiếu phương thức sẽ làm preflight từ chối dù bạn vẫn thấy route tồn tại. Access-Control-Allow-Headers bắt buộc khi client gửi Authorization, X-Request-Id hoặc bất kỳ header tùy biến nào. Max-Age cho trình duyệt biết cache bao lâu kết quả preflight, giúp giảm số lần OPTIONS lặp lại trên người dùng trung thành. Dưới đây là bốn điểm thường bị bỏ sót khi team mới chạm CORS lần đầu.
- Điểm 1: Nhầm lẫn lỗi 401 từ API với lỗi CORS — mở tab Network, xem request preflight trước khi sửa chính sách xác thực.
- Điểm 2: Quên cấu hình OPTIONS trên tầng reverse proxy, khiến 404 hoặc 405 dù Node đã chuẩn.
- Điểm 3: Bật credentials mà vẫn dùng Allow-Origin * — trình duyệt sẽ chặn theo chuẩn, không có ngoại lệ “gần đúng”.
- Điểm 4: Trùng lặp header từ CDN và origin làm giá trị hợp lệ trở thành không xác định.
Bảng đối chiếu nhanh: mở trực tiếp trên API so với BFF cùng origin
Trước khi chốt mã, hãy thống nhất tiêu chí: số lượng origin cần mở, mức độ tin cậy cookie, chi phí bảo trì và khả năng audit sau này. Bảng này không đưa ra phán quyết tuyệt đối; nó giúp PM và engineer dùng chung một ngôn ngữ khi tranh luận “tại sao không để front gọi thẳng nhà cung cấp thứ ba”.
| Tiêu chí | Lựa chọn A | Lựa chọn B | Khuyên dùng |
|---|---|---|---|
| Độ phức tạp CORS | Mở từng origin trên API công khai | Ẩn sau BFF cùng domain với site | API công tức thời trả dữ liệu công khai; dữ liệu nhạy cảm nên qua BFF |
| Quản lý bí mật | Client giữ token nguồn mở | Chỉ server giữ secret | Ưu tiên server lưu khóa, hạn chế lộ diện trên bundle JS |
| Khả năng debug | Lỗi hiển thị ngay trên console fetch | Lỗi ẩn sau gateway | Tách log request-id và correlation-id để nối vết hai phía |
| Chi phí vận hành | Ít hop trung gian | Thêm một lớp compute | Nếu chỉ vì CORS mà thêm BFF, cân nhắc gom header ở API; nếu vì bảo mật, BFF xứng đáng |
Sau bảng, hãy ghi lại quyết định trong ADR ngắn: origin nào được mở, thời hạn dự án partner, ai chịu trách nhiệm gia hạn chứng chỉ SSL và khi nào cần thu hồi quyền. Nếu bạn cần bộ layout marketing đồng bộ với tài liệu kỹ thuật, tham khảo template Next.js Webchốt để phần tài liệu API đi cùng giao diện thương hiệu.
Quy trình năm bước: từ tái hiện lỗi tới bàn giao checklist CORS ổn định
- Bước 1: Tái hiện trên trình duyệt thật, mở DevTools, lọc XHR/fetch và lưu cặp request preflight cùng request chính để biết header nào bị từ chối.
- Bước 2: Liệt kê origin hợp lệ: production, staging, preview Vercel hoặc IP nội bộ; gom vào biến môi trường dạng danh sách, tránh hard-code rải rác.
- Bước 3: Cấu hình route handler hoặc middleware trả đủ bộ header trên cả phương thức OPTIONS — kiểm tra bằng curl -X OPTIONS -H "Origin: ..." -H "Access-Control-Request-Method: POST".
- Bước 4: Bật thử credentials nếu cần cookie phiên: đặt Access-Control-Allow-Credentials true và origin cụ thể, đồng bộ SameSite phía auth.
- Bước 5: Viết bài kiểm thử tích hợp hoặc script smoke gọi từ origin giả lập, gắn vào pipeline trước khi deploy; lưu lại mẫu phản hồi chuẩn để on-call đối chiếu khi partner báo sự cố.
Chuỗi bước này giúp bạn tránh cảnh “sửa trên máy dev localhost được mà lên domain thật thì hỏng” vì thiếu biến môi trường. Khi dự án cần người chịu trách nhiệm rõ, hãy mở trang liên hệ Webchốt để gửi mô tả nhanh về danh sách origin và môi trường deploy. Nếu bạn ưu tiên tự phục vụ trước, hub công cụ Webchốt cũng gợi ý cách trình bày số liệu cho stakeholder khi cần giải thích thời gian chết do cấu hình sai preflight.
Chi phí vận hành, phạm vi và khi nào CORS chỉ là một phần trong gói triển khai
CORS không tốn phí license riêng, song thời gian kỹ sư debug sai sót giữa staging và production thường đắt hơn budget hosting một tháng. Khi roadmap của bạn gồm nhiều đối tác đọc cùng API, bạn cần tài liệu allowlist, cảnh báo thay đổi header và cơ chế thông báo trước khi thu hồi quyền. Gói dịch vụ tại mục dịch vụ Webchốt thường bao gồm rà soát an toàn cơ bản, chuẩn hóa biến môi trường và bàn giao checklist vận hành sao cho team nội bộ tự mở origin mới mà không phá vỡ môi trường cũ. Nếu bạn đang tính toán kinh phí tổng, hãy cộng thêm thời gian on-call: incident CORS ban đêm thường kéo theo cả bức xúc từ phía partner.
Ở góc độ sản phẩm, hãy cân nhắc mức “đủ tốt” thay vì mở tối đa: public read-only data có thể dùng cache CDN; thao tác ghi nhận cần lớp xác thực rõ. Một số tổ chức chọn zero trust qua API gateway thay vì mở rộng dài Access-Control — đó là quyết định kiến trúc, không chỉ từ vựng CORS. Với doanh nghiệp vừa và nhỏ, ưu tiên tài liệu ngắn mà mọi dev mới đọc trong mười lăm phút sẽ giảm lỗi lặp lại hơn là bài blog dài dằng dặc.
Sai lầm phổ biến khi cấu hình CORS trên môi trường thật
Nhiều team lần đầu triển khai API public dễ rơi vào bẫy: sửa tạm bằng Allow-Origin * để “cho chạy”, hoặc bật reflect origin mà không kiểm tra, hoặc quên rằng thiết bị di động cũng cần cùng chính sách. Dưới đây là bốn lỗi cụ thể khi audit lại trước khi bật tích hợp lớn.
- Sai lầm 1: Mở phản xạ mọi giá trị Origin từ header request — tạo lỗ hổng nếu kẻ tấn công dụ trình duyệt nạn nhân gọi qua trang độc hại.
- Sai lầm 2: Chỉ test bằng Postman hoặc curl mà không bật trình duyệt; CORS là chính sách trình duyệt, không phải chuyện “server trả 200 là xong”.
- Sai lầm 3: Quên map OPTIONS trên load balancer, khiến preflight chạm máy sai hoặc thiếu header dù Node đã đúng.
- Sai lầm 4: Không phiên bản hóa tài liệu cho partner; khi bạn thu hẹp Methods, họ vẫn gửi PUT cũ và đổ lỗi “API hỏng”.
FAQ — hướng dẫn CORS cấu hình API website
CORS là gì và tại sao trình duyệt lại chặn gọi API chéo origin?
CORS là bộ quy tắc trình duyệt áp dụng cho request JavaScript giữa hai origin khác nhau, nhằm hạn chế trang độc hại đọc dữ liệu lén dùng session của bạn. Khi thiếu header phản hồi hợp lệ, trình duyệt chặn ở tầng client: bạn thấy lỗi network dù server vẫn ghi log 200. Phân biệt với lỗi 401/403 từ API bằng cách mở tab Network và xem cả preflight. Cấu hình Access-Control-Allow-Origin hoặc đưa gọi về cùng origin qua BFF sẽ mở đường hợp pháp. Với dữ liệu công khai, cân nhắc cache CDN thay vì mở rộng dài danh sách origin nếu không cần cookie.
Preflight OPTIONS xảy ra khi nào và cần cấu hình gì trên server?
Trình duyệt gửi preflight khi request không thuộc nhóm “đơn giản”, chẳng hạn dùng PUT/DELETE, thêm header tùy biến hoặc gửi JSON với Content-Type đặc thù. Server cần trả 200/204 cho OPTIONS kèm Access-Control-Allow-Methods, Allow-Headers và tùy chọn Max-Age. Thiếu một mục, trình duyệt hủy bước gửi chính. Bật log riêng cho OPTIONS để không nhầm với lỗi ở bước sau. Nếu bạn dùng reverse proxy, hãy xác minh nó chuyển tiếp đủ phần thân và header tới ứng dụng. Max-Age hợp lý giúp giảm tải khi người dùng thao tác lặp lại trên cùng phiên.
Cors api Next.js nên cấu hình ở middleware, route handler hay server ngoài?
Trên App Router, route handler trả CORS sát nơi xử lý nghiệp vụ, dễ test và code review. Middleware phù hợp khi cùng một bộ rule cho cả lớp path. Nếu API nằm sau Nginx hoặc API gateway, cân nhắc cấu hình ở lớp đó để thống nhất mọi runtime. Tránh lặp header mâu thuẫn giữa edge và origin. Với serverless, cold start vẫn phải trả header đúng trên cả OPTIONS. Gom hàm allowlist origin chung giúp bạn mở môi trường mới mà không sao chép dán lỗi. Khi cần tư vấn bố cục, dịch vụ Webchốt thường bắt đầu từ sơ đồ luồng thực tế của bạn.
Access-Control-Allow-Credentials true kết hợp Allow-Origin * có an toàn không?
Chuẩn trình duyệt cấm kết hợp credentials với Allow-Origin *; request sẽ bị từ chối. Khi cần cookie hoặc header Authorization, bạn phải trả origin cụ thể trùng với nguồn gọi. Nên dùng allowlist thay vì phản xạ mù. Kết hợp thêm chính sách SameSite cho cookie và chống CSRF cho thao tác thay đổi dữ liệu. Nếu API công khai không cần session, tắt credentials giúp giản lược. Luôn xác minh bằng trình duyệt thật vì chính sách khác hẳn curl. Ghi ràng buộc này trong tài liệu cho partner để tránh “sửa tạm” phá vỡ bảo mật.
Khi nào nên nhờ Webchốt hỗ trợ thay vì tự sửa CORS tạm thời bằng plugin?
Khi bạn có nhiều môi trường, nhiều domain marketing và cần tài liệu bàn giao rõ, cách vá tạm dễ tích nợ. Webchốt chuẩn hóa header, log preflight và gợi ý mô hình BFF nếu cần che token. Gọi 0905 151 701 hoặc hi@webchot.com kèm danh sách origin và stack deploy. Bạn cũng có thể xem thêm bảng giá để ước thời gian rà soát. Mục tiêu là production ổn, partner tin tưởng, on-call đỡ cãi vã nửa đêm vì thiếu dòng header.
Liên Hệ Webchốt
Hướng dẫn CORS cấu hình API website hiệu quả nhất khi cả sản phẩm lẫn vận hành cùng nhìn một bảng: origin nào được mở, phương thức nào phục vụ công khai, chứng thực đặt ở đâu và ai chịu trách nhiệm khi đối tác thêm domain mới. Khi header được phiên bản hóa và preflight được log rõ, bạn giảm thời gian chữa cháy, tăng niềm tin từ phía tích hợp. Webchốt hỗ trợ theo sprint, bàn giao mã nguồn và chính sách bảo hành 12 tháng cùng hoàn 100% trong 7 ngày nếu không đạt thỏa thuận đầu vào đã ký. Hãy dùng hotline hoặc email bên dưới để gửi mô tả nhanh danh sách origin và môi trường staging khi bạn muốn kiểm tra trước khi mở cửa tích hợp lớn.
- Hotline / Zalo: 0905 151 701 — gặp anh Trường (founder/dev).
- Chat Zalo: zalo.me/0905151701 — phản hồi nhanh.
- Email: hi@webchot.com — phản hồi <12h làm việc.
- Studio: 262/1/93 Phan Anh, Phường Phú Thạnh, TP.HCM (T2–T7, 9h–18h).
Tham khảo thêm: 17 template Next.js · 10 dịch vụ web chuyên sâu · bảng giá Webchốt 2026 · 12 công cụ kế toán/tài chính miễn phí · trang liên hệ Webchốt.
Reference: Next.js docs · web.dev Core Web Vitals.
