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

2025-05-04

Node.js aplikacje muszą być wdrażane ze wszystkimi wymaganymi zależnościami npm. Silnik wdrażania usługi App Service uruchamia automatycznie npm install --production za Ciebie 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.

Ten przewodnik zawiera kluczowe pojęcia i instrukcje dla deweloperów Node.js, którzy wdrażają w usłudze App Service. Jeśli nigdy nie korzystałeś z usługi Azure App Service, najpierw zapoznaj się z szybkim startem Node.js oraz z samouczkiem Node.js z 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="~16"

Uwaga

W tym przykładzie użyto zalecanej składni "tyldy", aby kierować do najnowszej dostępnej wersji środowiska uruchomieniowego Node.js 16 w usłudze App Service.

Ponieważ środowisko uruchomieniowe jest regularnie poprawiane i aktualizowane przez platformę, nie zalecamy wybierania konkretnej wersji pobocznej/poprawki, ponieważ ich dostępność nie jest gwarantowana ze względu na potencjalne zagrożenia bezpieczeństwa.

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|14-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ą wycofywane przez organizację nadzorującą 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. Alternatywy wdrażania umożliwiają tworzenie zdeprecjonowanych środowisk uruchomieniowych, które zostały usunięte 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.

Uzyskiwanie 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 to zrobić 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 otrzymywać żądania, aplikacja powinna nasłuchiwać tego portu przy użyciu polecenia process.env.PORT. W poniższym przykładzie pokazano, jak to zrobić 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, procedura automatyzacji kompilacji usługi App Service przebiega przez następującą sekwencję:

Uruchom skrypt niestandardowy, jeśli został określony przez PRE_BUILD_SCRIPT_PATHelement .
Uruchom npm install bez żadnych flag, co obejmuje npm preinstall i skrypty postinstall, a także instaluje devDependencies.
Uruchom polecenie npm run build , jeśli skrypt kompilacji został określony w package.json.
Uruchom polecenie npm run build:azure , jeśli skrypt build:azure został określony w package.json.
Uruchom niestandardowy skrypt, jeśli jest określony przez POST_BUILD_SCRIPT_PATH.

Uwaga

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

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, aby określić serię 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 w celu dostosowania 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, przy użyciu npm start 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

Począwszy od Node.js 14 LTS, kontener nie uruchamia automatycznie aplikacji za pomocą 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ć twoją aplikację przy użyciu niestandardowego polecenia, takiego jak plik wykonywalny run.sh. Aby na przykład uruchomić npm run start:prod, wykonaj następujące polecenie w 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ę przy użyciu polecenia npm start, 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

Możesz debugować aplikację Node.js zdalnie w programie Visual Studio Code , jeśli skonfigurujesz ją do uruchamiania przy użyciu funkcji PM2, z wyjątkiem sytuacji, gdy jest uruchamiana przy użyciu .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 i wybierz polecenie Rozpocznij debugowanie zdalne. Wybierz pozycję Tak , aby włączyć zdalne debugowanie dla aplikacji. Usługa App Service uruchamia dla Ciebie serwer proxy tunelu i przyłą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
# ----------

Ta sekcja kończy się uruchomieniem polecenia npm install --production. Dodaj sekcję kodu potrzebną do uruchomienia wymaganego narzędzia na końcu sekcji Deployment.

Bower
Łyk
Grunt

Zobacz przykład w przykładzie MEAN.js, w którym skrypt wdrażania uruchamia również polecenie niestandardowenpm 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

ziemia

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 kończenie żądań 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.

Można uzyskać dostęp do dzienników konsoli wygenerowanych wewnątrz kontenera.

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 <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ć strumieniowanie logów w dowolnym momencie, naciśnij 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. Jest to szczególnie przydatne w przypadku zapewnienia przekierowania określonych wzorców adresów URL do poprawnych punktów końcowych bez polegania na konfiguracjach serwera internetowego. Istnieje kilka sposobów na ponowne zapisywanie adresów URL w Node.js. Przykładem jest pakiet express-urlrewrite .

Monitorowanie za pomocą 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 Ustawienia, 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 u dołu. Aby instrumentować aplikację internetową przy użyciu programu PowerShell, zapoznaj się z tymi instrukcjami

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 informacje o wersji rozszerzenia usługi Application Insights.

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 podczas przechodzenia do adresu URL aplikacji. Jest to najprawdopodobniej spowodowane tym, że nie masz pliku web.config . (Zobacz szablon i przykład).

Jeśli pliki są wdrażane 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 sieci Web aplikacji (%HOME%\site\wwwroot), jeśli jeden z następujących warunków jest spełniony:

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

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

Jeśli używasz wdrożenia ZIP (na przykład za pomocą programu Visual Studio Code), pamiętaj, aby włączyć automatyzację 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 jest fikcyjną ścieżką adresu URL, za pomocą której usługa App Service sprawdza, czy kontener jest w stanie obsługiwać żądania. Odpowiedź 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.

Następne kroki

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)

Możesz też zapoznać się z dodatkowymi zasobami:

Odniesienie do zmiennych środowiskowych i ustawień aplikacji

Udostępnij za pośrednictwem

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?

Uzyskiwanie 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

ziemia

Wykrywanie sesji protokołu HTTPS

Uzyskiwanie dostępu do dzienników diagnostycznych

Ponowne zapisywanie adresów URL

Monitorowanie za pomocą usługi Application Insights

Rozwiązywanie problemów

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

Ignoruj komunikat robots933456 w logach

Następne kroki

Opinia

Dodatkowe zasoby