Azure App Service için Node.js uygulamasını yapılandırma

Node.js uygulamalar tüm gerekli npm bağımlılıklarıyla dağıtılmalıdır. App Service dağıtım altyapısı, npm install --production dağıttığınızda veya derleme otomasyonu etkin bir Zip paketi dağıttığınızda otomatik olarak çalışır. Ancak dosyalarınızı FTP/S kullanarak dağıtırsanız gerekli paketleri el ile yüklemeniz gerekir.

Bu makalede önemli kavramlar açıklanır ve App Service'e dağıtım yapan Node.js geliştiricilere yönelik yönergeler sağlanır. Azure App Service'i hiç kullanmadıysanız önce Node.js hızlı başlangıcı ve MongoDB ileNode.js öğreticisini tamamlayın.

Node.js sürümünü gösterme

Geçerli Node.js sürümünü göstermek için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config appsettings list --name <app-name> --resource-group <resource-group-name> --query "[?name=='WEBSITE_NODE_DEFAULT_VERSION'].value"

Desteklenen tüm Node.js sürümlerini göstermek için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp list-runtimes --os windows | grep NODE

Geçerli Node.js sürümünü göstermek için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

Desteklenen tüm Node.js sürümlerini göstermek için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp list-runtimes --os linux | grep NODE

Node.js sürümünü ayarlama

Uygulamanızı desteklenen bir Node.js sürümüne

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~24"

Not

Bu örnekte, App Service'te Node.js 24 çalışma zamanının kullanılabilir en son sürümünü hedeflemek için önerilen tilde söz dizimi kullanılır.

Çalışma zamanı platform tarafından düzenli olarak düzeltme eki uygulandığından ve güncelleştirildiğinden, belirli bir ikincil sürümü / düzeltme ekini hedeflemenizi önermeyiz. Olası güvenlik riskleri nedeniyle bu sürümlerin kullanılabilir olması garanti değildir.

Not

Projenizin package.jsonsürümünde Node.js sürümünü ayarlamanız gerekir. Dağıtım altyapısı, desteklenen tüm Node.js sürümlerini içeren ayrı bir işlemde çalışır.

Uygulamanızı desteklenen bir Node.js sürümüne ayarlamak için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "NODE|24-lts"

Bu ayar, hem çalışma zamanında hem de Kudu'da otomatik paket geri yükleme sırasında kullanılacak Node.js sürümünü belirtir.

Not

Projenizin package.jsonsürümünde Node.js sürümünü ayarlamanız gerekir. Dağıtım altyapısı, desteklenen tüm Node.js sürümlerini içeren ayrı bir kapsayıcıda çalışır.

App Service'te eski çalışma zamanlarına ne olur?

Eski çalışma zamanları, bakım kuruluşu tarafından kullanım dışı bırakılır veya önemli güvenlik açıklarına sahiptir. Buna göre, portaldaki oluşturma ve yapılandırma sayfalarından kaldırılırlar. Süresi geçmiş bir çalışma zamanı portaldan gizlendiğinde, bu çalışma zamanını kullanmaya devam eden tüm uygulamalar çalışmaya devam eder.

Portalda artık gösterilmemiş bir eski çalışma zamanı sürümüne sahip bir uygulama oluşturmak istiyorsanız Azure CLI' yı, ARM şablonunu veya Bicep'i kullanın. Bu dağıtım alternatifleri, portaldan kaldırılan ancak hala desteklenmeye devam eden kullanım dışı çalışma zamanları oluşturmanıza olanak tanır.

Bir çalışma zamanı App Service platformundan tamamen kaldırılırsa, Azure aboneliği sahibiniz kaldırmadan önce bir e-posta bildirimi alır.

Bağlantı noktası numarasını ayarlama

Node.js uygulamanızın gelen istekleri almak için doğru bağlantı noktasını dinlemesi gerekir.

