Source map

JavaScript trên production đã được thu nhỏ, nên stack trace gốc chỉ tới index-4f2a1c.js:1:48213. Khi source map được tải lên node, Belvador hiện đúng file, dòng, hàm và đoạn code xung quanh. Source map nằm trên node của bạn; không bao giờ được công khai cùng website.

Cách hoạt động#

1. Khi build, sentry-cli sourcemaps inject ghi một Debug ID vào mỗi file JavaScript và file .map của nó.

2. Bạn triển khai các file JavaScript đã được ghi Debug ID — không kèm file .map.

3. CI tải các file .map lên node bằng một token upload.

4. Khi có lỗi, SDK đã gắn Debug ID của các file trong stack. Node tìm source map khớp và khôi phục frame gốc.

Frame không khôi phục được sẽ có nhãn Bản thu nhỏ trong stack trace.

Trước khi bắt đầu#

• Một project và thư mục kết quả build, ví dụ ./dist.

• Cùng một giá trị release trong init của SDK và khi tải lên, ví dụ mã commit.

• Một token upload: Cài đặt project → Token upload → Token upload mới. Token chỉ hiện một lần, có hạn 365 ngày, chỉ dùng cho project này — tải source map (tối đa 60 request mỗi giờ) và ghi release và deploy (600 mỗi giờ). Lưu thành biến bí mật trong CI tên BELVADOR_UPLOAD_TOKEN. Tạo và thu hồi token sẽ hỏi mã xác thực của bạn.

Cách A — sentry-cli (khuyên dùng)#

Edge của Belvador nhận API tải lên của sentry-cli. Chạy đoạn này trong CI sau bước build, trước khi triển khai:

export SENTRY_URL=https://edge.belvador.devexport SENTRY_AUTH_TOKEN="$BELVADOR_UPLOAD_TOKEN"export SENTRY_ORG=belvador SENTRY_PROJECT=<project-slug>npx @sentry/cli sourcemaps inject ./distnpx @sentry/cli sourcemaps upload --release "$RELEASE" ./dist

Cài đặt project → Token upload hiện đúng các lệnh này với địa chỉ project của bạn đã điền sẵn. $RELEASE phải là giá trị bạn truyền làm release trong init.

Cách B — tải lên tarball#

Không dùng lệnh upload của sentry-cli: ghi Debug ID, đóng gói source map rồi gửi lên:

npx @sentry/cli sourcemaps inject ./dist(cd dist && find . -name '*.map' | tar -czf ../sourcemaps.tgz -T -)curl -fsS -X POST "https://edge.belvador.dev/n/<node-id>/upload/sourcemaps?project=<project-id>&release=$RELEASE" \  -H "Authorization: Bearer $BELVADOR_UPLOAD_TOKEN" \  --data-binary @sourcemaps.tgz

Ứng dụng hiện lệnh này với node và project của bạn đã điền sẵn.

Plugin của công cụ build#

Plugin của Sentry cho công cụ build (Vite, webpack, esbuild, Rollup) dùng cùng API tải lên với sentry-cli, nên có thể tải lên Belvador khi trỏ tới https://edge.belvador.dev với token upload của bạn. Edge đã có sẵn hai cách sentry-cli và tarball trong bài này; với plugin, hãy kiểm tra kết quả bằng một lỗi thử.

Giới hạn#

Đừng triển khai file .map#

Bỏ file .map khỏi bản triển khai, hoặc cấu hình hosting không phục vụ chúng. Ai tải được các file này đều đọc được mã nguồn gốc của bạn.

Kiểm tra#

1. Build, ghi Debug ID, tải lên và triển khai một release.

2. Tạo một lỗi thử trong release đó.

3. Mở issue: frame hiện tên file và dòng gốc, không còn nhãn Bản thu nhỏ.

Nếu frame vẫn ở dạng thu nhỏ:

• release trong init khác với giá trị đã tải lên;

• JavaScript đã triển khai không phải bản đã ghi Debug ID — inject phải chạy trước khi triển khai, trên đúng các file đó;

• việc tải lên thất bại: xem log CI có 401 (token sai hoặc đã thu hồi) hoặc 413 (file quá lớn);

• token đã hết hạn sau 365 ngày.