Konfigurowanie aplikacji Node.js dla usługi Azure App Service

Node.js aplikacje muszą być wdrażane ze wszystkimi wymaganymi zależnościami npm. Aparat wdrażania usługi App Service jest uruchamiany npm install --production automatycznie podczas wdrażania repozytorium Git lub wdrażania pakietu Zip z włączoną automatyzacją kompilacji. Jeśli jednak wdrażasz pliki przy użyciu protokołu FTP/S, musisz ręcznie przekazać wymagane pakiety.

W tym artykule opisano kluczowe pojęcia i przedstawiono instrukcje dla deweloperów Node.js, którzy wdrażają je w usłudze App Service. Jeśli nigdy nie używasz usługi Azure App Service, najpierw ukończ Node.js przewodnik Szybki start i Node.js z samouczkiem bazy danych MongoDB .

Pokaż wersję Node.js

Aby wyświetlić bieżącą wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

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

Aby wyświetlić wszystkie obsługiwane wersje Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

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

Aby wyświetlić bieżącą wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

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

Aby wyświetlić wszystkie obsługiwane wersje Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

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

Ustawianie wersji Node.js

Aby ustawić aplikację na obsługiwaną wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell , aby ustawić WEBSITE_NODE_DEFAULT_VERSION obsługiwaną wersję:

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

Uwaga

W tym przykładzie użyto zalecanej składni tyldy w celu kierowania najnowszej dostępnej wersji środowiska uruchomieniowego Node.js 24 w usłudze App Service.

Ponieważ środowisko uruchomieniowe jest regularnie poprawiane i aktualizowane przez platformę, nie zalecamy określania docelowej wersji pomocniczej/poprawki. Ze względu na potencjalne zagrożenia bezpieczeństwa te wersje nie są gwarantowane.

Uwaga

Należy ustawić wersję Node.js w projekcie package.json. Aparat wdrażania działa w osobnym procesie zawierającym wszystkie obsługiwane wersje Node.js.

Aby ustawić aplikację na obsługiwaną wersję Node.js, uruchom następujące polecenie w usłudze Cloud Shell:

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

To ustawienie określa wersję Node.js do wykorzystania, zarówno w czasie wykonywania, jak i podczas automatycznego przywracania pakietu w Kudu.

Uwaga

Należy ustawić wersję Node.js w projekcie package.json. Aparat wdrażania działa w oddzielnym kontenerze zawierającym wszystkie obsługiwane wersje Node.js.

Co się stanie z nieaktualnymi środowiskami uruchomieniowymi w usłudze App Service?

Nieaktualne środowiska uruchomieniowe są przestarzałe przez utrzymanie organizacji lub mają znaczące luki w zabezpieczeniach. W związku z tym są one usuwane z tworzenia i konfigurowania stron w portalu. Gdy nieaktualne środowisko uruchomieniowe jest ukryte w portalu, każda aplikacja, która nadal korzysta z tego środowiska uruchomieniowego, będzie nadal działać.

Jeśli chcesz utworzyć aplikację z nieaktualną wersją środowiska uruchomieniowego, która nie jest już wyświetlana w portalu, użyj interfejsu wiersza polecenia platformy Azure, szablonu usługi ARM lub Bicep. Te alternatywy wdrażania umożliwiają tworzenie przestarzałych środowisk uruchomieniowych, które są usuwane z portalu, ale nadal są obsługiwane.

Jeśli środowisko uruchomieniowe zostanie w pełni usunięte z platformy App Service, właściciel subskrypcji platformy Azure otrzyma powiadomienie e-mail przed usunięciem.

Ustawianie numeru portu

Aplikacja Node.js musi nasłuchiwać odpowiedniego portu w celu odbierania żądań przychodzących.

W usłudze App Service w systemie Windows aplikacje Node.js są hostowane w programie IISNode, a aplikacja Node.js powinna nasłuchiwać portu określonego w zmiennej process.env.PORT . W poniższym przykładzie pokazano, jak ustawić port w prostej aplikacji Express:

