Khắc phục sự cố
Trang này chỉ liệt kê các tình huống đã gặp thật khi chạy dự án trong một bản clone sạch, hoặc suy ra trực tiếp từ code (có ghi rõ). Nó không bao gồm lỗi giả định. Mỗi mục nêu dấu hiệu, nguyên nhân và cách xử lý.
Đã gặp thật
Trang /login báo Google OAuth components must be used within GoogleOAuthProvider
- Dấu hiệu: console máy chủ ghi lỗi này khi mở
/login; HTTP vẫn 200 nhưng HTML chứa thông báo lỗi. - Nguyên nhân: chưa đặt
NEXT_PUBLIC_GOOGLE_CLIENT_ID, nên ứng dụng không dựng Google provider, trong khi nút đăng nhập Google cần nó. - Xử lý: tạo
.env.localcó biến này rồi khởi động lạinpm run dev. Đã thử với giá trị giả có dạngxxx.apps.googleusercontent.comvà lỗi biến mất. Xem Biến môi trường.
Dòng NEXT_PUBLIC_GOOGLE_CLIENT_ID is not defined xuất hiện ở mỗi trang
- Nguyên nhân: cùng nguyên nhân trên;
google-oauth-provider.tsxghiconsole.errormỗi lần render khi thiếu biến. - Xử lý: đặt biến. Nếu bạn không dùng đăng nhập Google, có thể bỏ qua dòng này ở các trang khác ngoài
/login.
Sitemap chỉ có ba địa chỉ
- Dấu hiệu:
/sitemap.xmltrả 200 nhưng chỉ có/,/jobs,/companies. - Nguyên nhân: không kết nối được backend. Hàm lấy dữ liệu trả
nullmà không báo lỗi nên sitemap bỏ qua việc làm và công ty. - Xử lý: chạy backend ở
localhost:8081. Xem Rendering và SEO.
Robots và sitemap trỏ về localhost:3000
- Nguyên nhân: chưa đặt
NEXT_PUBLIC_SITE_URL, nên dùng giá trị dự phòng. - Xử lý: đặt biến này. Đã kiểm tra: đặt xong thì
Host,Sitemapvà<loc>đổi theo.
next build không báo lỗi lint nhưng npm run lint có cảnh báo
- Nguyên nhân:
eslint.ignoreDuringBuilds: truetrongnext.config.ts; build inSkipping linting. - Xử lý: chạy
npm run lintriêng. Hiện có 0 lỗi, 16 cảnh báo.
Cảnh báo deprecated và npm audit khi npm ci
- Dấu hiệu: nhiều dòng
npm warn deprecated, và thông báo 44 lỗ hổng. - Ghi chú: không làm lệnh thất bại (mã thoát 0). Đây là thông tin về cây phụ thuộc, không phải lỗi cài đặt. Chưa có đánh giá về mức ảnh hưởng.
Chạy trên Node.js khác .nvmrc
- Ghi chú: các lệnh
npm ci,tsc,lint,test,build,devđều chạy được trên Node.js v22.23.2 dù.nvmrcghi20.19.5. Nếu gặp lỗi khó hiểu ở môi trường khác, hãy thửnvm useđể về đúng phiên bản.
/api/proxy-image trả 400
- Nguyên nhân: thiếu tham số
url; phản hồi là{"error":"Image URL is required"}. Route này chỉ được trang xuất PDF gọi.
Suy ra từ code, chưa chạy thử
/api/proxy-image trả 403 Invalid image URL
- Nguyên nhân: máy chủ ảnh không nằm trong danh sách cho phép. Chỉ
localhost:8081và giá trịNEXT_PUBLIC_API_URLđược chấp nhận; giá trị có đường dẫn như/api/v1sẽ không khớp. Xem Biến môi trường.
Đổi backend nhưng ứng dụng vẫn gọi localhost:8081
- Nguyên nhân:
API_BASE_URLđược viết cứng, không đọc biến môi trường. - Xử lý: sửa
src/shared/constants/constant.ts, đồng thờinext.config.ts(images.remotePatterns) và danh sách trongproxy-image/route.tsnếu dùng ảnh từ backend đó.
Chưa kiểm tra
- Build và chạy khi không có mạng (phông Roboto được tải từ Google Fonts).
- Giao diện cuối cùng của các trang trong trình duyệt khi không có backend.
- Đăng nhập Google với Client ID thật.
Source code liên quan
src/components/google-oauth-provider.tsx: provider Googlesrc/components/auth/social-auth-buttons.tsx: nút đăng nhập Googlesrc/shared/constants/seo.ts: giá trị dự phòng của địa chỉ sitesrc/app/sitemap.ts: sitemapnext.config.ts:ignoreDuringBuildsvà máy chủ ảnhsrc/app/api/proxy-image/route.ts: proxy ảnh
