Yeni iş bilgisayarınızda bir projeyi açıp npm install çalıştırıyorsunuz ve yirmi saniye boyunca hiçbir şey olmuyor. Sonra npm error code ETIMEDOUT hatası geliyor, ardından da bir proxy arkasında olabileceğinizi söyleyen bir not. Aynı makinede tarayıcı npm kayıt deposunu (registry) sorunsuz açıyor, çünkü tarayıcı Windows ya da macOS'un ona verdiği şirket proxy'sini kullanıyor. npm bu sistem ayarlarını okumaz; kendi ayarına ihtiyaç duyar.
Bu yazıda npm'e proxy vermenin üç yolunu (npm config, .npmrc dosyaları ve ortam değişkenleri), npm'in bunları hangi sırayla okuduğunu, özel karakter içeren şifreleri, ayarları kontrol edip kaldırmayı, iç sunucuları proxy dışında tutmayı ve sık görülen hataları ele alıyoruz. Her komutu Windows 11 üzerinde Node.js 24.22.2 ve npm 11.19.1 ile, her isteği günlüğe yazan ve şifre isteyen yerel bir proxy'ye karşı, deneme amaçlı geçici bir yapılandırma dosyasıyla çalıştırdık.
npm'in proxy'ye ne zaman ihtiyacı olur?
Makine kayıt deposuna doğrudan ulaşamıyorsa ya da ona bilinen tek bir adresten ulaşması gerekiyorsa npm proxy'ye ihtiyaç duyar. Kayıt deposu paketleri barındıran sunucudur; çoğu proje için bu https://registry.npmjs.org adresidir, ama şirketler kendi kayıt depolarını da çalıştırabilir.
Neredeyse her durum iki senaryodan birine girer. Şirket ağı dışarıya yalnız bir proxy üzerinden çıkışa izin verir ve kayıt deposuna doğrudan bağlantı zaman aşımına uğrar. Ya da özel bir kayıt deposu yalnız izin listesindeki IP adreslerinden gelen istekleri kabul eder, sizin dizüstü bilgisayarınızın ya da CI makinenizin ise sabit bir adresi yoktur. İki durumda da proxy'nin nerede olduğunu npm'e sizin söylemeniz gerekir, çünkü npm işletim sisteminin proxy ayarını tarayıcı gibi devralmaz.
npm isteği proxy üzerinden nasıl gönderir?
npm önce proxy'ye bağlanır ve ondan kayıt deposuna bir tünel açmasını ister. Aşağıdaki adımlar, npm view semver version komutu sırasında test proxy'mizin günlüğüne düşenlerdir:
- npm bir proxy adresi seçer. Tanımlıysa
https-proxydeğerini, değilseproxydeğerini kullanır. Yalnız ikisi de boşsaHTTPS_PROXYortam değişkenine bakar. - npm dışlama listesini kontrol eder. Kayıt deposunun adı
noproxy(ya daNO_PROXY) listesindeki bir girdiyle eşleşirse proxy atlanır ve npm doğrudan bağlanır. - npm proxy'ye bir TCP bağlantısı açar ve
CONNECT registry.npmjs.org:443gönderir. Proxy adresinde kullanıcı adı ve şifre varsa npm bunları daha bu ilk istekteProxy-Authorizationbaşlığıyla gönderir. Günlükte ek bir gidiş-dönüş yoktu:CONNECT registry.npmjs.org:443 auth user=user (ok). - Proxy
200 Connection Establishedyanıtını döner ve bundan sonra yalnız baytları aktarır. TLS el sıkışması tünelin içinde npm ile kayıt deposu arasında yapılır; proxy sunucu adını ve portu görür, paketleri görmez. - npm paket bilgilerini ve arşivleri indirir ve yerel önbelleğine kaydeder. Bu önbellek, sorun ararken ileride önem kazanacak.
npm proxy ayarı nasıl yapılır?
İki npm config set komutu ayarı kullanıcı hesabınız için yapar:
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000npm bu değerleri kullanıcıya özel .npmrc dosyasına yazar (macOS ve Linux'ta ~/.npmrc, Windows'ta C:\Users\<ad>\.npmrc). Test makinemizde dosyada bundan sonra tam olarak şu satırlar vardı:
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000https-proxy değerinin de http:// ile başladığına dikkat edin. Buradaki şema kayıt deposuna değil, proxy'ye giden bağlantıyı anlatır: proxy npm'den düz HTTP alır ve HTTPS trafiğini CONNECT tünelinin içinde taşır. https:// yazmanız yalnız proxy'nin kendisi o portta TLS bekliyorsa gerekir.
İki anahtarı da tanımlayın. Testimizde HTTPS kayıt deposu için tek başına proxy yetti, çünkü https-proxy boşken npm proxy değerini kullanır; ama npm ayarlarını okuyan her araç bu kuralı uygulamaz. npm bilinmeyen anahtarları reddeder; npm config set proxi … gibi bir yazım hatası npm error `proxi` is not a valid npm option hatasıyla durur.
Makinenin sabit bir IP'si varsa Proxynet'in IP whitelist (IP yetkilendirme) özelliğiyle kimlik bilgilerini adresten tamamen çıkarabilirsiniz: o durumda ayarın tamamı http://pr.proxynet.io:8000 olur.
npm hangi ayarları hangi sırayla okur?
npm ayarları birkaç kaynaktan birleştirir ve en özel olan kazanır. npm config belgeleri öncelik sırasını şöyle verir: önce komut satırı seçenekleri, sonra npm_config_ ile başlayan ortam değişkenleri, sonra .npmrc dosyaları, en son yerleşik varsayılanlar.
| Kaynak | Örnek | Kapsam |
|---|---|---|
| Komut satırı seçeneği | --https-proxy http://… | Tek komut |
npm_config_* değişkeni | npm_config_https_proxy | Açık terminal oturumu |
Proje .npmrc | <proje>/.npmrc | O proje |
Kullanıcı .npmrc | ~/.npmrc | Sizin hesabınız |
Genel npmrc | $PREFIX/etc/npmrc | O Node.js'in tüm kullanıcıları |
Yerleşik npmrc | npm'in kurulum klasörü | O npm kopyası |
Sırayı geçici bir dosyayla denedik: npm_config_proxy=http://env.example:3128 kullanıcı dosyasındaki değeri geçersiz kıldı, --proxy http://cli.example:3128 ise ikisini birden geçersiz kıldı. Ortam değişkeni adlarında büyük-küçük harf fark etmez ve tireler alt çizgiye döner; yani https-proxy anahtarı npm_config_https_proxy olur.
npm config set komutunun --location seçeneği dosyayı belirler: varsayılan user, project değeri package.json dosyasının yanındaki .npmrc dosyasına, global değeri npm'in kurulum önekindeki dosyaya yazar. Proje .npmrc dosyası proxy yalnız tek bir projede gerekiyorsa kullanışlıdır, ama genellikle sürüm kontrolüne eklenir; şifreyi bu dosyaya yazmayın. .npmrc başvurusu ${VARIABLE_NAME} biçimindeki değişken yerleştirmeyi de anlatır: https-proxy=${NPM_PROXY_URL} gibi bir satır proxy adresinin tamamını npm başlarken bir ortam değişkeninden okur ve gizli bilgiyi dosyanın dışında tutar. Bunu denedik; değişken tanımlı değilken npm ${NPM_PROXY_URL} metnini olduğu gibi bıraktı.
HTTP_PROXY ve HTTPS_PROXY npm'de çalışır mı?
HTTPS_PROXY çalışır; tek başına HTTP_PROXY ise testimizde kayıt deposu trafiğini proxy'ye yönlendirmedi. HTTPS_PROXY tanımlıyken ve hiçbir .npmrc dosyasında proxy yokken kayıt deposuna giden her istek proxy'mizden geçti. Yalnız HTTP_PROXY tanımlıyken npm view doğrudan bağlandı ve proxy günlüğü boş kaldı; oysa npm'in https-proxy açıklaması HTTP_PROXY değişkenini de yedek olarak anar. npm 11.19.1'in kodu https:// adresleri için yalnız HTTPS_PROXY değişkenini okuyor ve genel kayıt deposu HTTPS üzerinden çalışıyor.
Terminal, konteyner ya da CI işi için güvenli yol ikisini de, dışlama listesiyle birlikte tanımlamaktır:
export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"Windows PowerShell'de aynı satırlar $env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000" biçiminde yazılır. Bir tuzak var: HTTPS_PROXY tanımlıyken bile npm config get https-proxy komutu null yazar, çünkü npm değişkeni yalnız isteği gönderdiği anda uygular. Bu null değerini "proxy yok" diye okumayın.
Proxy adresine kullanıcı adı ve şifre nasıl yazılır?
İkisini sunucu adından önce user:password@ biçiminde yazın ve URL'de anlamı olan her karakteri yüzde kodlamasıyla (percent-encoding) kodlayın. Yüzde kodlaması bir karakteri % işareti ve onaltılık koduyla değiştirir. Proxy adresini bozan karakterler RFC 3986, bölüm 2.2 içinde sayılan ayırıcılardır: :, /, ?, #, [, ] ve @. Boşluk ve % işaretinin kendisi de kodlanmalıdır.
| Karakter | Kodlu biçimi |
|---|---|
@ | %40 |
: | %3A |
# | %23 |
/ | %2F |
% | %25 |
| boşluk | %20 |
Test proxy'miz p@ss:w#rd şifresini kabul ediyordu. Şifre kodlanmadan, http://user:p@ss:w#rd@127.0.0.1:18080 biçiminde yazıldığında npm proxy'ye ulaşamadı bile: Node.js adresin geçersiz olduğunu bildirdi, npm de getaddrinfo ENOTFOUND ss hatasıyla durdu. İlk @ işaretinden sonraki metni sunucu adı sanmıştı. Şifre http://user:p%40ss%3Aw%23rd@127.0.0.1:18080 biçiminde kodlanınca aynı komut paket sürümünü döndürdü ve proxy günlüğünde doğru bir oturum açma göründü. Bir DNS hatası hiç yazmadığınız bir sunucu adını gösteriyorsa önce şifreye bakın.
npm proxy ayarları nasıl kontrol edilir ve kaldırılır?
npm config list varsayılandan farklı her ayarı ve geldiği dosyayı gösterir. Bizim çalıştırmamızda çıktı kaynağı söyleyen bir satırla başladı, ; "user" config from …\test.npmrc, ardından proxy = "http://user:***@pr.proxynet.io:8000" geldi. npm bu görünümde şifreyi maskeler; çıktıyı bir destek talebine güvenle yapıştırabilirsiniz.
npm config get proxy ise şifre içeren bir değeri yazdırmayı reddeder: The proxy option is protected, and cannot be retrieved in this way. Adreste kimlik bilgisi yoksa değeri kaydedildiği gibi yazar; dosyanın kendisini npm config edit açar.
Proxy'yi kaldırmak için iki anahtarı da silin:
npm config delete proxy
npm config delete https-proxyHer delete komutu tek dosyadan tek satır siler; testimizde https-proxy satırı ayrıca silinene kadar yerinde kaldı. Diğer dosyalar için --location=project ya da --location=global ekleyin ve terminalinizde HTTPS_PROXY ile npm_config_https_proxy değişkenlerine bakın; dosya temizlense de unutulmuş bir değişken trafiği proxy'ye göndermeye devam eder. Dosyaya dokunmadan tek bir komutta proxy'yi atlamak için kayıt deposunu dışlama olarak verin: --noproxy registry.npmjs.org.
Bazı sunucular proxy dışında nasıl tutulur?
Onları virgülle ayırarak noproxy listesine yazın. npm sunucu adını sağdan başlayarak parça parça karşılaştırır; bu yüzden .internal.example hem registry.internal.example adresiyle hem de o alan adının altındaki her adla eşleşir.
npm config set noproxy "localhost,127.0.0.1,.internal.example"Genel kayıt deposunun adını noproxy listesine (ikinci denemede NO_PROXY değişkenine) eklediğimizde npm doğrudan bağlandı ve proxy günlüğüne hiçbir şey düşmedi. noproxy anahtarının varsayılan değeri NO_PROXY değişkeninden gelir; iki ayrı liste değil, tek liste tutun.
Sık görülen npm proxy hataları ve çözümleri
Aşağıdakiler testlerimizde npm 11'in yazdığı mesajlar ve yeniden üretmediğimiz iki hatadır:
npm error code E407ve407 Proxy Authentication Required. Proxy oturum açma bekliyor, ama hiç bilgi gelmedi ya da yanlış bilgi geldi. Eksik şifre de yanlış şifre de aynı metni verdi. Kullanıcı adını, özel karakterlerin kodlamasını ve IP whitelist kullanıyorsanız IP'nizin bu listede olup olmadığını kontrol edin.getaddrinfo ENOTFOUNDve ardından tuhaf bir sunucu adı. Proxy adresi yanlış ayrıştırıldı; neredeyse her zaman şifredeki kodlanmamış bir@ya da#yüzünden. Gösterilen ad proxy'nin kendisiyse yazımını ve DNS'inizi kontrol edin.connect ECONNREFUSED <proxy-ip>:<port>. O portu dinleyen bir şey yok: port numarası yanlış ya da proxy kapalı.connect ETIMEDOUT <ip>:<port>. Paketler hiçbir yere ulaşmıyor; ulaşılamayan test adresimiz yaklaşık 22 saniye sonra hata verdi. Proxy tanımlıysa adresi yanlıştır; tanımlı değilse ağ büyük olasılıkla dışarıya yalnız proxy üzerinden çıkışa izin veriyordur.ECONNRESET. Bağlantı açıldı, sonra kesildi; genellikle uzun indirmeleri kapatan bir proxy ya da trafiği inceleyen bir antivirüs yüzünden. Hangi isteğin düştüğünü--loglevel verbosegösterir.UNABLE_TO_GET_ISSUER_CERT_LOCALLYya daSELF_SIGNED_CERT_IN_CHAIN. Şirket proxy'si HTTPS trafiğini inceliyor ve Node.js'in güvenmediği kendi kök sertifikasıyla yeniden imzalıyor. Bu kök sertifikayı bir dosyaya koyun ve npm'incafileayarını ya daNODE_EXTRA_CA_CERTSdeğişkenini o dosyaya yönlendirin; ikisinin farkını ve doğru sertifikayı nasıl bulacağınızı unable to get local issuer certificate yazısında anlattık.
strict-ssl=false son hatayı, kayıt deposu için sertifika denetimini kapatarak ortadan kaldırır. Bunu en fazla bir dakikalık hata ayıklama için kullanın, asla çözüm olarak bırakmayın: bu ayar açıkken ağ yolundaki herhangi biri npm'e değiştirilmiş bir paket verebilir.
Bir tuzak da bize zaman kaybettirdi. Önbellek doluyken, proxy portunu dinleyen hiçbir şey olmadığı halde npm view bir sürüm numarası yazdı; npm yanıtı önbelleğinden vermişti. ECONNREFUSED ancak önbellek boşken göründü. Bir proxy değişikliği çalışıyor gibi görünüyorsa daha önce hiç kurmadığınız bir paketle ya da --prefer-online ve --cache ile verilen boş bir önbellek klasörüyle deneyin.
Yarn ve pnpm aynı ayarları kullanır mı?
pnpm aynı .npmrc anahtarlarını okur, Yarn 2 ve sonrası ise kendi dosyasını kullanır. pnpm ağ ayarları https-proxy, http-proxy ve noproxy ayarlarını anlatır; npm'in eski proxy anahtarı ikisi için de yedektir, ondan sonra HTTPS_PROXY, HTTP_PROXY ve NO_PROXY değişkenlerine bakılır. pnpm .npmrc dosyasından yalnız kimlik doğrulama, kayıt deposu, TLS, proxy ve local-address ayarlarını okur; bu yüzden mevcut npm proxy ayarı çoğu zaman olduğu gibi geçerli kalır.
Yarn 2 ve sonrası (Yarn Berry) ayarlarını .yarnrc.yml dosyasında tutar; anahtarlar httpProxy ve httpsProxy olur ve örneğin yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000 komutuyla tanımlanır. Yarn yapılandırma başvurusuna göre sertifika seçeneği httpsCaFilePath, enableStrictSsl ayarının varsayılanı ise true değeridir.
Proxy kurulum betiklerine ve Node.js'in kendisine ulaşır mı?
Kısmen. npm ayarlarını paket betiklerine ortam değişkeni olarak geçirir: testimizde npm run ile başlatılan bir betik npm_config_https_proxy ve npm_config_noproxy değişkenlerini gördü. Betiğin bunları kullanıp kullanmayacağı yazarına kalmıştır; bu yüzden kurulum sırasında ikili dosya indiren bir paket proxy arkasında yine de hata verebilir. Böyle bir durumda paketin kendi belgeleri genellikle okuduğu değişkenin adını verir.
Kendi Node.js kodunuz ayrı bir konudur. Node.js'in yerleşik fetch fonksiyonu, süreç NODE_USE_ENV_PROXY=1 ya da güncel Node.js sürümlerinin desteklediği --use-env-proxy seçeneğiyle başlatılmadıkça HTTPS_PROXY değişkenini yok sayar; kütüphanelere göre seçenekleri Node.js'te proxy kullanımı yazısında bulabilirsiniz.
Doğrudan bir Git deposundan kurulan bağımlılıkları (package.json içinde git+https:// adresi) npm'in ağ kodu değil, Git indirir. Git'in kendi proxy ayarları vardır; bunları Git proxy ayarları yazısında anlattık.
Sabit bir proxy IP'si ne zaman işe yarar?
Kimin bağlanabileceğine ağınız değil kayıt deposu karar veriyorsa sabit bir çıkış IP'si işe yarar. Şirketin kendi barındırdığı kayıt depoları ve paket aynaları çoğu zaman yalnız kısa bir kaynak adres listesine izin veren bir güvenlik duvarı kuralıyla korunur. Buluttaki derleme makineleri her çalıştırmada yeni bir adres alır, bu yüzden kural hiç eşleşmez. npm trafiğini özel ve değişmeyen bir adresi olan bir proxy'den geçirmek, güvenlik duvarına izin verilecek tek bir adres bırakır.
Datacenter Proxy elinizde tuttuğunuz sürece aynı özel IP'yi korur; derleme sunucuları için uygundur.
ISP Proxy aynı işi bir internet servis sağlayıcısına kayıtlı bir adresle yapar. İkisi de IP başına satılır ve varsayılan olarak hedef site kısıtlamasıyla gelir; kayıt deponuzun adresinin kapsamda olduğunu kontrol edin ya da "Tüm web sitelerine erişim" seçeneğini ekleyin. Şirketinizin kendi proxy'si arkasındaysanız bunların hiçbiri gerekmez: BT ekibinizin verdiği adresi kullanın.
Karar rehberi
| İhtiyaç | Ayar |
|---|---|
| Makinedeki her kurulum | npm config set proxy ve https-proxy |
| Yalnız tek proje | --location=project, içinde şifre yok |
| CI işi ya da konteyner | HTTPS_PROXY, HTTP_PROXY ve NO_PROXY |
| Tek komut | --https-proxy seçeneği |
| İç kayıt deposuna doğrudan | Alan adıyla noproxy |
@ ya da # içeren şifre | Yüzde kodlaması |
| Dosyada şifre olmasın | .npmrc içinde ${VAR} ya da IP whitelist |
| TLS inceleyen şirket proxy'si | cafile ya da NODE_EXTRA_CA_CERTS |
| IP izin listesi olan kayıt deposu | Özel IP'li proxy |
Sıkça sorulan sorular
npm'de proxy nasıl ayarlanır?
npm config set proxy http://host:port ve npm config set https-proxy http://host:port komutlarını çalıştırın; proxy oturum açma istiyorsa sunucu adından önce user:pass@ ekleyin. Ayarlar kullanıcı .npmrc dosyanıza yazılır ve bundan sonraki her npm komutunda geçerli olur.
npm proxy ayarına kullanıcı adı ve şifre nasıl eklenir?
İkisini adrese http://user:password@host:port biçiminde yazın ve her iki bölümdeki özel karakterleri yüzde kodlamasıyla kodlayın: @ yerine %40, : yerine %3A, # yerine %23. Kodlanmamış bir @ npm'in şifrenin geri kalanını sunucu adı sanmasına ve ENOTFOUND hatası vermesine yol açar.
npm proxy ayarı nasıl kaldırılır?
npm config delete proxy ve npm config delete https-proxy komutlarını çalıştırın, ardından npm config list ile kontrol edin. Trafik hâlâ bir proxy'den geçiyorsa ortam değişkenlerinizde HTTPS_PROXY ya da npm_config_https_proxy olup olmadığına, ayrıca proje ya da genel bir .npmrc dosyasına bakın.
npm proxy ayarları nerede saklanır?
Bir .npmrc dosyasında: varsayılan olarak kullanıcı başına ev klasörünüzde, proje başına package.json dosyasının yanında ya da genel olarak npm'in kurulum önekinde. npm config list, okuduğu her dosyanın yolunu o dosyadan gelen ayarların üstüne yazar.
npm Windows'taki sistem proxy'sini kullanır mı?
Hayır. npm yalnız kendi ayarlarını ve ortam değişkenlerini okur; Windows ağ ayarlarında ya da Internet Seçenekleri'nde tanımlı proxy'yi okumaz. Aynı adresi npm config set ya da HTTPS_PROXY ile tanımlayın.
npm SOCKS5 proxy kullanabilir mi?
npm'in ağ katmanında bir SOCKS istemcisi vardır ve npm 11'in kaynak kodunun gösterdiği gibi proxy ayarlarında socks5://host:port biçimindeki adresleri kabul eder; bunu canlı bir SOCKS sunucusuna karşı denemedik. Sizin sürümünüzde çalışmazsa sağlayıcının HTTP endpoint'ini kullanın; bu yazıdaki bütün testler o yolla yapıldı.
Özet
npm'e proxy'yi npm config set proxy ve npm config set https-proxy komutlarıyla, terminal ve CI ortamlarında ise HTTPS_PROXY ile verin; tek başına HTTP_PROXY testimizde kayıt deposu trafiğini yönlendirmedi. Komut satırındaki ayarlar npm_config_* değişkenlerini, onlar da proje, kullanıcı ve genel .npmrc dosyalarını geçersiz kılar. Şifredeki özel karakterleri kodlayın, iç sunucuları noproxy listesinde tutun, npm config list ile kontrol edin ve iki anahtarı da npm config delete ile kaldırın. Şirket proxy'si arkasındaki sertifika hataları strict-ssl=false ile değil, şirketin kök sertifikasıyla çözülür. Bu ayarların hepsiyle çalışan proxy endpoint'lerini Proxynet proxy sayfasında bulabilirsiniz.