Usługa App Service ustawia zmienną środowiskową PORT w kontenerze Node.js i przekazuje żądania przychodzące do kontenera pod tym numerem portu. Aby odbierać żądania, aplikacja powinna nasłuchiwać portu określonego w zmiennej process.env.PORT . W poniższym przykładzie pokazano, jak ustawić port w prostej aplikacji Express:

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}`)
})

Dostosowywanie automatyzacji kompilacji

Jeśli wdrażasz aplikację przy użyciu usługi Git lub przy użyciu pakietów zip z włączoną automatyzacją kompilacji, automatyzacja kompilacji usługi App Service wykonuje następujące kroki:

Uruchom skrypt niestandardowy, jeśli został określony przez PRE_BUILD_SCRIPT_PATHelement .
Uruchom polecenie npm install bez żadnych flag. Ten krok obejmuje narzędzie npm preinstall i postinstall skrypty, a także instaluje devDependenciesprogram .
Uruchom polecenie npm run build , jeśli skrypt kompilacji został określony w pliku package.json .
Uruchom polecenie npm run build:azure , jeśli build:azure skrypt został określony w pliku package.json .
Uruchom skrypt niestandardowy, jeśli został określony przez POST_BUILD_SCRIPT_PATHelement .

Uwaga

Jak wspomniano w dokumentacji npm, skrypty o nazwie prebuild i postbuild są uruchamiane, odpowiednio, przed i po build, jeśli zostaną określone. Skrypty o nazwie preinstall i postinstall uruchamiane przed i po install, odpowiednio.

PRE_BUILD_COMMAND i POST_BUILD_COMMAND są zmiennymi środowiskowymi, które są domyślnie puste. Aby uruchomić polecenia przed kompilacją, zdefiniuj polecenie PRE_BUILD_COMMAND. Aby uruchomić polecenia po kompilacji, zdefiniuj polecenie POST_BUILD_COMMAND.

W poniższym przykładzie użyto dwóch zmiennych do określenia serii poleceń rozdzielonych przecinkami.

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"

Aby uzyskać informacje o dodatkowych zmiennych środowiskowych na potrzeby dostosowywania automatyzacji kompilacji, zobacz Konfiguracja Oryx.

Aby uzyskać więcej informacji na temat sposobu uruchamiania i kompilowania aplikacji Node.js w systemie Linux, zobacz dokumentację Oryx: Jak wykrywać i kompilować aplikacje Node.js.

Konfigurowanie serwera Node.js

Kontenery Node.js są dostarczane z PM2, menedżerem procesów produkcyjnych. Aplikację można skonfigurować tak, aby rozpoczynała się od pm2, za pomocą npm startpolecenia lub za pomocą polecenia niestandardowego.

Narzędzie	Cel
Uruchamianie za pomocą funkcji PM2	Zalecane. Użycie produkcyjne lub przejściowe. PM2 zapewnia kompleksową platformę do zarządzania aplikacjami.
Uruchamianie przy użyciu narzędzia npm start	Tylko do użytku programistycznego.
Uruchamianie za pomocą polecenia niestandardowego	Rozwój lub testowanie.

Uruchamianie za pomocą funkcji PM2

Kontener automatycznie uruchamia aplikację z pm2, gdy w projekcie znajduje się jeden z typowych plików Node.js:

bin/www
server.js
app.js
index.js
hostingstart.js
Jeden z następujących plików PM2: process.json lub ecosystem.config.js

Można również skonfigurować niestandardowy plik startowy z następującymi rozszerzeniami:

Plik .js
Plik PM2 z rozszerzeniem .json, .config.js, yaml lub .yml

Uwaga

W przypadku wersji Node.js po Node 14 LTS, kontener nie uruchamia automatycznie aplikacji z użyciem PM2. Aby uruchomić aplikację z pm2, ustaw polecenie uruchamiania na pm2 start <.js-file-or-PM2-file> --no-daemon. Pamiętaj, aby użyć argumentu --no-daemon, ponieważ PM2 musi działać w pierwszym planie kontenera, aby działać prawidłowo.

Aby dodać niestandardowy plik startowy, uruchom następujące polecenie w usłudze Cloud Shell:

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

Uruchamianie za pomocą polecenia niestandardowego

Usługa App Service może uruchomić aplikację przy użyciu polecenia niestandardowego, takiego jak plik wykonywalny, taki jak run.sh. Aby na przykład uruchomić npm run start:prodpolecenie , uruchom następujące polecenie w usłudze Cloud Shell:

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

Uruchamianie przy użyciu narzędzia npm start

Aby uruchomić aplikację za pomocą npm startpolecenia , upewnij się, że start skrypt znajduje się w pliku package.json . Na przykład:

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

Aby użyć niestandardowego package.json w projekcie, wykonaj następujące polecenie w Cloud Shell:

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

Debugowanie zdalne

Aplikację Node.js można debugować zdalnie w programie Visual Studio Code , jeśli skonfigurujesz ją do uruchamiania przy użyciu funkcji PM2, z wyjątkiem sytuacji, w której jest uruchamiana przy użyciu pliku.config.js, .yml lub yaml .

W większości przypadków nie jest wymagana żadna dodatkowa konfiguracja aplikacji. Jeśli aplikacja jest uruchamiana z plikiem process.json (domyślnym lub niestandardowym), to w katalogu głównym JSON musi mieć script właściwość. Na przykład:

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

Aby skonfigurować program Visual Studio Code na potrzeby zdalnego debugowania, zainstaluj rozszerzenie usługi App Service. Postępuj zgodnie z instrukcjami na stronie rozszerzenia i zaloguj się do platformy Azure w programie Visual Studio Code.

W Eksploratorze platformy Azure znajdź aplikację, którą chcesz debugować, kliknij ją prawym przyciskiem myszy, a następnie wybierz pozycję Rozpocznij debugowanie zdalne. Wybierz pozycję Tak , aby włączyć zdalne debugowanie dla aplikacji. Usługa App Service uruchamia serwer proxy tunelu i dołącza debuger. Następnie możesz wysyłać żądania do aplikacji i zobaczyć, jak debuger zatrzymuje się na punktach przerwania.

Po zakończeniu debugowania zatrzymaj debuger, wybierając pozycję Rozłącz. Po wyświetleniu monitu wybierz pozycję Tak , aby wyłączyć debugowanie zdalne. Aby wyłączyć ją później, ponownie kliknij aplikację prawym przyciskiem myszy w eksploratorze platformy Azure i wybierz polecenie Wyłącz debugowanie zdalne.

Uzyskiwanie dostępu do zmiennych środowiskowych

W usłudze App Service można określić ustawienia aplikacji poza kodem aplikacji. Następnie możesz uzyskać do nich dostęp przy użyciu standardowego wzorca Node.js. Aby na przykład uzyskać dostęp do ustawienia aplikacji o nazwie NODE_ENV, użyj następującego kodu:

process.env.NODE_ENV

Run Grunt/Bower/Gulp

Domyślnie automatyzacja kompilacji usługi App Service jest uruchamiana npm install --production po rozpoznaniu, że aplikacja Node.js jest wdrażana za pośrednictwem usługi Git lub za pośrednictwem wdrożenia zip z włączoną automatyzacją kompilacji. Jeśli aplikacja wymaga dowolnego z popularnych narzędzi automatyzacji, takich jak Grunt, Bower lub Gulp, musisz podać niestandardowy skrypt wdrożenia, aby go uruchomić.

Aby umożliwić repozytorium uruchamianie tych narzędzi, należy dodać je do zależności w package.json. Na przykład:

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

W lokalnym oknie terminalu zmień katalog na katalog główny repozytorium i uruchom następujące polecenia:

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

Katalog główny repozytorium ma teraz dwa dodatkowe pliki: .deployment i deploy.sh.

Otwórz deploy.sh i znajdź sekcję Deployment , która wygląda następująco:

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

Na końcu tej sekcji npm install --production zostanie uruchomiona. Dodaj sekcję kodu potrzebną do uruchomienia wymaganego narzędzia na końcu sekcji Deployment.

Bower
Łyk
Grunt

Przykład można znaleźć w przykładzie MEAN.js. W tym przykładzie skrypt wdrażania uruchamia również polecenie niestandardowe npm install .

Bower

Ten fragment kodu uruchamia polecenie 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

Łyk

Ten fragment kodu uruchamia polecenie 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

Grunt

Ten fragment kodu uruchamia polecenie grunt.

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

Wykrywanie sesji protokołu HTTPS

W usłudze App Service zakończenie protokołu TLS/SSL odbywa się w modułach równoważenia obciążenia sieciowego, więc wszystkie żądania HTTPS docierają do aplikacji jako niezaszyfrowane żądania HTTP. Jeśli logika aplikacji musi sprawdzić, czy żądania użytkownika są szyfrowane, sprawdź X-Forwarded-Proto nagłówek.

Popularne platformy internetowe umożliwiają dostęp do informacji X-Forwarded-* w standardowym wzorcu aplikacji. W programie Express można używać zaufanych proxy. Na przykład:

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

Uzyskiwanie dostępu do dzienników diagnostycznych

Aby uzyskać dostęp do dzienników konsoli wygenerowanych z poziomu kodu aplikacji w usłudze App Service, włącz rejestrowanie diagnostyczne, uruchamiając następujące polecenie w usłudze Cloud Shell:

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

Możliwe wartości to --levelError, Warning, Infoi Verbose. Każdy kolejny poziom obejmuje poprzedni poziom. Na przykład Error zawiera tylko komunikaty o błędach. Verbose zawiera wszystkie komunikaty.

Po włączeniu rejestrowania diagnostycznego uruchom następujące polecenie, aby wyświetlić strumień dziennika:

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

Jeśli dzienniki konsoli nie są wyświetlane natychmiast, sprawdź ponownie w ciągu 30 sekund.

Aby zatrzymać strumieniowanie logów w dowolnym momencie, naciśnij Ctrl+C.

Dostęp do dzienników konsoli generowanych z poziomu kontenera można uzyskać.

Aby włączyć rejestrowanie kontenerów, uruchom następujące polecenie:

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

Zastąp wartości <app-name> i <resource-group-name> nazwami odpowiednimi dla swojej aplikacji internetowej.

Po włączeniu rejestrowania kontenerów uruchom następujące polecenie, aby wyświetlić strumień dziennika:

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

Jeśli dzienniki konsoli nie są wyświetlane natychmiast, sprawdź ponownie w ciągu 30 sekund.

Aby zatrzymać przesyłanie strumieniowe dzienników w dowolnym momencie, użyj skrótu klawiaturowego Ctrl+C.

Ponowne zapisywanie adresów URL

Podczas wdrażania aplikacji Node.js w usłudze Azure App Service dla systemu Linux może być konieczna obsługa przepisywania adresów URL bezpośrednio w aplikacji. Ta konfiguracja jest szczególnie przydatna do zapewnienia, że określone wzorce adresów URL są przekierowywane do poprawnych punktów końcowych bez konieczności polegania na konfiguracjach serwera internetowego. Istnieje kilka sposobów na ponowne zapisywanie adresów URL w Node.js. Jednym z przykładów jest użycie pakietu express-urlrewrite .

Monitorowanie aplikacji przy użyciu usługi Application Insights

Usługa Application Insights umożliwia monitorowanie wydajności, wyjątków i użycia aplikacji bez wprowadzania żadnych zmian w kodzie. Aby dołączyć agenta usługi Application Insights, przejdź do aplikacji internetowej w portalu, wybierz pozycję Application Insights w obszarze Monitorowanie, a następnie wybierz pozycję Włącz usługę Application Insights. Następnie wybierz istniejący zasób usługi Application Insights lub utwórz nowy. Na koniec wybierz pozycję Zastosuj w dolnej części strony. Aby instrumentować aplikację internetową przy użyciu programu PowerShell, zobacz te instrukcje.

Ten agent będzie monitorować aplikację Node.js po stronie serwera. Aby monitorować kod JavaScript po stronie klienta, dodaj zestaw SDK języka JavaScript do projektu.

Aby uzyskać więcej informacji, zobacz Włączanie monitorowania aplikacji w usłudze Azure App Service dla platformy .NET, Node.js, Python i aplikacji Java.

Rozwiązywanie problemów

Jeśli działająca aplikacja Node.js działa inaczej w usłudze App Service lub ma błędy, spróbuj wykonać następujące czynności:

Uzyskaj dostęp do strumienia dziennika.
Przetestuj aplikację lokalnie w trybie produkcyjnym. Usługa App Service uruchamia aplikacje Node.js w trybie produkcyjnym, dlatego należy upewnić się, że projekt działa zgodnie z oczekiwaniami w trybie produkcyjnym lokalnie. Na przykład:
- W zależności od pliku package.json, różne pakiety mogą być instalowane w trybie produkcyjnym (dependencies w stosunku do devDependencies).
- Niektóre struktury internetowe mogą wdrażać pliki statyczne inaczej w trybie produkcyjnym.
- Niektóre struktury internetowe mogą używać niestandardowych skryptów uruchamiania podczas uruchamiania w trybie produkcyjnym.
Uruchom aplikację w usłudze App Service w trybie programowania. Na przykład w MEAN.js możesz ustawić aplikację na tryb programowania w czasie wykonywania, ustawiając NODE_ENV ustawienie aplikacji.

Nie masz uprawnień do wyświetlania tego katalogu lub strony

Po wdrożeniu kodu Node.js w natywnej aplikacji systemu Windows w usłudze App Service może zostać wyświetlony komunikat You do not have permission to view this directory or page w przeglądarce po przejściu do adresu URL aplikacji. Ten błąd najprawdopodobniej występuje, ponieważ nie masz plikuweb.config . (Zobacz szablon i przykład).

Jeśli wdrażasz pliki przy użyciu usługi Git lub przy użyciu wdrożenia ZIP z włączoną automatyzacją kompilacji, aparat wdrażania generuje plik web.config w katalogu głównym aplikacji internetowej (%HOME%\site\wwwroot), jeśli spełniony jest jeden z następujących warunków:

Katalog główny projektu zawiera plik package.json , który definiuje start skrypt zawierający ścieżkę pliku JavaScript.
Katalog główny projektu zawiera server.js lub plik app.js .

Wygenerowany plik web.config jest dostosowany do wykrytego skryptu uruchamiania. W przypadku innych metod wdrażania ręcznie dodaj plik web.config . Upewnij się, że plik jest poprawnie sformatowany.

Jeśli używasz wdrożenia ZIP (na przykład za pośrednictwem programu Visual Studio Code), pamiętaj o włączeniu automatyzacji kompilacji. Nie jest ona domyślnie włączona. az webapp up używa wdrożenia ZIP z włączoną automatyzacją kompilacji.

Ignoruj komunikat robots933456 w logach

W dziennikach kontenera może zostać wyświetlony następujący komunikat:

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

Możesz bezpiecznie zignorować ten komunikat. /robots933456.txt to fikcyjna ścieżka adresu URL. Usługa App Service używa jej do sprawdzania, czy kontener może obsługiwać żądania. Odpowiedź błędu "404" wskazuje, że ścieżka nie istnieje i sygnalizuje usłudze App Service, że kontener jest w dobrej kondycji i gotowy do odpowiadania na żądania.

Samouczek: aplikacja Node.js z bazą danych MongoDB

Azure App Service on Linux FAQ (Usługa Azure App Service w systemie Linux — często zadawane pytania)

Odniesienie do zmiennych środowiskowych i ustawień aplikacji

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-09-09

Udostępnij za pomocą

Konfigurowanie aplikacji Node.js dla usługi Azure App Service

Pokaż wersję Node.js

Ustawianie wersji Node.js

Co się stanie z nieaktualnymi środowiskami uruchomieniowymi w usłudze App Service?

Ustawianie numeru portu

Dostosowywanie automatyzacji kompilacji

Konfigurowanie serwera Node.js

Uruchamianie za pomocą funkcji PM2

Uruchamianie za pomocą polecenia niestandardowego

Uruchamianie przy użyciu narzędzia npm start

Debugowanie zdalne

Uzyskiwanie dostępu do zmiennych środowiskowych

Run Grunt/Bower/Gulp

Bower

Łyk

Grunt

Wykrywanie sesji protokołu HTTPS

Uzyskiwanie dostępu do dzienników diagnostycznych

Ponowne zapisywanie adresów URL

Monitorowanie aplikacji przy użyciu usługi Application Insights

Rozwiązywanie problemów

Nie masz uprawnień do wyświetlania tego katalogu lub strony

Ignoruj komunikat robots933456 w logach

Treści powiązane

Sprzężenie zwrotne

Dodatkowe zasoby