Cara Setting Proxy di Node.js: fetch, HTTP_PROXY & NO_PROXY

Diperbarui 05 Oct 2026

Kamu sudah memasang HTTP_PROXY di server, tetapi aplikasi Node.js masih terlihat keluar menggunakan IP asli? Atau fetch() berjalan normal saat koneksi langsung, lalu gagal begitu aplikasi dipindahkan ke jaringan kantor yang mewajibkan proxy? Masalah seperti ini cukup sering terjadi karena konfigurasi proxy di Node.js tidak selalu sama dengan pengaturan proxy pada browser atau sistem operasi.

Pada Node.js modern, dukungan proxy sudah semakin praktis. Node dapat membaca HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY, lalu menerapkannya pada request dari fetch(), http, atau https jika dukungan environment proxy diaktifkan.

Artikel ini fokus pada penggunaan HTTP dan HTTPS proxy di aplikasi Node.js. Mulai dari konfigurasi paling sederhana, pengecekan IP, autentikasi, bypass domain, file .env, sampai troubleshooting jika proxy tidak terbaca.

Kalau format seperti IP:PORT masih terasa asing, baca dulu panduan apa itu IP proxy supaya contoh di bawah lebih mudah diikuti.

Apa yang Dibutuhkan Sebelum Setting Proxy di Node.js?

Untuk mulai menggunakan proxy, minimal kamu membutuhkan alamat server dan port. Beberapa proxy juga memakai username dan password.

Data	Fungsi	Contoh
Host / IP	Alamat server proxy.	`203.0.113.20`
Port	Port layanan proxy.	`8080`
Protokol	Menentukan skema URL proxy.	HTTP atau HTTPS
Username	Digunakan jika proxy membutuhkan autentikasi.	`user123`
Password	Password autentikasi proxy.	`pass123`

Format proxy sederhana biasanya seperti:

http://203.0.113.20:8080

Sementara proxy yang membutuhkan autentikasi dapat memiliki format seperti:

http://user123:[email protected]:8080

Alamat di artikel ini hanya contoh dokumentasi. Ganti dengan endpoint proxy yang benar-benar kamu gunakan.

Cek Versi Node.js Terlebih Dahulu

Sebelum mengikuti konfigurasi built-in proxy, cek versi Node.js yang terpasang.

node --version

Dukungan proxy bawaan Node.js berkembang cukup cepat. Dokumentasi Node.js saat ini mencatat built-in proxy support tersedia pada cabang modern Node, termasuk dukungan HTTP_PROXY, HTTPS_PROXY, NO_PROXY, dan flag --use-env-proxy.

Dokumentasi resminya dapat dilihat di Node.js HTTP documentation.

Kalau menggunakan Node.js versi lama: jangan langsung menganggap contoh environment proxy di artikel ini akan bekerja dengan perilaku yang sama. Cek dokumentasi versi Node yang sedang digunakan atau lakukan upgrade jika project memungkinkan.

Cara Kerja Proxy di Node.js

Tanpa proxy, aplikasi Node membuat koneksi menuju website atau API tujuan secara langsung. Ketika proxy digunakan, request diarahkan terlebih dahulu ke server proxy.

Node.js App
fetch / HTTP

→

Proxy Server
IP + Port

→

API / Website
Tujuan

Dari sisi aplikasi, kode request bisa tetap sederhana. Yang berubah adalah jalur koneksinya.

Kalau ingin memahami posisi proxy dalam jaringan secara lebih mendasar, baca juga artikel cara kerja proxy server.

Cara Setting Proxy Node.js dengan HTTP_PROXY

Salah satu cara paling rapi adalah menggunakan environment variable. Dengan metode ini, alamat proxy tidak harus ditulis langsung di source code.

Pada Linux atau macOS:

export HTTP_PROXY="http://203.0.113.20:8080" export HTTPS_PROXY="http://203.0.113.20:8080" export NODE_USE_ENV_PROXY="1" node app.js

HTTP_PROXY digunakan untuk request HTTP, sedangkan HTTPS_PROXY digunakan ketika destination memakai HTTPS.

Perhatikan satu detail penting: nilai HTTPS_PROXY tidak selalu harus diawali https://. Kalau server yang kamu miliki merupakan HTTP proxy yang menangani koneksi HTTPS, URL proxy tetap dapat berupa http://IP:PORT.