Windows üzerinde App Service'te Node.js uygulamalar IISNode ile barındırılır ve Node.js uygulamanız değişkende process.env.PORT belirtilen bağlantı noktasını dinlemelidir. Aşağıdaki örnek, basit bir Express uygulamasında bağlantı noktasının nasıl ayarlandığını gösterir:

App Service, Node.js kapsayıcısında ortam değişkenini PORT ayarlar ve gelen istekleri kapsayıcınıza bu bağlantı noktası numarasından iletir. İstekleri almak için uygulamanızın değişkende belirtilen bağlantı noktasını dinlemesi process.env.PORT gerekir. Aşağıdaki örnekte, basit bir Express uygulamasında bağlantı noktasının nasıl ayarlanacağı gösterilmektedir:

const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`)
})

Derleme otomasyonunu özelleştirin

Uygulamanızı Git kullanarak veya derleme otomasyonu etkin zip paketleri kullanarak dağıtırsanız App Service derleme otomasyonu aşağıdaki adımları tamamlar:

tarafından PRE_BUILD_SCRIPT_PATHbelirtilmişse özel bir betik çalıştırın.
Herhangi bir bayrak olmadan çalıştırın npm install . Bu adım npm preinstall ve betikleri postinstalliçerir ve devDependencies ayrıca yükler.
npm run build dosyanızda bir derleme betiği belirtilirse komutunu çalıştırın.
npm run build:azure dosyanızda bir build:azure betik belirtilirse komutunu çalıştırın.
tarafından POST_BUILD_SCRIPT_PATHbelirtilmişse özel bir betik çalıştırın.

Not

npm belgelerinde belirtildiği gibi, prebuild ve postbuild adlı betikler, belirtilirse build betiğinden önce ve sonra sırasıyla çalıştırılır. Betikler sırasıyla ve öncesinde ve sonrasında preinstalladlı postinstall ve install çalıştırılan betikler.

PRE_BUILD_COMMAND ve POST_BUILD_COMMAND varsayılan olarak boş olan ortam değişkenleridir. Derleme öncesi komutları çalıştırmak için PRE_BUILD_COMMAND tanımlayın. Derleme sonrası komutları çalıştırmak için tanımlayın POST_BUILD_COMMAND.

Aşağıdaki örnek, virgülle ayrılmış bir dizi komut belirtmek için iki değişkeni kullanır.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

Derleme otomasyonlarını özelleştirmeye yönelik ek ortam değişkenleri hakkında bilgi için bkz. Oryx yapılandırması.

App Service'in Linux'ta Node.js uygulamaları nasıl çalıştırıp oluşturduğu hakkında daha fazla bilgi için Oryx belgelerine bakın: Node.js uygulamaları nasıl algılanıp oluşturulur?

Node.js sunucusunu yapılandırma

Node.js kapsayıcıları, bir üretim süreci yöneticisi olan PM2 ile birlikte gelir. Uygulamanızı PM2 ile, ile npm startveya özel bir komutla başlayacak şekilde yapılandırabilirsiniz.

Araç	Amaç
PM2 ile çalıştırma	Önerilir. Üretim veya hazırlama kullanımı. PM2, tam hizmet uygulama yönetimi platformu sağlar.
npm start ile çalıştır	Yalnızca geliştirme kullanımı.
Özel komutla çalıştırma	Geliştirme veya test.

PM2 ile çalıştırma

Kapsayıcı, projenizde yaygın Node.js dosyalardan biri bulunduğunda uygulamanızı otomatik olarak PM2 ile başlatır:

bin/www
server.js
app.js
index.js
hostingstart.js
Aşağıdaki PM2 dosyalarından biri: process.json veya ecosystem.config.js

Aşağıdaki uzantılarla özel bir başlangıç dosyası da yapılandırabilirsiniz:

.js dosyası
uzantısı .json, .config.js, .yaml veya .yml olan birPM2 dosyası

Not

Node 14 LTS'den sonraki Node.js sürümlerinde, konteyner uygulamanızı PM2 ile otomatik olarak başlatmaz. Uygulamanızı PM2 ile başlatmak için başlangıç komutunu olarak pm2 start <.js-file-or-PM2-file> --no-daemonayarlayın. Container'ın düzgün çalışması için PM2'nin ön planda çalışması gerektiğinden --no-daemon argümanını kullandığınızdan emin olun.

Özel başlangıç dosyası eklemek için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename-with-extension>"

Özel komutla çalıştırma

App Service, run.sh gibi bir yürütülebilir dosya gibi özel bir komut kullanarak uygulamanızı başlatabilir. Örneğin, komutunu çalıştırmak npm run start:prodiçin Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "npm run start:prod"

npm start ile çalıştır

Uygulamanızı ile npm startbaşlatmak için start dosyasında bir betik olduğundan emin olun. Örneğin:

{
  ...
  "scripts": {
    "start": "gulp",
    ...
  },
  ...
}

Projenizde özel bir package.json kullanmak için Cloud Shell'de aşağıdaki komutu çalıştırın:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<filename>.json"

Uzaktan hata ayıklama

.config.js, .yml veya .yaml dosyası kullanarak çalıştırmanız dışında, Node.js uygulamanızı PM2 ile çalışacak şekilde yapılandırdığınızda Visual Studio Code'da uzaktan hata ayıklayabilirsiniz.

Çoğu durumda, uygulamanız için ek yapılandırma gerekmez. Uygulamanız birprocess.json dosyasıyla (varsayılan veya özel) çalıştırılıyorsa, JSON kökünde bir script özelliği olmalıdır. Örneğin:

{
  "name"        : "worker",
  "script"      : "./index.js",
  ...
}

Visual Studio Code'u uzaktan hata ayıklama için ayarlamak için App Service uzantısını yükleyin. Uzantı sayfasındaki yönergeleri izleyin ve Visual Studio Code'da Azure'da oturum açın.

Azure gezgininde, hata ayıklamak istediğiniz uygulamayı bulun, sağ tıklayın ve Uzaktan Hata Ayıklamayı Başlat'ı seçin. Uygulamanız için uzaktan hata ayıklamayı etkinleştirmek için Evet'i seçin. App Service bir tünel ara sunucusu başlatır ve hata ayıklayıcısını ekler. Ardından uygulamaya istekte bulunabilir ve hata ayıklayıcının kesme noktalarında durduğunu görebilirsiniz.

Hata ayıklamayı bitirdiğinizde Bağlantıyı Kes'i seçerek hata ayıklayıcıyı durdurun. İstendiğinde, uzaktan hata ayıklamayı devre dışı bırakmak için Evet'i seçmeniz gerekir. Daha sonra devre dışı bırakmak için Azure gezgininde uygulamanıza yeniden sağ tıklayın ve Uzaktan Hata Ayıklamayı Devre Dışı Bırak'ı seçin.

Ortam değişkenlerine erişme

App Service'te uygulama ayarlarınızı uygulama kodunuzun dışında ayarlayabilirsiniz. Daha sonra standart Node.js desenini kullanarak bunlara erişebilirsiniz. Örneğin NODE_ENV adlı bir uygulama ayarına erişmek için şu kodu kullanabilirsiniz:

process.env.NODE_ENV

Grunt/Bower/Gulp çalıştır

App Service derleme otomasyonu, bir Node.js uygulamasının Git aracılığıyla veya npm install --production zip dağıtımı aracılığıyla dağıtıldığını algıladığında varsayılan olarak çalışır. Uygulamanız Grunt, Bower veya Gulp gibi popüler otomasyon araçlarından herhangi birini gerektiriyorsa, uygulamayı çalıştırmak için özel bir dağıtım betiği sağlamanız gerekir.

Deponuzun bu araçları çalıştırmasını sağlamak için bunlarıpackage.jsoniçindeki bağımlılıklara eklemeniz gerekir . Mesela:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

Yerel terminal penceresinden dizini deponuzun köküyle değiştirin ve aşağıdaki komutları çalıştırın:

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

Depo kökünüzün artık iki ek dosyası vardır: .deployment ve deploy.sh.

deploy.sh açın ve şu şekilde görünen bölümü bulunDeployment:

#############################################################
# Deployment
# ----------

Bu bölümün npm install --production sonunda çalıştırılır. Bölümün sonunaçalıştırmak için ihtiyacınız olan kod bölümünü ekleyin:

Çardak
Gulp
Homurtu

Örnek için MEAN.js örneğine bakın. Bu örnekte dağıtım betiği özel bir npm install komut da çalıştırır.

Çardak

Bu kod parçacığı çalıştırır bower install.

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

Bu kod parçacığı çalıştırır gulp imagemin.

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Hırıltı

Bu kod parçacığı çalıştırır grunt.

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

HTTPS oturumlarını algılama

App Service'te TLS/SSL sonlandırma ağ yük dengeleyicilerinde gerçekleşir, böylece tüm HTTPS istekleri şifrelenmemiş HTTP istekleri olarak uygulamanıza ulaşır. Uygulama mantığınızın kullanıcı isteklerinin şifrelenip şifrelenmediğini denetlemesi gerekiyorsa üst bilgiyi inceleyin X-Forwarded-Proto .

Popüler web çerçeveleri, standart uygulama düzeninizde X-Forwarded-* bilgisine erişmenizi sağlar. Express'te güven proxy'lerini kullanabilirsiniz. Örneğin:

app.set('trust proxy', 1)
...
if (req.secure) {
  // Do something when HTTPS is used
}

Tanılama günlüklerine erişim

App Service'te uygulama kodunuzun içinden oluşturulan konsol günlüklerine erişmek için cloud shell aşağıdaki komutu çalıştırarak tanılama günlüğünü açın:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

--level için olası değerler Error, Warning, Infove Verbose'dır. Her düzey kendisinden önceki düzeyi içerir. Örneğin, Error yalnızca hata iletilerini içerir. Verbose tüm iletileri içerir.

Tanılama günlüğünü açtıktan sonra, günlük akışını görmek için aşağıdaki komutu çalıştırın:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

Konsol günlükleri hemen görünmüyorsa 30 saniye içinde yeniden denetleyin.

Günlük akışını istediğiniz zaman durdurmak için Ctrl+C'yi seçin.

Kapsayıcının içinden oluşturulan konsol günlüklerine erişebilirsiniz.

Kapsayıcı günlüğünü açmak için aşağıdaki komutu çalıştırın:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

<app-name> ve <resource-group-name> değerlerini web uygulamanız için uygun adlarla değiştirin.

Kapsayıcı günlüğünü açtıktan sonra günlük akışını görmek için aşağıdaki komutu çalıştırın:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Konsol günlükleri hemen görünmüyorsa 30 saniye içinde yeniden denetleyin.

Günlük akışını istediğiniz zaman durdurmak için klavye kısayolu Ctrl+C'yi kullanın.

URL yeniden yazımları

Linux için Azure Uygulaması Hizmeti'ne Node.js uygulamaları dağıtırken, URL yeniden yazma işlemlerini doğrudan uygulamanızın içinde işlemeniz gerekebilir. Bu yapılandırma özellikle web sunucusu yapılandırmalarına bağlı kalmadan belirli URL desenlerinin doğru uç noktalara yönlendirildiğinden emin olmak için kullanışlıdır. Node.js URL yeniden yazma işlemleri gerçekleştirmenin çeşitli yolları vardır. Örneklerden biri express-urlrewrite paketini kullanmaktır.

Application Insights kullanarak uygulamanızı izleme

Application Insights, kod değişikliği yapmadan uygulamanızın performansını, özel durumlarını ve kullanımını izlemenizi sağlar. Application Insights aracısını eklemek için portalda web uygulamanıza gidin, İzleme'nin altında Application Insights'ı seçin ve ardından Application Insights'ı aç'ı seçin. Ardından, mevcut bir Application Insights kaynağını seçin veya yeni bir kaynak oluşturun. Son olarak, sayfanın alt kısmındaki Uygula'yı seçin. Web uygulamanızı PowerShell kullanarak işaretlemek için bu yönergelere bakın.

Bu ajan, sunucu tarafı Node.js uygulamanızı izleyecek. İstemci tarafı JavaScript'inizi izlemek için projenize JavaScript SDK'sını ekleyin.

Daha fazla bilgi için bkz. .NET, Node.js, Python ve Java uygulamaları için Azure App Service'te uygulama izlemeyi etkinleştirme.

Sorun giderme

Çalışan bir Node.js uygulaması App Service'te farklı davrandığında veya hatalar olduğunda aşağıdakileri deneyin:

Günlük akışına erişin.
Uygulamayı üretim modunda yerel olarak test edin. App Service, Node.js uygulamalarınızı üretim modunda çalıştırdığından, projenizin yerel olarak üretim modunda beklendiği gibi çalıştığından emin olmanız gerekir. Örneğin:
- package.json dosyasına bağlı olarak, üretim modu ( ile dependencies) için farklı paketler yüklenebilir.
- Bazı web çerçeveleri üretim modunda statik dosyaları farklı şekilde dağıtabilir.
- Bazı web çerçeveleri üretim modunda çalışırken özel başlangıç betikleri kullanabilir.
Uygulamanızı App Service'te geliştirme modunda çalıştırın. Örneğin, MEAN.jsuygulamasında, uygulama ayarını ayarlayarak NODE_ENVuygulamanızı çalışma zamanında geliştirme moduna ayarlayabilirsiniz.

Bu dizini veya sayfayı görüntüleme izniniz yok

Node.js kodunuzu App Service'te yerel bir Windows uygulamasına dağıttığınızda, uygulamanızın URL'sine gittiğinizde iletiyi You do not have permission to view this directory or page tarayıcıda görebilirsiniz. Bu hata büyük olasılıkla web.config dosyanız olmadığından oluşur. (Şablona ve örneğe bakın.)

Dosyalarınızı Git kullanarak veya derleme otomasyonu etkinken ZIP dağıtımı kullanarak dağıtırsanız, aşağıdaki koşullardan biri doğruysa dağıtım altyapısı uygulamanızın () web kökünde otomatik olarak bir %HOME%\site\wwwroot dosyası oluşturur:

Proje kökünde JavaScript dosyasının yolunu içeren bir betiği tanımlayan bir start dosyası bulunur.
Proje kök dizininiz bir server.js veya app.js dosyası içeriyor.

Oluşturulan web.config dosyası algılanan başlangıç betiğine uyarlanmıştır. Diğer dağıtım yöntemleri için web.config dosyasını el ile ekleyin. Dosyanın düzgün biçimlendirildiğinden emin olun.

ZIP dağıtımı kullanıyorsanız (örneğin Visual Studio Code aracılığıyla), derleme otomasyonlarını etkinleştirdiğinizden emin olun. Varsayılan olarak etkin değildir. az webapp up ZIP dağıtımını derleme otomasyonu etkinleştirilmiş olarak kullanır.

Günlüklerde robots933456 iletisini yoksayın

Kapsayıcı günlüklerinde aşağıdaki iletiyi görebilirsiniz:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

Bu iletiyi güvenle yoksayabilirsiniz. /robots933456.txt , sahte bir URL yoludur. App Service, kapsayıcının istekler için uygun olup olmadığını denetlemek için bunu kullanır. "404" hata yanıtı, yolun mevcut olmadığını gösterir ve App Service'e kapsayıcının iyi durumda olduğunu ve isteklere yanıt vermeye hazır olduğunu bildirir.

Öğretici: MongoDB ile uygulama Node.js

Linux üzerinde Azure App Service hakkında Sıkça Sorulan Sorular

Ortam değişkenleri ve uygulama ayarları referansı

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-09-09