Men-debug Node.js

Panduan ini akan membantu Anda memulai men-debug aplikasi dan skrip Node.js Anda.

 

Enable Inspector

Saat dimulai dengan sakelar --inspect, proses Node.js mendengarkan klien debugging. Secara default, klien akan mendengarkan di host dan port 127.0.0.1:9229. Setiap proses juga diberi UUID yang unik.

Klien Inspektur harus mengetahui dan menentukan alamat host, port, dan UUID untuk terhubung. URL lengkap akan terlihat seperti ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.

Node.js juga akan mulai mendengarkan pesan debugging jika menerima sinyal SIGUSR1. (SIGUSR1 tidak tersedia di Windows.) Di Node.js 7 dan versi sebelumnya, ini akan mengaktifkan API Debugger lama. Di Node.js 8 dan versi yang lebih baru, ini akan mengaktifkan API Inspektur. 

 

Implikasi Keamanan

Karena debugger memiliki akses penuh ke lingkungan eksekusi Node.js, pelaku jahat yang dapat terhubung ke port ini mungkin dapat mengeksekusi kode arbitrer atas nama proses Node.js. Penting untuk memahami implikasi keamanan dari mengekspos port debugger di jaringan publik dan privat.

 

Mengekspos port debug ke publik tidaklah aman

Jika debugger terikat ke alamat IP publik, atau ke 0.0.0.0, semua klien yang dapat mencapai alamat IP Anda akan dapat terhubung ke debugger tanpa batasan apa pun dan akan dapat menjalankan kode arbitrer.

Secara default node --inspect terikat ke 127.0.0.1. Anda secara eksplisit perlu memberikan alamat IP publik atau 0.0.0.0, dll., jika Anda bermaksud mengizinkan koneksi eksternal ke debugger. Melakukan hal itu dapat membuat Anda terpapar pada ancaman keamanan yang berpotensi signifikan. Kami sarankan Anda memastikan firewall dan kontrol akses yang sesuai tersedia untuk mencegah paparan keamanan.

Lihat bagian 'Mengaktifkan skenario debugging jarak jauh' untuk beberapa saran tentang cara mengizinkan klien debugger jarak jauh untuk terhubung dengan aman.

 

Aplikasi lokal memiliki akses penuh ke inspector

Bahkan jika Anda mengikat port inspektur ke 127.0.0.1 (default), semua aplikasi yang berjalan secara lokal di mesin Anda akan memiliki akses tanpa batas. Hal ini dirancang untuk memungkinkan debugger lokal dapat terhubung dengan mudah.
 

Browser, WebSockets, dan kebijakan asal yang sama

Situs web yang dibuka di peramban web dapat membuat permintaan WebSocket dan HTTP di bawah model keamanan peramban. Koneksi HTTP awal diperlukan untuk mendapatkan ID sesi debugger yang unik. Kebijakan asal yang sama mencegah situs web dapat membuat koneksi HTTP ini. Untuk keamanan tambahan terhadap serangan pengikatan ulang DNS, Node.js memverifikasi bahwa header 'Host' untuk koneksi tersebut menentukan alamat IP atau localhost secara tepat.

Kebijakan keamanan ini melarang koneksi ke server debug jarak jauh dengan menentukan nama host. Anda dapat mengatasi pembatasan ini dengan menentukan alamat IP atau dengan menggunakan terowongan ssh seperti yang dijelaskan di bawah ini.

 

Inspector Clients

Debugger CLI minimal tersedia dengan node inspect myscript.js. Beberapa alat komersial dan sumber terbuka juga dapat terhubung ke Inspektur Node.js.
Chrome DevTools 55+, Microsoft Edge

• Opsi 1: Buka chrome://inspect di browser berbasis Chromium atau edge://inspect di Edge. Klik tombol Konfigurasi dan pastikan host dan port target Anda tercantum.
• Opsi 2: Salin devtoolsFrontendUrl dari output /json/list (lihat di atas) atau teks petunjuk --inspect dan tempel ke Chrome.

 See https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com for more information.

 

Visual Studio Code 1.10+

Di panel Debug, klik ikon pengaturan untuk membuka .vscode/launch.json. Pilih "Node.js" untuk pengaturan awal.

Lihat https://github.com/microsoft/vscode untuk informasi lebih lanjut.

 

Visual Studio 2017+

Pilih "Debug > Start Debugging" dari menu atau tekan F5.

Instruksi terperinci.

JetBrains WebStorm dan IDE JetBrains lainnya

Buat konfigurasi debug Node.js baru dan tekan Debug. --inspect akan digunakan secara default untuk Node.js 7+. Untuk menonaktifkan hapus centang js.debugger.node.use.inspect di IDE Registry. Untuk mempelajari lebih lanjut tentang menjalankan dan men-debug Node.js di WebStorm dan IDE JetBrains lainnya, lihat bantuan daring WebStorm.

 

chrome-remote-interface

Library untuk memudahkan koneksi ke titik akhir Inspector Protocol.