Contoh fetch() Menggunakan Proxy

Buat file app.js:

async function main() { const response = await fetch("https://api.ipify.org?format=json"); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const data = await response.json(); console.log(data); } main().catch(console.error);

Kemudian jalankan dengan environment proxy:

HTTP_PROXY="http://203.0.113.20:8080" \ HTTPS_PROXY="http://203.0.113.20:8080" \ NODE_USE_ENV_PROXY="1" \ node app.js

Jika konfigurasi bekerja, IP yang dikembalikan oleh layanan pengecekan IP seharusnya merupakan IP keluar proxy.

Cara Mengaktifkan Proxy dengan --use-env-proxy

Selain memakai NODE_USE_ENV_PROXY=1, Node.js juga menyediakan flag command line --use-env-proxy.

export HTTP_PROXY="http://203.0.113.20:8080" export HTTPS_PROXY="http://203.0.113.20:8080" node --use-env-proxy app.js

Flag tersebut meminta Node membaca konfigurasi proxy dari environment ketika process dimulai.

Dokumentasi resmi Node.js CLI menjelaskan bahwa --use-env-proxy membaca HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY.

NODE_USE_ENV_PROXY atau --use-env-proxy?

Keduanya mempunyai tujuan yang sama: mengaktifkan built-in environment proxy.

Metode	Contoh	Cocok untuk
NODE_USE_ENV_PROXY	`NODE_USE_ENV_PROXY=1 node app.js`	Docker, server, CI/CD, environment configuration.
--use-env-proxy	`node --use-env-proxy app.js`	Menentukan perilaku langsung dari command line.

Kalau aplikasi dijalankan di container atau deployment environment, environment variable biasanya lebih mudah dikelola tanpa mengubah command aplikasi.

Cara Setting Proxy Node.js di Windows PowerShell

Kalau Node.js dijalankan dari PowerShell, format environment variable berbeda dari Bash.

$env:HTTP_PROXY="http://203.0.113.20:8080" $env:HTTPS_PROXY="http://203.0.113.20:8080" $env:NODE_USE_ENV_PROXY="1" node app.js

Untuk memastikan nilainya sudah masuk:

echo $env:HTTP_PROXY echo $env:HTTPS_PROXY echo $env:NODE_USE_ENV_PROXY

Kalau output kosong, berarti environment variable belum aktif pada sesi PowerShell tersebut.

Cara Mengecek Proxy Node.js Benar-Benar Aktif

Jangan hanya melihat apakah script tidak error. Cara yang lebih jelas adalah membandingkan IP publik sebelum dan sesudah proxy aktif.

Pertama jalankan tanpa proxy:

node app.js

Catat IP yang muncul. Setelah itu jalankan kembali menggunakan proxy.

HTTP_PROXY="http://203.0.113.20:8080" \ HTTPS_PROXY="http://203.0.113.20:8080" \ NODE_USE_ENV_PROXY="1" \ node app.js

Kalau IP berubah menjadi IP keluar proxy, konfigurasi dasar sudah berjalan.

Cari Proxy untuk Testing Aplikasi Node.js?

GudangProxy menyediakan daftar proxy gratis yang dapat difilter berdasarkan negara, protokol, tingkat anonimitas, dan status koneksi. Kamu bisa memilih endpoint lalu mengujinya langsung melalui fetch atau HTTP client Node.js.

Lihat Daftar Proxy Gratis →

Apa Fungsi HTTPS_PROXY?

HTTPS_PROXY menentukan proxy yang digunakan untuk request dengan destination HTTPS.

Contohnya ketika kode menjalankan:

fetch("https://example.com")

Node dapat menggunakan nilai HTTPS_PROXY jika environment proxy sudah diaktifkan.

Misalnya:

export HTTPS_PROXY="http://203.0.113.20:8080" export NODE_USE_ENV_PROXY="1" node app.js

HTTP proxy tersebut dapat membuat tunnel menuju server HTTPS. Ini berbeda dari mengubah website tujuan menjadi HTTP.

Apa Fungsi NO_PROXY di Node.js?

