Ghi Chú: Decap CMS Đồng Bộ Nội Dung & Phân Quyền Vercel

Ghi chú nhanh về 3 vấn đề gặp phải sau khi setup xong Decap CMS + Astro Starlight + Vercel. Dùng để bổ sung vào bài viết chính thức sau.

Vấn đề 1: Số lượng bài trong CMS ít hơn trên web

Triệu chứng: Vào CMS thấy collection “Web Development” chỉ có vài bài, nhưng web thật lại hiển thị nhiều hơn.

Nguyên nhân: File config.yml của Decap CMS được cấu hình extension: "md", trong khi toàn bộ bài viết trong Astro Starlight lại có đuôi .mdx. CMS bị “mù” hoàn toàn với các file .mdx.

Cách sửa: Mở public/admin/config.yml, sửa tất cả các collection từ:

extension: "md"

thành:

extension: "mdx"

Sau khi sửa, CMS nhận ra toàn bộ bài viết cũ và hiển thị đúng số lượng.

Vấn đề 2: Local Backend không hiện nút đăng nhập

Triệu chứng: Chạy npx decap-server và npm run dev, nhưng vào /admin không thấy nút “Login with Local Backend”, chỉ thấy “Login with GitHub”.

Nguyên nhân: Cấu hình local_backend trong config.yml đang dùng dạng object phức tạp:

local_backend:
  url: http://localhost:8081
  allowed_hosts:
    - localhost

Phiên bản Decap CMS mới không nhận diện được cú pháp này.

Cách sửa: Đổi thành dạng đơn giản:

local_backend: true

Vấn đề 3: Cộng tác viên viết bài → Dấu X đỏ trên GitHub

Triệu chứng: Tài khoản được share (Collaborator) viết bài qua Decap CMS, commit lên GitHub thành công, nhưng hiện dấu X đỏ. Trong khi đó, cùng commit đó nếu do tài khoản chính push thì tick xanh bình thường.

Nguyên nhân: Dấu X đỏ đó là từ Vercel Deployment Check, không phải lỗi code. Vercel chỉ trigger Production Deployment đầy đủ cho tài khoản chính của dự án. Tài khoản cộng tác viên GitHub chỉ được cấp quyền Write trên GitHub repo, nhưng chưa được thêm vào Vercel Team.

Giải pháp lâu dài: Nâng cấp Vercel lên gói Pro và thêm tài khoản share vào Vercel Team (Settings → Members → Invite).

Giải pháp tạm thời (miễn phí): Cộng tác viên vẫn có thể viết bài bình thường. Bài sẽ nằm trên GitHub nhưng chưa được deploy. Khi tài khoản chính push bất kỳ thay đổi nào lên GitHub, Vercel sẽ deploy gộp tất cả các commit lại — bài của cộng tác viên sẽ tự động lên web cùng lúc đó.

Quy trình làm việc nhóm hiện tại

Cả 2 tk được thêm làm Collaborator trên GitHub repo.
Tk nào cũng vào /admin và đăng nhập được bằng “Login with GitHub”.
Cộng tác viên viết bài → Publish → commit lên GitHub (X đỏ, chờ).
Tk chính viết hoặc sửa bất kỳ thứ gì → push → Vercel deploy tất cả → web cập nhật luôn.