Penjaga di Router Aplikasi Next.js: kesalahan server dan klien, peta sumber tanpa PII
Apa yang harus terjadi
Kesalahan dalam komponen server, Route Handler, Server Action atau di browser masuk ke Sentry dengan tumpukan yang dapat dibaca (nama file dan baris sumber, bukan bundel yang diperkecil), dengan indikasi rilis dan tanpa data pengguna pribadi jika terjadi.
Instalasi
npx @sentry/wizard@latest -i nextjs
Wizard membuat file dan mengedit next.config. Cari tahu apa yang dia lakukan, lalu Anda mendukung mereka:
instrumentation-client.ts(dalam versi SDK yang lebih lama -sentry.client.config.ts) - inisialisasi di browser.sentry.server.config.tsdansentry.edge.config.ts- untuk runtime Node.js dan Edge.instrumentation.tsadalah titik masuk yang dipanggil Next.js saat server dimulai.app/global-error.tsx— batas kesalahan untuk tata letak root.
// instrumentation.ts
import * as Sentry from "@sentry/nextjs";
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") await import("./sentry.server.config");
if (process.env.NEXT_RUNTIME === "edge") await import("./sentry.edge.config");
}
export const onRequestError = Sentry.captureRequestError;onRequestError adalah hook Next.js 15 yang dipanggil saat kesalahan rendering di Route Handler dan Tindakan Server. Tanpa baris ini, kesalahan server sering kali tidak mencapai Sentry: Next.js mencegatnya sendiri dan menampilkan halaman kesalahan kepada pengguna.
Konfigurasi server tanpa PII
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.APP_ENV ?? "production",
release: process.env.SENTRY_RELEASE,
sendDefaultPii: false,
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request) {
delete event.request.cookies;
delete event.request.data;
if (event.request.headers) {
delete event.request.headers.authorization;
delete event.request.headers.cookie;
}
}
return event;
},
});sendDefaultPii: false(ini adalah default, tapi eksplisit lebih baik) - SDK tidak melampirkan alamat IP, cookie, dan header data pengguna.beforeSend- baris terakhir: menghapus apa yang dapat diperoleh melalui integrasi atau konteks Anda sendiri. Isi permintaan (request.data) sangat berbahaya: berisi kata sandi dari formulir login dan data pembayaran.- Tentukan pengguna hanya dengan pengidentifikasi:
Sentry.setUser({ id: user.id }). Email dan nama dalam peristiwa kesalahan tidak diperlukan untuk debugging, tetapi disimpan oleh pihak ketiga. tracesSampleRate: 0.1- 10% permintaan penelusuran kinerja. Nilai produksi 1,0 akan cepat menghabiskan kuota.
Periksa juga teks kesalahan. `throw new Error(Pengguna ${email} tidak ditemukan) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` tidak akan menghentikannya.
Pemutaran Ulang Klien dan Sesi
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0.2,
integrations: [Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })],
});Putar ulang menulis DOM halaman. maskAllText dan blockAllMedia diaktifkan secara default - jangan menonaktifkannya tanpa memastikan bahwa halaman tersebut tidak berisi informasi pribadi. Merekam hanya sesi yang gagal (replaysOnErrorSampleRate) memberikan konteks untuk debugging tanpa terus-menerus memantau pengguna.
DSN di browser pada dasarnya bersifat publik: hanya memungkinkan Anda mengirim acara. Batasi domain yang diperbolehkan di pengaturan proyek Sentry (Allowed Domains) agar situs orang lain tidak menyumbat proyek Anda.
Sumber peta
// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = { /* ... */ };
export default withSentryConfig(nextConfig, {
org: "my-org",
project: "web",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: !process.env.CI,
widenClientFileUpload: true,
sourcemaps: { deleteSourcemapsAfterUpload: true },
});Selama next build plugin memuat peta sumber ke Sentry. deleteSourcemapsAfterUpload menghapus file .map dari build setelah diunggah sehingga kode sumber tidak dibagikan kepada semua orang di situs Anda. Periksa setelah penerapan: permintaan ke .js.map mana pun dari /_next/static/chunks/ akan menghasilkan 404.
SENTRY_AUTH_TOKEN adalah rahasia dengan izin menulis ke proyek. Ini hanya diperlukan di CI pada tahap pembuatan, bukan saat runtime dan bukan variabel dengan awalan NEXT_PUBLIC_.
Diagnostik
- Tumpukan diperkecil. Peta sumber tidak dimuat atau rilis acara tidak bersamaan dengan rilis unduhan. Perintah
sentry-cli sourcemaps explain <event_id>menjelaskan mengapa peristiwa tertentu tidak disimbolkan. - Server error tidak muncul. Tidak ada
onRequestErrordiinstrumentation.ts, atau file tidak ada di root proyek (jika adasrc/- di dalamsrc/). - Kesalahan browser tidak terjadi pada beberapa pengguna. Pemblokir iklan memotong permintaan ke Sentry. Opsi
tunnelRoute: "/monitoring"diwithSentryConfigakan memproksi peristiwa melalui domain Anda. Jika situs memiliki CSP yang ketat, tambahkan domain penerima keconnect-src. - Tidak ada yang datang sama sekali. Aktifkan sementara
debug: truediSentry.initdan lihat log server dan konsol browser.
Kebisingan dan kuota
Tidak setiap kesalahan layak untuk diperjuangkan. Saring yang diharapkan: permintaan dibatalkan, kesalahan ekstensi browser, 404 dari bot. Gunakan ignoreErrors untuk pesan yang dikenal dan denyUrls untuk skrip ekstensi. Sebuah proyek di mana terdapat ribuan kesalahan identik yang tidak penting setiap hari mengajarkan tim untuk tidak melihat Sentry sama sekali.
Saat Sentry mubazir
Untuk layanan internal kecil, log terstruktur dengan level error dan peringatan untuk nomornya mungkin sudah cukup. Penjaga terbayar ketika ada JavaScript sisi klien, banyak pengguna dan Anda perlu mengelompokkan kesalahan dan melihat rilis mana yang menyebabkannya.