Tidak semua koneksi sebaiknya dilewatkan melalui proxy. Service lokal, API internal, database gateway, atau development server sering kali justru harus diakses secara langsung.

Di sinilah NO_PROXY berguna.

export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

Dengan konfigurasi tersebut, host yang cocok dengan daftar NO_PROXY akan melewati proxy.

Contoh NO_PROXY untuk Localhost

HTTP_PROXY="http://203.0.113.20:8080" HTTPS_PROXY="http://203.0.113.20:8080" NO_PROXY="localhost,127.0.0.1"

Request menuju internet menggunakan proxy, tetapi koneksi ke localhost dan 127.0.0.1 tetap langsung.

Bypass Satu Domain

NO_PROXY="api.internal.example.com"

Bypass Subdomain

NO_PROXY=".example.com"

Pada implementasi Node.js modern, NO_PROXY juga mendukung beberapa pola lain seperti hostname, suffix domain, wildcard, alamat IP, dan hostname yang disertai port.

HTTP_PROXY vs http_proxy, Mana yang Digunakan?

Node.js mendukung nama environment variable huruf besar maupun kecil.

Variabel	Fungsi
HTTP_PROXY / http_proxy	Proxy untuk HTTP.
HTTPS_PROXY / https_proxy	Proxy untuk HTTPS.
NO_PROXY / no_proxy	Daftar destination yang tidak melalui proxy.

Ada detail yang mudah terlewat: jika versi huruf besar dan kecil sama-sama diisi, dokumentasi Node.js saat ini memberikan prioritas ke varian huruf kecil.

Karena itu sebaiknya jangan mengatur dua nilai berbeda seperti ini:

HTTP_PROXY="http://proxy-a:8080" http_proxy="http://proxy-b:8080"

Gunakan satu standar agar debugging tidak membingungkan.

Setting Proxy Node.js dari File .env

Untuk project development, konfigurasi sering disimpan di file environment.

Contoh .env:

HTTP_PROXY=http://203.0.113.20:8080 HTTPS_PROXY=http://203.0.113.20:8080 NO_PROXY=localhost,127.0.0.1 NODE_USE_ENV_PROXY=1

Pada Node.js yang mendukung --env-file, jalankan:

node --env-file ./.env app.js

Dengan begitu konfigurasi networking tidak perlu ditulis langsung di file JavaScript.

Jangan commit file .env yang berisi username dan password proxy ke repository publik. Gunakan environment deployment atau secret manager jika credential memang sensitif.

Cara Menggunakan Proxy dengan Username dan Password

Jika proxy menggunakan autentikasi, credential dapat dimasukkan ke URL proxy.

export HTTPS_PROXY="http://user123:[email protected]:8080" export NODE_USE_ENV_PROXY="1" node app.js

Format dasarnya:

http://username:password@proxy-host:port

Kalau username atau password salah, proxy dapat menolak koneksi dengan status seperti 407 Proxy Authentication Required.

Untuk aplikasi produksi, hindari menaruh password secara hardcode di source code JavaScript.

Mengaktifkan Proxy dari Dalam Kode Node.js

Pada Node.js modern tersedia http.setGlobalProxyFromEnv(). Fungsi ini dapat mengaktifkan konfigurasi proxy secara global pada runtime.

import http from "node:http"; http.setGlobalProxyFromEnv({ http_proxy: "http://203.0.113.20:8080", https_proxy: "http://203.0.113.20:8080", no_proxy: "localhost,127.0.0.1" }); const response = await fetch("https://api.ipify.org?format=json"); console.log(await response.json());

Metode ini berguna ketika konfigurasi ingin dibuat dari JavaScript, bukan hanya ketika process pertama kali dijalankan.

Namun ada satu konsekuensi penting: fungsi tersebut mengubah konfigurasi global. Dokumentasi Node.js menyarankan pengaturan dilakukan sebelum request berjalan dan tidak diubah sembarangan ketika request sedang aktif.

Menggunakan Custom Proxy Agent

Kalau kamu tidak ingin semua request menggunakan konfigurasi yang sama, Node.js juga mendukung proxyEnv pada agent.

Contoh untuk modul HTTP:

