Cara Mengatur Proxy untuk npm Saat Registry Terblokir: Cermin, .npmrc, dan Cara Mengatasi Pembatasan

```html

npm-registry tidak tersedia — dan pembangunan proyek terhenti. Situasi yang akrab bagi pengembang di jaringan perusahaan, daerah dengan akses terbatas, atau saat bekerja melalui firewall yang ketat. Dalam panduan ini, kita akan membahas semua cara yang efektif: dari beralih ke cermin hingga pengaturan proxy yang tepat di .npmrc — agar npm install kembali berfungsi tanpa kesalahan.

Mengapa npm registry diblokir dan apa yang terjadi saat itu

Registry npm resmi terletak di https://registry.npmjs.org. Ini adalah CDN global, tetapi tetap dapat tidak tersedia karena beberapa alasan, dan masing-masing memerlukan pendekatan yang berbeda.

Alasan utama ketidaktersediaan registry

• Firewall perusahaan — perusahaan memblokir permintaan langsung ke repositori eksternal, hanya mengizinkan lalu lintas melalui server proxy internal. Ini adalah praktik standar di bank, lembaga pemerintah, dan perusahaan IT besar.
• Geoblocking atau pembatasan regional — di beberapa negara dan wilayah, akses ke npmjs.org dibatasi di tingkat penyedia layanan internet atau firewall pemerintah.
• Jaringan kantor tanpa akses langsung ke internet — mesin kerja di segmen jaringan yang terisolasi tidak memiliki akses langsung ke sumber daya eksternal, semua lalu lintas melewati gerbang perusahaan.
• Tunnel VPN dengan pemaksaan proxy — VPN perusahaan mengalihkan semua lalu lintas, dan npm tidak dapat menghubungi registry secara langsung.
• Masalah dengan inspeksi SSL — proxy perusahaan menangkap lalu lintas HTTPS dan mengganti sertifikat, yang menyebabkan kesalahan seperti SELF_SIGNED_CERT_IN_CHAIN atau UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Kesalahan umum saat registry diblokir

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

Setiap kode kesalahan ini menunjukkan masalah yang berbeda: ECONNREFUSED — koneksi ditolak oleh firewall, ETIMEDOUT — permintaan tidak mendapatkan respons (diblokir tanpa jawaban), kesalahan sertifikat — masalah inspeksi SSL. Memahami penyebabnya langsung mempersempit lingkup solusi.

Cermin npm registry: cara cepat tanpa proxy

Cara paling sederhana untuk mengatasi pemblokiran adalah dengan mengalihkan npm ke cermin registry alternatif. Cermin tersebut berisi paket yang sama dengan registry resmi, tetapi terletak di server dan domain yang berbeda. Ini berfungsi ketika domain registry.npmjs.org diblokir, bukan seluruh lalu lintas HTTPS.

Cermin npm yang populer

Cara mengalihkan registry

Pengalihan untuk satu perintah (tanpa mengubah pengaturan global):

# Instalasi sekali melalui registry alternatif
npm install react --registry https://registry.npmmirror.com

# Mengatur secara global untuk pengguna saat ini
npm config set registry https://registry.npmmirror.com

# Memeriksa registry saat ini
npm config get registry

# Mengembalikan registry resmi
npm config set registry https://registry.npmjs.org

Catatan penting: jika Anda beralih ke cermin dalam proyek dengan perintah, lebih baik mencatat ini dalam file .npmrc di root repositori — maka semua anggota tim secara otomatis akan mendapatkan konfigurasi yang benar saat mengkloning proyek.

# .npmrc di root proyek
registry=https://registry.npmmirror.com

Pengaturan proxy melalui .npmrc: sintaks lengkap

Ketika cermin tidak membantu (misalnya, seluruh lalu lintas HTTPS diblokir), Anda perlu secara eksplisit memberi tahu npm alamat server proxy. File .npmrc adalah file konfigurasi utama npm, dan di situlah pengaturan proxy disimpan.

Lokasi file .npmrc

npm mencari konfigurasi di beberapa tempat — dalam urutan prioritas (dari yang tertinggi ke terendah):

• Proyek — /path/to/project/.npmrc — diterapkan hanya untuk proyek ini
• Pengguna — ~/.npmrc — diterapkan untuk pengguna saat ini di sistem
• Global — $PREFIX/etc/npmrc — diterapkan untuk seluruh instalasi npm
• Built-in — /path/to/npm/npmrc — pengaturan default dari npm itu sendiri

Sintaks pengaturan proxy di .npmrc

# Proxy untuk lalu lintas HTTP
proxy=http://proxy.example.com:8080

# Proxy untuk lalu lintas HTTPS (digunakan untuk sebagian besar permintaan ke registry)
https-proxy=http://proxy.example.com:8080

# Proxy dengan autentikasi (login:password dalam URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Pengecualian — alamat yang melewati proxy
noproxy=localhost,127.0.0.1,internal.company.com

Mengatur proxy melalui perintah npm config

Alternatif untuk mengedit file secara manual adalah menggunakan perintah npm config set. Ini secara otomatis akan menulis pengaturan ke ~/.npmrc:

# Mengatur proxy
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Memeriksa pengaturan proxy saat ini
npm config get proxy
npm config get https-proxy

# Menghapus pengaturan proxy (mengembalikan koneksi langsung)
npm config delete proxy
npm config delete https-proxy

# Melihat seluruh konfigurasi npm
npm config list

Proxy melalui variabel lingkungan untuk npm

npm secara otomatis membaca variabel lingkungan sistem standar untuk proxy. Ini nyaman dalam pipeline CI/CD, kontainer Docker, dan sistem di mana konfigurasi ditentukan di tingkat lingkungan, bukan file.

Variabel lingkungan standar

# Linux / macOS — pengaturan dalam sesi saat ini
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Versi huruf kecil (npm memahami keduanya)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Command Prompt)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

Prioritas konfigurasi npm

Penting untuk memahami bahwa npm menggunakan prioritas berikut saat menentukan proxy (dari yang tertinggi ke terendah):

1. Flag baris perintah: --proxy http://...
2. Variabel lingkungan dengan awalan npm_config_: misalnya, npm_config_proxy
3. File proyek .npmrc
4. File pengguna ~/.npmrc
5. File global $PREFIX/etc/npmrc
6. Variabel lingkungan standar HTTP_PROXY / HTTPS_PROXY

Jika proxy diatur di .npmrc, tetapi variabel lingkungan menunjukkan alamat lain — .npmrc yang akan menang. Ini adalah penyebab umum kebingungan dalam sistem CI/CD.

Pengaturan dalam CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions — tambahkan ke bagian env job atau step
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI — dalam variabel proyek atau di .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Proxy perusahaan dengan autentikasi dan inspeksi SSL

Server proxy perusahaan adalah kasus yang paling rumit. Mereka tidak hanya mengalihkan lalu lintas, tetapi juga memerlukan autentikasi, dan sering kali melakukan inspeksi SSL (menangkap dan mendekripsi lalu lintas HTTPS). Ini menghasilkan kesalahan sertifikat spesifik yang tidak dapat ditangani npm secara langsung.

Proxy dengan autentikasi NTLM/Basic

Jika proxy perusahaan memerlukan login dan password (Basic Auth), mereka dapat disertakan langsung dalam URL. Namun, untuk autentikasi NTLM (domain Windows), lebih rumit — npm tidak mendukung NTLM secara native. Dalam hal ini, alat perantara digunakan.

# Basic Auth — login dan password dalam URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Jika password mengandung karakter khusus — mereka perlu di-URL-encode
# @ → %40, # → %23, : → %3A
# Contoh: password "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Untuk autentikasi NTLM, gunakan utilitas cntlm — ia berjalan secara lokal, menerima permintaan HTTP biasa dan melakukan NTLM handshake dengan proxy perusahaan. Untuk npm, ini terlihat seperti proxy biasa tanpa autentikasi:

# Setelah mengatur cntlm, ia mendengarkan di localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Mengatasi masalah inspeksi SSL

Proxy perusahaan dengan inspeksi SSL mengganti sertifikat situs dengan sertifikat perusahaan mereka. npm memeriksa rantai kepercayaan dan menolak sertifikat semacam itu. Ada tiga pendekatan:

Cara 1 (direkomendasikan): tambahkan sertifikat CA perusahaan ke dalam daftar yang dipercaya

# Dapatkan sertifikat perusahaan dari departemen IT (file .crt atau .pem)
# Tentukan dalam konfigurasi npm
npm config set cafile /path/to/corporate-ca.crt

# Atau tambahkan beberapa sertifikat melalui cafile
# Beberapa CA dapat digabungkan menjadi satu file PEM

Cara 2 (sementara, tidak aman): nonaktifkan pemeriksaan SSL

# Gunakan hanya sebagai solusi sementara untuk diagnostik!
npm config set strict-ssl false

# Atau untuk satu perintah
npm install --legacy-peer-deps --no-strict-ssl

Proxy SOCKS5 untuk npm: pengaturan melalui utilitas helper

npm hanya mendukung proxy HTTP/HTTPS secara native. Jika Anda memiliki proxy SOCKS5 (misalnya, dari penyedia proxy residensial), tidak dapat ditentukan langsung dalam konfigurasi npm. Dibutuhkan lapisan perantara — utilitas yang menerima permintaan HTTP dari npm dan mengalihkan mereka melalui SOCKS5.

Cara 1: proxychains (Linux/macOS)

# Instalasi proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# Konfigurasi /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# Menjalankan npm melalui proxychains
proxychains4 npm install

Cara 2: konverter HTTP-ke-SOCKS5 lokal

Utilitas privoxy atau polipo membuat proxy HTTP lokal yang meneruskan lalu lintas melalui SOCKS5. Setelah dijalankan, npm melihat proxy HTTP biasa di localhost:

# Instalasi privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Tambahkan ke konfigurasi /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# Privoxy mendengarkan di localhost:8118 secara default
# Tentukan npm untuk menggunakan alamat ini:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Cara 3: Tunnel SSH sebagai proxy SOCKS5

Jika Anda memiliki akses ke server jarak jauh dengan internet terbuka, Anda dapat membuat tunnel SOCKS5 SSH dan mengarahkan lalu lintas npm melalui itu. Ini sangat nyaman saat bekerja dari jaringan perusahaan dengan akses terbatas:

# Membuat tunnel SOCKS5 SSH di port lokal 1080
ssh -D 1080 -f -C -q -N [email protected]

# Selanjutnya gunakan privoxy atau proxychains untuk mengonversi ke HTTP
# Atau langsung melalui variabel lingkungan (Node.js memahami SOCKS melalui beberapa pustaka)

# Alternatif — gunakan curl sebagai tes:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Registry privat sendiri sebagai alternatif proxy

Dalam lingkungan perusahaan dan terisolasi, sering kali solusi terbaik bukanlah mengatur proxy untuk setiap pengembang, tetapi menerapkan registry npm sendiri di dalam jaringan. Registry semacam itu menyimpan paket dari npmjs.org publik dan menyediakannya dari jaringan internal. Pengembang tidak memerlukan akses ke internet — semuanya berfungsi melalui registry lokal.

Verdaccio: memulai dengan cepat dalam 10 menit

Verdaccio adalah registry npm open-source dengan dukungan proxy dan caching. Diinstal sebagai paket npm, berfungsi sebagai layanan terpisah:

# Instalasi Verdaccio secara global
npm install -g verdaccio

# Menjalankan (secara default mendengarkan di http://localhost:4873)
verdaccio

# Mengatur npm untuk menggunakan registry lokal
npm config set registry http://localhost:4873

# Menerbitkan paket ke registry lokal
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Konfigurasi Verdaccio (~/.config/verdaccio/config.yaml) memungkinkan pengaturan proxy melalui proxy eksternal untuk mengunduh paket dari npmjs.org:

# config.yaml — pengaturan uplink dengan proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Jika Verdaccio sendiri berada di belakang proxy:
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

Perbandingan solusi untuk lingkungan terisolasi

Diagnostik dan pemecahan kesalahan umum

Bahkan setelah pengaturan proxy yang benar, masalah dapat muncul. Berikut adalah pendekatan sistematis untuk diagnostik dan daftar kesalahan yang paling umum beserta solusinya.

Langkah 1: Periksa konfigurasi npm saat ini

# Menampilkan semua pengaturan npm (termasuk proxy)
npm config list

# Menampilkan hanya pengaturan proxy
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Mengaktifkan output rinci untuk diagnostik
npm install react --verbose
npm install react --loglevel verbose

Langkah 2: Periksa ketersediaan registry secara langsung

# Periksa ketersediaan registry melalui curl
curl -v https://registry.npmjs.org/react/latest

# Periksa melalui proxy
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Periksa ping (tidak selalu informatif untuk HTTPS)
ping registry.npmjs.org

# Periksa resolusi DNS
nslookup registry.npmjs.org

Kesalahan umum dan solusinya

Reset semua pengaturan proxy

# Menghapus semua pengaturan proxy dari konfigurasi pengguna
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Mengatur registry kembali ke resmi
npm config set registry https://registry.npmjs.org

# Mengembalikan strict-ssl (jika dinonaktifkan)
npm config set strict-ssl true

# Memeriksa konfigurasi akhir
npm config list

Bekerja dengan pnpm dan Yarn saat registry diblokir

Jika Anda menggunakan manajer paket alternatif, pengaturan proxy terlihat mirip, tetapi sintaksnya sedikit berbeda:

# pnpm — menggunakan .npmrc yang sama dengan npm
# Tambahan dapat diatur melalui pnpm config:
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) — file .yarnrc sendiri
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) — file .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Pengaturan proxy untuk paket scoped tertentu

Terkadang perlu menggunakan registry yang berbeda untuk paket yang berbeda: misalnya, paket publik diambil dari npmjs.org resmi, sementara paket perusahaan @company/* diambil dari Nexus internal. Ini diatur melalui registry khusus scope di .npmrc:

# .npmrc — registry berbeda untuk scope yang berbeda
registry=https://registry.npmjs.org

# Paket perusahaan @company melalui Nexus internal
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Paket @myorg melalui Verdaccio
@myorg:registry=http://localhost:4873/

# Autentikasi untuk registry tertentu
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Kesimpulan dan rekomendasi akhir

Dalam dunia pengembangan perangkat lunak, mengatasi pemblokiran registry npm bisa menjadi tantangan. Namun, dengan memahami berbagai metode yang tersedia, mulai dari penggunaan cermin hingga pengaturan proxy yang tepat, pengembang dapat memastikan akses yang lancar ke paket yang mereka butuhkan. Selalu penting untuk mendokumentasikan pengaturan ini dalam proyek agar seluruh tim dapat mengaksesnya dengan mudah.