Lihat https://github.com/cyrus-and/chrome-remote-interface untuk informasi lebih lanjut.
 

Gitpod

Mulai konfigurasi debug Node.js dari tampilan Debug atau tekan F5. Instruksi terperinci

Lihat https://www.gitpod.io untuk informasi lebih lanjut.
 

Eclipse IDE dengan ekstensi Eclipse Wild Web Developer

Dari file .js, pilih "Debug As... > Node program", atau
Buat Konfigurasi Debug untuk melampirkan debugger ke aplikasi Node.js yang sedang berjalan (sudah dimulai dengan --inspect).

 lihat https://eclipse.org/eclipseide untuk informasi lebih banyak.

 

Command-line options

• --inspect Mengaktifkan agen inspektur; Mendengarkan pada alamat dan port default (127.0.0.1:9229)
• --inspect=[host:port] Mengaktifkan agen inspektur; Mengikat ke alamat atau nama host host (default: 127.0.0.1); Mendengarkan pada port port (default: 9229)
• --inspect-brk Mengaktifkan agen inspektur; Mendengarkan pada alamat dan port default (127.0.0.1:9229); Berhenti sebelum kode pengguna dimulai
• --inspect-brk=[host:port] Mengaktifkan agen inspektur; Mengikat ke alamat atau nama host host (default: 127.0.0.1); Mendengarkan pada port port (default: 9229); Berhenti sebelum kode pengguna dimulai
• --inspect-wait Mengaktifkan agen inspektur; Mendengarkan pada alamat dan port default (127.0.0.1:9229); Tunggu debugger terpasang.
• --inspect-wait=[host:port] Aktifkan agen pemeriksa; Ikat ke alamat atau nama host host (default: 127.0.0.1); Dengarkan di port port (default: 9229); Tunggu debugger terpasang.
• node inspect script.js Memunculkan proses anak untuk menjalankan skrip pengguna di bawah flag --inspect; dan gunakan proses utama untuk menjalankan debugger CLI.
• node inspect --port=xxxx script.js Memunculkan proses anak untuk menjalankan skrip pengguna di bawah flag --inspect; dan gunakan proses utama untuk menjalankan debugger CLI. Dengarkan di port port (default: 9229)

 

Mengaktifkan skenario debugging jarak jauh

Kami sarankan agar debugger tidak pernah mendengarkan alamat IP publik. Jika Anda perlu mengizinkan koneksi debugging jarak jauh, kami sarankan untuk menggunakan terowongan ssh. Kami memberikan contoh berikut hanya untuk tujuan ilustrasi. Harap pahami risiko keamanan dari mengizinkan akses jarak jauh ke layanan istimewa sebelum melanjutkan.

Misalnya Anda menjalankan Node.js pada mesin jarak jauh, remote.example.com, yang ingin Anda debug. Pada mesin tersebut, Anda harus memulai proses node dengan inspektur yang hanya mendengarkan localhost (default).

node --inspect server.js
 

Sekarang, pada komputer lokal tempat Anda ingin memulai koneksi klien debug, Anda dapat menyiapkan terowongan ssh:

ssh -L 9221:localhost:9229 user@remote.example.com
 

Ini memulai sesi terowongan ssh tempat koneksi ke port 9221 pada mesin lokal Anda akan diteruskan ke port 9229 pada remote.example.com. Anda sekarang dapat melampirkan debugger seperti Chrome DevTools atau Visual Studio Code ke localhost:9221, yang seharusnya dapat men-debug seolah-olah aplikasi Node.js berjalan secara lokal.
 

Debugger Lama

Debugger lama telah ditinggalkan sejak Node.js 7.7.0. Gunakan --inspect dan Inspector sebagai gantinya.

Saat dimulai dengan sakelar --debug atau --debug-brk pada versi 7 dan sebelumnya, Node.js mendengarkan perintah debugging yang ditetapkan oleh Protokol Debugging V8 yang dihentikan pada port TCP, secara default 5858. Setiap klien debugger yang menggunakan protokol ini dapat terhubung dan men-debug proses yang sedang berjalan; beberapa yang populer tercantum di bawah ini.

Protokol Debugging V8 tidak lagi dikelola atau didokumentasikan. 

 

Debugger Bawaan

Jalankan skrip debug node script_name.js untuk memulai skrip Anda di bawah debugger baris perintah bawaan. Skrip Anda dimulai dalam proses Node.js lain yang dimulai dengan opsi --debug-brk, dan proses Node.js awal menjalankan skrip _debugger.js dan terhubung ke target Anda. Lihat dokumen untuk informasi selengkapnya.
 

node-inspector

Debug aplikasi Node.js Anda dengan Chrome DevTools dengan menggunakan proses perantara yang menerjemahkan Protokol Inspektur yang digunakan di Chromium ke protokol Debugger V8 yang digunakan di Node.js. Lihat https://github.com/node-inspector/node-inspector untuk informasi selengkapnya.