import http from "node:http"; const agent = new http.Agent({ proxyEnv: { HTTP_PROXY: "http://203.0.113.20:8080" } }); const request = http.request({ hostname: "example.com", port: 80, path: "/", agent }, (response) => { console.log("Status:", response.statusCode); response.resume(); }); request.on("error", console.error); request.end();

Dengan pendekatan ini, konfigurasi proxy dapat dibatasi pada agent tertentu.

fetch dan http.request Tidak Selalu Memakai Konfigurasi yang Sama

Ini bagian yang sering membingungkan developer.

fetch() Node.js menggunakan implementasi berbasis Undici, sedangkan http.request() dan https.request() menggunakan HTTP agent Node.js. Karena itu custom agent yang kamu pasang secara manual pada http.globalAgent tidak otomatis berarti fetch() menggunakan agent tersebut.

Namun ketika built-in proxy support diaktifkan melalui mekanisme resmi Node.js seperti environment proxy atau setGlobalProxyFromEnv(), Node dapat mengatur dukungan proxy untuk jalur request yang didukung.

Dokumentasi Node.js fetch menjelaskan bahwa implementasi fetch Node berbasis Undici.

Bagaimana dengan SOCKS5 di Node.js?

Built-in environment proxy yang dibahas di artikel ini berfokus pada HTTP dan HTTPS proxy. Jangan menganggap URL SOCKS5 otomatis dapat dimasukkan ke HTTP_PROXY lalu bekerja di semua konfigurasi Node.

Kalau endpoint yang kamu punya adalah SOCKS5, gunakan HTTP client, dispatcher, agent, atau library yang memang mendukung SOCKS.

Untuk memahami protokolnya terlebih dahulu, baca panduan SOCKS5 Proxy.

Cara Memberi Timeout pada fetch()

Proxy dapat mati, terlalu lambat, atau tidak merespons. Karena itu sebaiknya request tidak dibiarkan menunggu tanpa batas.

Salah satu pola modern adalah menggunakan AbortSignal.timeout().

try { const response = await fetch( "https://example.com", { signal: AbortSignal.timeout(10000) } ); console.log(response.status); } catch (error) { console.error("Request gagal:", error.message); }

Dengan contoh tersebut, request dibatasi sekitar 10 detik.

Menangani Error Proxy di Node.js

Jangan langsung menganggap semua error berasal dari server tujuan. Saat proxy berada di tengah koneksi, ada satu lapisan tambahan yang juga bisa gagal.

async function requestUrl() { try { const response = await fetch( "https://example.com", { signal: AbortSignal.timeout(10000) } ); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } console.log(await response.text()); } catch (error) { console.error("Request gagal:"); console.error(error); } } requestUrl();

Saat debugging, lihat pesan error lengkap dan jangan hanya mencetak error.message. Property seperti cause sering membantu menunjukkan error jaringan yang lebih spesifik.

Error yang Sering Muncul Saat Proxy Node.js

Gejala	Kemungkinan Penyebab	Yang Perlu Dicek
ECONNREFUSED	Proxy menolak koneksi atau port tidak aktif.	IP, hostname, port, status proxy.
ETIMEDOUT	Proxy terlalu lambat atau tidak dapat dijangkau.	Network route dan latency.
407 Proxy Authentication Required	Proxy membutuhkan autentikasi.	Username dan password.
IP tidak berubah	Environment proxy belum diaktifkan.	NODE_USE_ENV_PROXY atau --use-env-proxy.
Local API gagal	Request internal ikut diarahkan ke proxy.	NO_PROXY.
Certificate error	Masalah CA atau TLS inspection.	Certificate chain dan trust store.
Hanya fetch yang berbeda perilaku	Konfigurasi agent tidak berlaku pada fetch.	Jenis client dan konfigurasi proxy.

Kenapa Environment Proxy Sudah Ada tetapi Node Tidak Memakainya?

Kalau HTTP_PROXY dan HTTPS_PROXY sudah terlihat di Terminal tetapi IP tidak berubah, periksa apakah built-in environment proxy memang sudah diaktifkan.

Cek environment:

env | grep -i proxy

Kemudian cek apakah NODE_USE_ENV_PROXY aktif:

echo $NODE_USE_ENV_PROXY

Kalau tidak ingin memakai environment variable tersebut, jalankan Node dengan:

