Bối cảnh
Blog này build bằng Astro (output: "server") qua adapter @astrojs/cloudflare, deploy lên Cloudflare Workers, quản lý package bằng pnpm. Lần đầu chạy CI/CD để deploy, build fail liên tiếp hai lần vì hai nguyên nhân khác hẳn nhau.
Lỗi thứ nhất: pnpm workspace thiếu trường packages
pnpm 10.x bắt buộc pnpm-workspace.yaml phải khai báo tường minh trường packages, kể cả khi repo chỉ có một package duy nhất ở root — hành vi này khác với các bản pnpm cũ hơn, vốn có thể suy luận ngầm. Thiếu trường này khiến bước cài dependency trên CI thất bại ngay từ đầu, trước khi build kịp chạy.
Cách xử lý: thêm packages: ["."] vào pnpm-workspace.yaml. Đơn giản, nhưng dễ bỏ sót nếu chỉ test local với bản pnpm cũ hơn version dùng trên CI.
Lỗi thứ hai: wrangler không nằm trong devDependencies trực tiếp
Lỗi tiếp theo xuất hiện ở bước deploy: script gọi wrangler nhưng package này chỉ có mặt gián tiếp qua dependency của @astrojs/cloudflare, không được khai báo trực tiếp trong package.json. Một số môi trường CI cài đặt "sạch" (--frozen-lockfile hoặc tương đương) không đảm bảo binary của dependency gián tiếp có sẵn trên PATH giống hệt máy dev.
Cách xử lý: thêm thẳng wrangler vào devDependencies. Về nguyên tắc chung: bất kỳ CLI nào script build/deploy gọi trực tiếp nên là dependency trực tiếp, không dựa vào việc nó "tình cờ" có mặt qua một package khác.
Một cải thiện đi kèm: bỏ bước index Pagefind khỏi build chính
Cùng đợt dọn build, tôi cũng bỏ bước index tìm kiếm (Pagefind) ra khỏi script build mặc định — tính năng search đang tắt tạm thời (xem CLAUDE.md, mục "Tính năng đang tắt"), nên chạy index mỗi lần build là phí thời gian CI không cần thiết.
Bài học
Cả hai lỗi đều không phải do logic ứng dụng sai — chúng nằm ở lớp cấu hình package manager và deploy tooling, thứ rất dễ bị bỏ qua khi chỉ test bằng astro dev local. Nguồn tham khảo: pnpm workspace docs, Wrangler docs — Cloudflare.