npm için proxy ayarları: registry engelleme, aynalar, .npmrc ve kısıtlamaların aşılması

```html

npm-registry erişilemez hale geldi - ve proje derlemesi durdu. Kurumsal ağlarda, sınırlı erişim olan bölgelerde veya katı bir güvenlik duvarı üzerinden çalışırken tanıdık bir durum. Bu kılavuzda, aynalara geçişten .npmrc dosyasında proxy ayarlarına kadar tüm çalışır yöntemleri inceleyeceğiz - böylece npm install tekrar hatasız çalışsın.

npm registry neden engelleniyor ve bu durumda ne oluyor

Resmi npm registry adresi https://registry.npmjs.org. Bu küresel bir CDN'dir, ancak birkaç nedenle erişilemez hale gelebilir ve her biri farklı bir yaklaşım gerektirir.

Registry'nin erişilemez olmasının başlıca nedenleri

• Kurumsal güvenlik duvarı - şirket, dış depolara doğrudan istekleri engeller, trafiği yalnızca iç proxy sunucusu üzerinden izin verir. Bu, bankalar, devlet kurumları ve büyük IT şirketlerinde standart bir uygulamadır.
• Coğrafi engelleme veya bölgesel kısıtlamalar - bazı ülkelerde ve bölgelerde npmjs.org'a erişim, internet servis sağlayıcısı veya devlet güvenlik duvarı düzeyinde kısıtlanmıştır.
• İnternete doğrudan çıkışı olmayan ofis ağı - izole ağ segmentlerinde çalışan makineler, dış kaynaklara doğrudan erişim sağlamaz, tüm trafik kurumsal geçit üzerinden geçer.
• Proxy ile zorunlu VPN tüneli - kurumsal VPN, tüm trafiği yönlendirir ve npm doğrudan registry'e erişemez.
• SSL denetimi ile ilgili sorunlar - kurumsal proxy, HTTPS trafiğini yakalar ve sertifikaları değiştirir, bu da SELF_SIGNED_CERT_IN_CHAIN veya UNABLE_TO_VERIFY_LEAF_SIGNATURE gibi hatalara yol açar.

Engellenmiş registry ile ilgili tipik hatalar

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

Bu hata kodlarının her biri farklı bir sorunu gösterir: ECONNREFUSED - bağlantı güvenlik duvarı tarafından reddedildi, ETIMEDOUT - istek yanıtsız kalıyor (engellenmiş), sertifika hataları - SSL denetimi sorunu. Sorunun nedenini anlamak, çözüm yelpazesini daraltır.

npm registry aynaları: proxy olmadan hızlı bir geçiş

Engeli aşmanın en basit yolu, npm'i alternatif bir registry aynasına geçirmektir. Ayna, resmi registry ile aynı paketleri içerir, ancak farklı sunucularda ve alan adlarında bulunmaktadır. Bu, yalnızca registry.npmjs.org alanı engellendiğinde işe yarar, tüm HTTPS trafiği değil.

Popüler npm aynaları

Registry nasıl değiştirilir

Tek bir komut için geçiş (küresel ayarları değiştirmeden):

# Alternatif registry üzerinden tek seferlik kurulum
npm install react --registry https://registry.npmmirror.com

# Mevcut kullanıcı için küresel olarak kur
npm config set registry https://registry.npmmirror.com

# Mevcut registry'yi kontrol et
npm config get registry

# Resmi registry'ye geri dön
npm config set registry https://registry.npmjs.org

Önemli bir nokta: Eğer bir projede ayna kullanıyorsanız, bunu .npmrc dosyasına kaydetmek daha iyidir, böylece tüm ekip üyeleri projeyi klonladıklarında doğru yapılandırmayı otomatik olarak alırlar.

# Proje kökünde .npmrc
registry=https://registry.npmmirror.com

.npmrc üzerinden proxy ayarı: tam sözdizimi

Ayna işe yaramadığında (örneğin, tüm dış HTTPS trafiği engellendiğinde), npm'e proxy sunucusunun adresini açıkça belirtmek gerekir. .npmrc dosyası, npm'in ana yapılandırma dosyasıdır ve proxy ayarları burada saklanır.

.npmrc dosyalarının konumu

npm, yapılandırmayı birkaç yerde arar - öncelik sırasına göre (en yüksekten en düşüğe):

• Proje - /path/to/project/.npmrc - yalnızca bu projeye uygulanır
• Kullanıcı - ~/.npmrc - sistemdeki mevcut kullanıcı için uygulanır
• Küresel - $PREFIX/etc/npmrc - tüm npm kurulumuna uygulanır
• Yerleşik - /path/to/npm/npmrc - npm'in varsayılan ayarları

.npmrc dosyasında proxy ayarlarının sözdizimi

# HTTP trafiği için proxy
proxy=http://proxy.example.com:8080

# HTTPS trafiği için proxy (registry'e yapılan çoğu istek için kullanılır)
https-proxy=http://proxy.example.com:8080

# Kimlik doğrulamalı proxy (kullanıcı:şifre URL içinde)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# İstisnalar - proxy'yi atlayan adresler
noproxy=localhost,127.0.0.1,internal.company.com

npm config komutları ile proxy ayarlama

Dosyayı manuel olarak düzenlemeye alternatif olarak, npm config set komutunu kullanabilirsiniz. Bu, ayarları otomatik olarak kullanıcı ~/.npmrc dosyasına kaydedecektir:

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

# Mevcut proxy ayarlarını kontrol et
npm config get proxy
npm config get https-proxy

# Proxy ayarlarını sil (doğrudan bağlantıya geri dön)
npm config delete proxy
npm config delete https-proxy

# Tüm npm yapılandırmasını görüntüle
npm config list

npm için ortam değişkenleri ile proxy

npm, proxy için standart sistem ortam değişkenlerini otomatik olarak okur. Bu, CI/CD boru hatlarında, Docker konteynerlerinde ve yapılandırmanın ortam düzeyinde, dosya yerine ayarlandığı sistemlerde kullanışlıdır.

Standart ortam değişkenleri

# Linux / macOS - mevcut oturumda ayarlama
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Küçük harfli versiyonlar (npm her ikisini de anlar)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Komut İstemi)
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"

npm yapılandırma önceliği

npm'in proxy'yi belirlerken kullandığı öncelik sırasını anlamak önemlidir (en yüksekten en düşüğe):

1. Komut satırı bayrakları: --proxy http://...
2. npm_config_ ile başlayan ortam değişkenleri: örneğin, npm_config_proxy
3. Proje .npmrc
4. Kullanıcı ~/.npmrc
5. Küresel $PREFIX/etc/npmrc
6. Standart ortam değişkenleri HTTP_PROXY / HTTPS_PROXY

Eğer .npmrc dosyasında proxy ayarlanmışsa, ancak ortam değişkeni farklı bir adres gösteriyorsa - .npmrc kazanır. Bu, CI/CD sistemlerinde sıkça kafa karışıklığına neden olur.

CI/CD'de yapılandırma (GitHub Actions, GitLab CI)

# GitHub Actions - job veya step bölümüne ekleyin
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 - proje değişkenlerinde veya .gitlab-ci.yml içinde
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Kimlik doğrulama ve SSL denetimi ile kurumsal proxy

Kurumsal proxy sunucuları en karmaşık durumdur. Sadece trafiği yönlendirmekle kalmaz, aynı zamanda kimlik doğrulama gerektirir ve çoğu zaman SSL denetimi gerçekleştirir (HTTPS trafiğini yakalama ve çözme). Bu, npm'in kutudan çıktığında başa çıkamadığı belirli sertifika hatalarına yol açar.

NTLM/Basic kimlik doğrulamalı proxy

Eğer kurumsal proxy, kullanıcı adı ve şifre (Basic Auth) gerektiriyorsa, bunları doğrudan URL içinde iletebilirsiniz. Ancak NTLM kimlik doğrulaması (Windows alanı) ile işler daha karmaşıktır - npm NTLM'i yerel olarak desteklemez. Bu durumda, bir ara araç kullanılır.

# Basic Auth - URL içinde kullanıcı adı ve şifre
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Eğer şifre özel karakterler içeriyorsa - bunları URL ile kodlamanız gerekir
# @ → %40, # → %23, : → %3A
# Örnek: şifre "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

NTLM kimlik doğrulaması için cntlm aracı kullanılır - bu, yerel olarak çalışır, normal HTTP isteklerini kabul eder ve kurumsal proxy ile NTLM el sıkışmasını gerçekleştirir. npm için bu, kimlik doğrulaması olmayan sıradan bir proxy gibi görünür:

# cntlm ayarlandıktan sonra localhost:3128 üzerinde dinler
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

SSL denetimi sorununu çözme

SSL denetimi ile kurumsal proxy'ler, sitelerin sertifikalarını kendi kurumsal sertifikaları ile değiştirir. npm, güven zincirini kontrol eder ve bu tür sertifikaları reddeder. Üç yaklaşım vardır:

Yöntem 1 (önerilir): kurumsal CA sertifikasını güvenilirler listesine eklemek

# Kurumsal sertifikayı IT departmanından alın (crt veya pem dosyası)
# npm yapılandırmasında belirtin
npm config set cafile /path/to/corporate-ca.crt

# Veya birden fazla sertifikayı cafile üzerinden ekleyin
# Birkaç CA'yı bir PEM dosyasında birleştirebilirsiniz

Yöntem 2 (geçici, güvensiz): SSL kontrolünü devre dışı bırakmak

# Sadece teşhis için geçici bir çözüm olarak kullanın!
npm config set strict-ssl false

# Veya tek bir komut için
npm install --legacy-peer-deps --no-strict-ssl

npm için SOCKS5 proxy: yardımcı araçlar ile ayarlama

npm yalnızca HTTP/HTTPS proxy'lerini yerel olarak destekler. Eğer bir SOCKS5 proxy'niz varsa (örneğin, rezidans proxy'leri sağlayıcısından), bunu npm yapılandırmasında doğrudan belirtemezsiniz. Bir ara katman gereklidir - npm'den gelen HTTP isteklerini kabul eden ve bunları SOCKS5 üzerinden yönlendiren bir araç.

Yöntem 1: proxychains (Linux/macOS)

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

# macOS:
brew install proxychains-ng

# /etc/proxychains4.conf yapılandırması
[ProxyList]
socks5 proxy.example.com 1080 username password

# npm'i proxychains üzerinden çalıştırma
proxychains4 npm install

Yöntem 2: yerel HTTP'den SOCKS5'e dönüştürücü

privoxy veya polipo aracı, trafiği SOCKS5 üzerinden tünelleyen yerel bir HTTP proxy'si oluşturur. Çalıştırıldıktan sonra npm, localhost üzerinde normal bir HTTP proxy'si görür:

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

# /etc/privoxy/config dosyasına ekleyin:
forward-socks5 / proxy.example.com:1080 .

# Privoxy varsayılan olarak localhost:8118 üzerinde dinler
# npm'in bu adresi kullanmasını belirtin:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Yöntem 3: SOCKS5 proxy olarak SSH tüneli

Eğer açık internete erişimi olan bir uzak sunucuya erişiminiz varsa, bir SSH SOCKS5 tüneli oluşturabilir ve npm trafiğini bunun üzerinden yönlendirebilirsiniz. Bu, özellikle sınırlı erişime sahip kurumsal ağlardan çalışırken kullanışlıdır:

# Yerel 1080 portunda bir SSH SOCKS5 tüneli oluşturun
ssh -D 1080 -f -C -q -N [email protected]

# Daha sonra privoxy veya proxychains kullanarak HTTP'ye dönüştürün
# Veya doğrudan ortam değişkeni üzerinden (Node.js bazı kütüphanelerle SOCKS'ı anlar)

# Alternatif - testi curl ile yapın:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Kendi özel registry'niz proxy alternatif olarak

Kurumsal ve izole ortamlarda, her geliştirici için proxy ayarlamak yerine, ağ içinde kendi npm-registry'nizi dağıtmak genellikle en iyi çözümdür. Bu tür bir registry, npmjs.org'dan paketleri önbelleğe alır ve bunları iç ağdan sunar. Geliştiricilerin internete erişimi gerekmez - her şey yerel registry üzerinden çalışır.

Verdaccio: 10 dakikada hızlı başlangıç

Verdaccio, proxy ve önbellekleme desteği olan açık kaynaklı bir npm-registry'dir. npm paketi olarak kurulur, ayrı bir hizmet olarak çalışır:

# Verdaccio'yu küresel olarak kur
npm install -g verdaccio

# Başlatma (varsayılan olarak http://localhost:4873 üzerinde dinler)
verdaccio

# npm'i yerel registry kullanacak şekilde yapılandırma
npm config set registry http://localhost:4873

# Paketleri yerel registry'e yayınlama
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Verdaccio yapılandırması (~/.config/verdaccio/config.yaml) npmjs.org'dan paketleri yüklemek için dış proxy üzerinden proxy ayarlarını yapılandırmanıza olanak tanır:

# config.yaml - proxy ile uplink ayarı
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Eğer Verdaccio kendisi bir proxy arkasındaysa:
    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

İzole ortamlarda çözümlerin karşılaştırılması

Tipik hataların teşhisi ve giderilmesi

Doğru proxy ayarlarından sonra bile sorunlar ortaya çıkabilir. İşte teşhis için sistematik bir yaklaşım ve en sık karşılaşılan hataların çözüm listesi.

Adım 1: Mevcut npm yapılandırmasını kontrol et

# Tüm npm ayarlarını göster (proxy dahil)
npm config list

# Sadece proxy ayarlarını göster
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Teşhis için ayrıntılı çıktıyı etkinleştir
npm install react --verbose
npm install react --loglevel verbose

Adım 2: Registry'nin doğrudan erişilebilirliğini kontrol et

# curl ile registry'nin erişilebilirliğini kontrol et
curl -v https://registry.npmjs.org/react/latest

# Proxy üzerinden kontrol et
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# ping kontrolü (her zaman HTTPS için bilgilendirici değildir)
ping registry.npmjs.org

# DNS çözümlemesini kontrol et
nslookup registry.npmjs.org

Tipik hatalar ve çözümleri

Tüm proxy ayarlarını sıfırlama

# Kullanıcı yapılandırma dosyasından tüm proxy ayarlarını sil
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Registry'yi resmi olanına geri döndür
npm config set registry https://registry.npmjs.org

# strict-ssl'yi geri yükle (eğer devre dışı bıraktıysanız)
npm config set strict-ssl true

# Nihai yapılandırmayı kontrol et
npm config list

Engellenmiş registry ile pnpm ve Yarn ile çalışma

Alternatif paket yöneticileri kullanıyorsanız, proxy ayarı benzer şekilde görünür, ancak sözdizimi biraz farklıdır:

# pnpm - npm ile aynı .npmrc dosyasını kullanır
# Ek olarak pnpm config ile ayarlayabilirsiniz:
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) - kendi .yarnrc dosyası
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+) - .yarnrc.yml dosyası
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Belirli scoped paketler için proxy ayarlama

Bazen farklı paketler için farklı registry'ler kullanmak gerekir: örneğin, genel paketleri resmi npmjs.org'dan almak, ancak kurumsal @company/* paketlerini içsel Nexus'tan almak. Bu, .npmrc dosyasında scope-specific registry ile yapılandırılır:

# .npmrc - farklı scope'lar için farklı registry'ler
registry=https://registry.npmjs.org

# Kurumsal paketler @company içsel Nexus üzerinden
@company:registry=http://nexus.company.local/repository/npm-hosted/

# @myorg paketleri Verdaccio üzerinden
@myorg:registry=http://localhost:4873/

# Belirli bir registry için kimlik doğrulama
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Sonuç ve nihai öneriler

npm registry'ye erişim sorunlarıyla başa çıkmak için yukarıda belirtilen yöntemleri kullanarak, geliştiricilerin sorunsuz bir şekilde çalışmasını sağlamak mümkündür. Proxy ayarları ve alternatif registry'ler hakkında bilgi sahibi olmak, projelerinizi daha verimli bir şekilde yönetmenize yardımcı olacaktır.