node --use-env-proxy app.js

Jangan berasumsi bahwa hanya karena sistem operasi memiliki proxy, semua aplikasi Node otomatis mengikuti proxy sistem.

Kenapa localhost Ikut Lewat Proxy?

Biasanya karena NO_PROXY belum diatur.

Misalnya aplikasi Node mengakses:

http://localhost:3000

Jika request tersebut tidak seharusnya melalui proxy, tambahkan:

NO_PROXY="localhost,127.0.0.1"

Untuk microservice atau jaringan internal, daftar bypass bisa ditambah sesuai kebutuhan.

NO_PROXY="localhost,127.0.0.1,.internal.example.com"

Proxy Jalan di cURL tetapi Tidak di Node.js

Kondisi ini cukup normal karena cURL dan Node.js adalah dua aplikasi berbeda. Masing-masing mempunyai cara membaca environment serta implementasi networking sendiri.

Kalau cURL berhasil tetapi Node gagal:

Cek apakah environment variable memang tersedia pada process Node.
Cek apakah built-in proxy support sudah diaktifkan.
Pastikan URL proxy mempunyai skema seperti http://.
Periksa NO_PROXY.
Coba endpoint sederhana untuk mengecek IP.
Periksa apakah proxy membutuhkan autentikasi.

Kamu juga bisa mencetak environment dari Node:

console.log({ HTTP_PROXY: process.env.HTTP_PROXY, HTTPS_PROXY: process.env.HTTPS_PROXY, NO_PROXY: process.env.NO_PROXY, NODE_USE_ENV_PROXY: process.env.NODE_USE_ENV_PROXY });

Jangan tampilkan output seperti ini di log publik jika URL proxy berisi username dan password.

Certificate Error Saat Node.js Menggunakan Proxy

Di jaringan perusahaan, koneksi HTTPS terkadang melewati TLS inspection. Perusahaan dapat menggunakan certificate authority internal untuk menandatangani koneksi yang diperiksa oleh gateway.

Dalam kondisi seperti itu, Node mungkin menghasilkan error certificate jika CA internal belum dipercaya.

Node.js menyediakan beberapa mekanisme untuk menambahkan CA, termasuk penggunaan system CA pada versi yang mendukungnya serta NODE_EXTRA_CA_CERTS.

Contoh:

export NODE_EXTRA_CA_CERTS="/path/to/company-ca.pem" node app.js

Dokumentasi lengkapnya tersedia pada panduan resmi Enterprise Network Configuration Node.js.

Jangan menjadikan NODE_TLS_REJECT_UNAUTHORIZED=0 sebagai solusi normal. Menonaktifkan certificate verification membuat koneksi HTTPS kehilangan validasi TLS yang penting.

Proxy dengan Authentication atau IP Whitelist?

Proxy private biasanya menggunakan salah satu dari dua pendekatan: credential atau IP whitelist.

Metode	Cara Kerja	Konfigurasi Node.js
Username + Password	Client mengirim credential ke proxy.	Masukkan credential pada URL proxy.
IP Whitelist	Server hanya menerima koneksi dari IP tertentu.	Tidak perlu credential jika IP server sudah diizinkan.

Kalau proxy memakai whitelist dan aplikasi dijalankan di cloud server, pastikan public outbound IP server sudah didaftarkan ke penyedia proxy.

Apakah Proxy Node.js Mengubah Seluruh Koneksi Server?

Tidak otomatis. Proxy yang dikonfigurasi untuk process Node hanya memengaruhi request yang memang membaca atau menggunakan konfigurasi tersebut.

Browser, database daemon, Docker container lain, atau service yang berjalan terpisah tidak otomatis menggunakan proxy yang sama.

Ini berbeda dengan mekanisme VPN yang dapat mengatur routing pada level jaringan yang lebih luas. Kalau ingin membandingkannya, baca artikel Proxy vs VPN.

Kapan Proxy di Node.js Berguna?

Mengakses API eksternal dari jaringan perusahaan yang mewajibkan outbound proxy.
Testing aplikasi melalui jalur jaringan berbeda.
Menguji geolocation aplikasi yang memang kamu kelola.
Monitoring endpoint dari IP tertentu.
Menjalankan automation pada service yang memang mengizinkan automated access.
Memisahkan jalur request pada environment development dan production.
Mengakses resource eksternal dari server yang outbound traffic-nya dikontrol.

