Bước 1: khai báo tường minh packages trong pnpm-workspace.yaml
pnpm 10.x yêu cầu trường này, kể cả khi repo chỉ có một package ở root:
packages:
- "."
Thiếu dòng này, bước cài dependency trên CI sẽ fail trước khi build kịp chạy — dễ gây nhầm lẫn vì local vẫn chạy bình thường nếu máy bạn cài bản pnpm cũ hơn.
Bước 2: thêm wrangler làm devDependency trực tiếp
Dù @astrojs/cloudflare đã kéo theo wrangler như dependency gián tiếp, một số môi trường CI cài "sạch" không đảm bảo binary đó có sẵn đúng như trên máy dev. Thêm trực tiếp vào package.json:
pnpm add -D wrangler
Quy tắc chung: CLI nào script build/deploy gọi trực tiếp, hãy khai báo nó là dependency trực tiếp — đừng dựa vào việc nó tình cờ có mặt qua package khác.
Bước 3: kiểm tra lại các bước phụ trong script build
Nhân tiện dọn build, tôi cũng rà lại xem có bước nào chạy không cần thiết — ví dụ bước index tìm kiếm (Pagefind) chạy dù tính năng search đang tắt tạm thời. Bỏ những bước như vậy ra khỏi script build mặc định giúp CI nhanh hơn và giảm điểm có thể fail.
Bước 4: test bằng đúng lockfile sẽ dùng trên CI
Trước khi push, chạy pnpm install --frozen-lockfile local một lần để mô phỏng đúng điều kiện CI, thay vì chỉ tin vào pnpm install thông thường vốn có thể tự sửa lockfile.
Nguồn tham khảo: pnpm workspace docs, Cloudflare Wrangler docs, Astro Cloudflare adapter docs.