netlify-config

Tổng quan về netlify-config

netlify-config dùng để làm gì

netlify-config là một tài liệu tham chiếu thực hành để viết và chỉnh sửa netlify.toml. Hãy dùng netlify-config khi bạn cần cấu hình builds, redirects, rewrites, headers, deploy contexts, environment variables, functions, hoặc edge functions mà không phải đoán cú pháp của Netlify.

Ai nên dùng nó

Đây là lựa chọn phù hợp nhất cho những người đã biết mình muốn Netlify làm gì, nhưng cần một cách diễn đạt đúng và đáng tin cậy. Hướng dẫn netlify-config đặc biệt hữu ích cho các thay đổi triển khai rất dễ sai lệch một cách tinh vi, như thứ tự redirect, catch-all routing, hoặc các thiết lập theo từng context.

Điều gì làm nó hữu ích

Skill này tập trung vào những chi tiết cấu hình ảnh hưởng trực tiếp đến hành vi deploy thật: vị trí file, cấu trúc TOML, cách khớp rule, và các tùy chọn đặc thù của Netlify như conditions và force rules. Nếu bạn đang cân nhắc giữa một prompt chung chung và netlify-config, thì skill này phù hợp hơn khi độ chính xác quan trọng hơn việc phác thảo ý tưởng.

Cách dùng netlify-config

Cài đặt và nạp skill

Hãy dùng luồng cài đặt netlify-config trong quy trình skills của bạn, rồi mở skills/netlify-config/SKILL.md làm điểm khởi đầu. Hiện tại repository trình bày skill này như một tham chiếu một file, nên bạn không cần lần theo các script hỗ trợ hay tài nguyên đi kèm nào khác.

Chuyển mục tiêu của bạn thành một prompt có thể dùng được

Cách dùng netlify-config hiệu quả nhất bắt đầu từ một mục tiêu triển khai cụ thể, không phải một yêu cầu mơ hồ. Đầu vào tốt sẽ nêu rõ loại site, file bạn đang chỉnh sửa, và kết quả bạn cần. Ví dụ: “Cập nhật netlify.toml để /docs/* rewrite sang /docs/index.html trong production, nhưng vẫn giữ /api/* proxy về backend ở mọi deploy context.”

Đọc đúng phần trước

Hãy bắt đầu từ các ví dụ về build settings và redirects, rồi xem các phần khớp với thay đổi của bạn: headers, deploy contexts, functions, hoặc edge functions. Trong thực tế, cách nhanh nhất để dùng netlify-config cho Deployment là map hành vi routing bạn muốn vào ví dụ gần nhất, rồi chỉnh cú pháp theo đó thay vì tự nghĩ lại từ đầu.

Mẹo giúp đầu ra tốt hơn

Hãy cung cấp cho skill đường dẫn file hiện tại, thư mục output của framework, và bất kỳ rule xung đột nào đã tồn tại. Nói rõ bạn cần rewrite, redirect hay proxy, vì những lựa chọn này sẽ quyết định giá trị status đúng và việc có cần force hay không. Nếu bạn đang làm trong monorepo, hãy nêu rõ base directory để cấu hình được đặt đúng chỗ.

Câu hỏi thường gặp về netlify-config

netlify-config chỉ dành cho netlify.toml thôi à?

Đúng, netlify-config tập trung vào netlify.toml và hành vi triển khai mà nó điều khiển. Nếu vấn đề của bạn rộng hơn ở chiến lược hosting trên Netlify, skill này vẫn hữu ích khi nhiệm vụ cốt lõi là cú pháp config hoặc thiết kế rule.

Khi nào một prompt bình thường là đủ?

Một prompt bình thường là đủ cho những câu hỏi ở mức khái quát như “redirect trên Netlify hoạt động thế nào?”. netlify-config phù hợp hơn khi bạn cần câu trả lời sẵn sàng để deploy, đặc biệt là với routing precedence, rewrites, hoặc các thiết lập theo context nơi chỉ một lỗi cú pháp nhỏ cũng có thể làm hỏng build.

Có thân thiện với người mới không?

Có, nếu bạn có thể mô tả mục tiêu triển khai bằng ngôn ngữ đơn giản. Rào cản chính không phải là độ khó của skill, mà là input chưa đầy đủ. Người mới sẽ có kết quả tốt hơn khi đưa vào current build command, publish folder, và các path pattern họ muốn thay đổi.

Khi nào không nên dùng nó?

Đừng dùng netlify-config nếu bạn هنوز đang phân vân giữa các platform, hoặc chưa biết thay đổi đó thuộc về redirects, headers, hay build settings. Đây là một skill về cấu hình, không phải công cụ giải thích chung về Netlify hay tư vấn kiến trúc site.

Cách cải thiện netlify-config

Nêu rõ vấn đề routing

Đầu ra mạnh nhất từ netlify-config đến từ các ví dụ path thật cụ thể. Thay vì nói “fix redirects,” hãy đưa path cũ, path đích, status code mong muốn, và mọi ngoại lệ. Như vậy skill có thể chọn giữa 301, 302, 200, và 404 mà không mơ hồ.

Bao gồm context triển khai và các ràng buộc

Với netlify-config cho Deployment, context là yếu tố quan trọng: hành vi chỉ áp dụng cho production, khác biệt giữa preview deploy, và các environment-specific variables đều có thể làm thay đổi đáp án đúng. Hãy nói rõ rule cần áp dụng toàn cục hay chỉ trong một deploy context, và nêu mọi ràng buộc hiện có từ CMS, SPA, hoặc API.

Yêu cầu file cuối cùng, không chỉ là lời khuyên

Một yêu cầu hữu ích cho netlify-config guide nên xin luôn đoạn netlify.toml chính xác để bạn có thể dán vào, kèm một ghi chú ngắn giải thích nó nên nằm ở đâu trong file. Cách này giảm qua lại nhiều lần và giúp phát hiện lỗi thứ tự trước khi deploy.

Lặp lại từ lần test deploy đầu tiên

Sau khi cấu hình đầu tiên được viết xong, hãy test hành vi path thật và tinh chỉnh dựa trên cách Netlify thực sự phục vụ. Các lỗi thường gặp gồm rule bị chặn bởi rule khác, thiếu force = true, và nhầm lẫn giữa redirects với rewrites; prompt tiếp theo nên mô tả hành vi quan sát được, không chỉ ý định ban đầu.