Xử Lý Sự Cố: Browser

Sửa các vấn đề phổ biến với panel trình duyệt nhúng.

App Local Không Load

Triệu chứng: bạn điều hướng đến http://localhost:3000 trong panel trình duyệt nhưng thấy lỗi kết nối hoặc trang trống.

Cách sửa:

  • Đảm bảo dev server thực sự đang chạy. Kiểm tra terminal — tìm thông báo khởi động (ví dụ ready on http://localhost:3000 từ Next.js, hoặc Local: http://localhost:5173/ từ Vite). Nếu server chưa chạy, khởi động nó bằng lệnh thông thường (npm run dev, yarn dev, v.v.).
  • Thử 127.0.0.1 thay vì localhost. Một số hệ thống phân giải localhost khác với mong đợi. Thay localhost bằng 127.0.0.1 trong thanh URL — ví dụ http://127.0.0.1:3000.
  • Content-Security-Policy headers. Nếu app của bạn đặt CSP headers nghiêm ngặt ngăn embedding trong webview, panel trình duyệt sẽ từ chối hiển thị nó. Trong chế độ development, bạn có thể nới lỏng các headers này. Ví dụ, trong Next.js bạn có thể xóa hoặc nới lỏng directive frame-ancestors trong next.config.js chỉ cho local dev.

Chiều Cao Panel Trình duyệt Bị Thu Gọn

Triệu chứng: panel trình duyệt co lại thành dải mỏng và bạn không thể thấy app.

Cách sửa: kéo panel divider (thanh mỏng giữa panel trình duyệt và panel phía trên hoặc dưới nó) để resize trình duyệt. Click và kéo nó lên trên để dành nhiều không gian dọc hơn cho trình duyệt.

Nếu bạn muốn trình duyệt chiếm nhiều không gian nhất có thể, dùng chế độ fullscreen: nhấn Cmd+Shift+F (hoặc Ctrl+Shift+F trên Windows/Linux) để mở rộng panel trình duyệt lấp đầy cửa sổ. Nhấn cùng shortcut để quay lại layout bình thường.

Video Hoặc Audio Không Phát

Panel trình duyệt nhúng không hỗ trợ tất cả media codecs. Một số định dạng video hoặc audio streams có thể không phát được trong panel.

Cách sửa: click chuột phải bất kỳ đâu trong panel trình duyệt và chọn Open in External Browser. Điều này mở URL hiện tại trong trình duyệt mặc định của hệ thống (Safari, Chrome, Firefox, v.v.), nơi có hỗ trợ codec đầy đủ. Dùng cho trang nặng media, video players, hoặc bất kỳ thứ gì yêu cầu browser plugins.

Trang Hiển Thị Trắng / Trống

Trang trắng trống thường nghĩa là trang đã load nhưng có lỗi JavaScript trước khi bất kỳ nội dung nào hiển thị.

Cách sửa:

  1. Click nút DevTools trong thanh công cụ panel trình duyệt (icon cờ lê hoặc </>).
  2. Mở tab Console.
  3. Tìm thông báo lỗi màu đỏ.

Nguyên nhân phổ biến nhất cho local development là lỗi CORS — frontend của bạn đang request đến local API, và API từ chối nó vì request đến từ origin webview thay vì localhost. Để sửa điều này trong development, cấu hình API server cho phép tất cả origins:

  • Express / Node: thêm app.use(cors()) với package cors.
  • FastAPI: thêm CORSMiddleware với allow_origins=["*"] cho dev.
  • Next.js API routes: thêm Access-Control-Allow-Origin: * vào response headers trong route handler.

Nhớ giới hạn origins lại trước khi deploy lên production.