Proxy tetap bukan izin untuk mengabaikan Terms of Service, autentikasi, atau rate limit sebuah layanan.

HTTP Proxy atau HTTPS Proxy untuk Node.js?

Pilih berdasarkan endpoint proxy yang diberikan, bukan hanya berdasarkan URL website tujuan.

Proxy	Contoh URL	Keterangan
HTTP Proxy	`http://proxy.example:8080`	Koneksi client ke proxy menggunakan HTTP.
HTTPS Proxy	`https://proxy.example:8443`	Koneksi client ke proxy menggunakan TLS.

Kalau masih bingung membedakan kategori protokol proxy, lihat artikel jenis-jenis proxy.

Praktik yang Lebih Aman untuk Proxy di Node.js

Konfigurasi proxy sering berisi credential dan memengaruhi seluruh outbound request aplikasi. Karena itu perlakukan setting ini seperti bagian lain dari konfigurasi infrastruktur.

Jangan hardcode password proxy ke repository.
Gunakan environment variable atau secret manager.
Gunakan NO_PROXY untuk localhost dan service internal jika diperlukan.
Berikan timeout pada request.
Gunakan proxy yang memang dipercaya untuk data sensitif.
Jangan menonaktifkan verifikasi TLS hanya agar request berhasil.
Jangan mencetak URL proxy lengkap ke log jika mengandung password.
Cek IP setelah konfigurasi untuk memastikan request benar-benar melewati proxy.

FAQ Cara Setting Proxy di Node.js

Bagaimana cara menggunakan HTTP_PROXY di Node.js?

Set environment variable HTTP_PROXY, lalu aktifkan built-in environment proxy menggunakan NODE_USE_ENV_PROXY=1 atau flag --use-env-proxy pada versi Node.js yang mendukung fitur tersebut.

Apakah fetch Node.js mendukung proxy?

Ya, Node.js modern dapat menggunakan built-in proxy configuration untuk fetch() ketika environment proxy diaktifkan. Fetch Node.js sendiri menggunakan implementasi berbasis Undici.

Apa fungsi HTTPS_PROXY?

HTTPS_PROXY menentukan proxy yang digunakan untuk destination HTTPS. URL proxy tersebut dapat tetap menggunakan skema HTTP jika proxy yang diberikan memang merupakan HTTP proxy.

Apa fungsi NO_PROXY?

NO_PROXY berisi daftar host atau domain yang harus diakses secara langsung tanpa melewati proxy. Ini biasanya digunakan untuk localhost, IP lokal, atau service internal.

Kenapa HTTP_PROXY sudah diset tetapi IP Node.js tidak berubah?

Pastikan built-in proxy support sudah diaktifkan menggunakan NODE_USE_ENV_PROXY=1 atau --use-env-proxy. Cek juga apakah request masuk dalam daftar NO_PROXY.

Bagaimana cara menggunakan proxy dengan username dan password?

Gunakan URL seperti http://username:password@host:port. Jangan simpan credential tersebut secara permanen di source code atau repository publik.

Apakah proxy Node.js berlaku untuk seluruh komputer?

Tidak. Konfigurasi proxy di process Node hanya memengaruhi request yang menggunakan konfigurasi tersebut. Service atau aplikasi lain tidak otomatis ikut memakai proxy yang sama.

Kenapa localhost tidak bisa diakses setelah proxy aktif?

Kemungkinan request lokal ikut diarahkan ke proxy. Tambahkan localhost dan 127.0.0.1 ke NO_PROXY.

Kenapa Node.js mendapat certificate error melalui proxy?

Penyebabnya dapat berupa CA yang tidak dipercaya atau TLS inspection pada jaringan perusahaan. Gunakan certificate authority yang benar melalui konfigurasi CA Node.js, bukan menonaktifkan verifikasi TLS.

Apakah built-in proxy Node.js mendukung SOCKS5?

Built-in proxy configuration yang dibahas di artikel ini berfokus pada HTTP dan HTTPS proxy. Untuk SOCKS5, gunakan client atau agent yang memang mendukung protokol SOCKS.