Azure App Service용 Node.js 앱 구성

2025-09-09

Node.js 앱을 모든 필수 NPM 종속성과 함께 배포해야 합니다. App Service 배포 엔진은 Git 리포지토리를 배포하거나 빌드 자동화를 사용하도록 설정된 Zip 패키지를 배포할 때 자동으로 실행됩니다npm install --production. 그러나 FTP/S를 사용하여 파일을 배포하는 경우 필요한 패키지를 수동으로 업로드해야 합니다.

이 문서에서는 주요 개념을 설명하고 App Service에 배포하는 Node.js 개발자를 위한 지침을 제공합니다. Azure App Service를 사용한 적이 없는 경우 Node.js 빠른 시작 및 MongoDB 자습서를 사용하여Node.js 먼저 완료합니다.

Node.js 버전 표시

현재 Node.js 버전을 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

지원되는 Node.js 버전을 모두 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

현재 Node.js 버전을 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

지원되는 Node.js 버전을 모두 표시하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

Node.js 버전 설정

앱을 지원되는 Node.js 버전으로 설정하려면 Cloud Shell에서 다음 명령을 실행하여 WEBSITE_NODE_DEFAULT_VERSION을 지원되는 버전으로 설정합니다.

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

참고 항목

이 예제에서는 권장되는 타일드 구문을 사용하여 App Service에서 Node.js 16 런타임의 사용 가능한 최신 버전을 대상으로 합니다.

런타임은 플랫폼에서 정기적으로 패치 및 업데이트되므로 특정 부 버전/패치를 대상으로 지정하지 않는 것이 좋습니다. 잠재적인 보안 위험으로 인해 이러한 버전을 사용할 수 있다고 보장되지는 않습니다.

참고 항목

프로젝트의 package.json에서 Node.js 버전을 설정해야 합니다. 배포 엔진은 지원되는 모든 Node.js 버전을 포함하는 별도의 프로세스에서 실행됩니다.

앱을 지원되는 Node.js 버전으로 설정하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

이 설정은 런타임에 또한 Kudu에서 자동화된 패키지 복원 시에 사용할 Node.js 버전을 지정합니다.

참고 항목

프로젝트의 package.json에서 Node.js 버전을 설정해야 합니다. 배포 엔진은 지원되는 모든 Node.js 버전을 포함하는 별도의 컨테이너에서 실행됩니다.

App Service에서 오래된 런타임은 어떻게 되나요?

오래된 런타임은 유지 관리 조직에서 더 이상 사용되지 않거나 심각한 취약성이 있습니다. 따라서 포털의 만들기 및 구성 페이지에서 제거됩니다. 오래된 런타임이 포털에서 숨겨지면 해당 런타임을 계속 사용하는 모든 앱이 계속 실행됩니다.

더 이상 포털에 표시되지 않는 오래된 런타임 버전으로 앱을 만들려면 Azure CLI, ARM 템플릿 또는 Bicep을 사용합니다. 이러한 배포 대안을 사용하면 포털에서 제거되었지만 여전히 지원되는 사용되지 않는 런타임을 만들 수 있습니다.

런타임이 App Service 플랫폼에서 완전히 제거된 경우 Azure 구독 소유자는 제거 전에 이메일 알림을 받습니다.

포트 번호 설정

들어오는 요청을 수신하려면 Node.js 앱이 올바른 포트를 수신 대기해야 합니다.

Windows의 App Service에서 Node.js 앱은 IISNode를 사용하여 호스트되고 Node.js 앱은 process.env.PORT 변수에 지정된 포트를 수신 대기해야 합니다. 다음 예제에서는 간단한 Express 앱에서 포트를 설정하는 방법을 보여줍니다.

App Service는 Node.js 컨테이너의 환경 변수 PORT 를 설정하고 들어오는 요청을 해당 포트 번호의 컨테이너에 전달합니다. 요청을 받으려면 앱이 변수에 지정된 process.env.PORT 포트를 수신 대기해야 합니다. 다음 예제에서는 간단한 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}`)
})

빌드 자동화 사용자 지정

Git을 사용하거나 빌드 자동화를 사용하도록 설정된 zip 패키지를 사용하여 앱을 배포하는 경우 App Service 빌드 자동화는 다음 단계를 완료합니다.

로 지정된 경우 사용자 지정 스크립트를 PRE_BUILD_SCRIPT_PATH실행합니다.
플래그 없이 실행 npm install 합니다. 이 단계에는 npm preinstall 및 postinstall 스크립트가 포함되며 설치도 포함됩니다 devDependencies.
빌드 스크립트가 package.json 파일에 지정된 경우 실행 npm run build 합니다.
스크립트 가 build:azurepackage.json파일에 지정된 경우 실행 npm run build:azure 합니다.
로 지정된 경우 사용자 지정 스크립트를 POST_BUILD_SCRIPT_PATH실행합니다.

참고 항목

npm docs에 설명된 것처럼 prebuild 및 postbuild라는 스크립트가 지정된 경우 각각 build 전후에 실행됩니다. 각각 이전과 후에 install명명 preinstall 되고 postinstall 실행되는 스크립트입니다.

PRE_BUILD_COMMAND 및 POST_BUILD_COMMAND는 기본적으로 비어 있는 환경 변수입니다. 빌드 전 명령을 실행하려면 PRE_BUILD_COMMAND를 정의합니다. 빌드 후 명령을 실행하려면 POST_BUILD_COMMAND를 정의합니다.

다음 예제에서는 두 변수를 사용하여 쉼표로 구분되는 일련의 명령을 지정합니다.

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"

빌드 자동화를 사용자 지정하기 위한 추가 환경 변수에 대한 자세한 내용은 Oryx 구성을 참조하세요.

App Service를 실행하고 Linux에서 Node.js 앱을 빌드하는 방법에 대한 자세한 내용은 Oryx 설명서: Node.js 앱을 인식하고 구축하는 방법을 참조하세요.

Node.js 서버 구성

Node.js 컨테이너는 프로덕션 프로세스 관리자인 PM2와 함께 제공됩니다. PM2 또는 npm start사용자 지정 명령을 사용하여 시작하도록 앱을 구성할 수 있습니다.

도구	목적
PM2를 사용하여 실행	권장합니다. 프로덕션 또는 스테이징 사용. PM2는 전체 서비스 앱 관리 플랫폼을 제공합니다.
npm start로 실행	개발 용도로만 사용합니다.
사용자 지정 명령으로 실행	개발 또는 스테이징 중 하나.

PM2를 사용하여 실행

이 컨테이너는 일반적인 Node.js 파일 중 하나가 프로젝트에 있는 경우 PM2를 사용하여 앱을 자동으로 시작합니다.

bin/www
server.js
app.js
index.js
hostingstart.js
다음 PM2 파일 중 하나: process.json 또는 ecosystem.config.js

다음 확장명을 사용하여 사용자 지정 시작 파일을 구성할 수도 있습니다.

.js 파일
확장.json, .config.js, .yaml 또는 .yml 있는 PM2 파일

참고 항목

노드 14 LTS부터 컨테이너는 PM2로 앱을 자동으로 시작하지 않습니다. PM2로 앱을 시작하려면 시작 명령을 pm2 start <.js-file-or-PM2-file> --no-daemon(으)로 설정합니다. 컨테이너가 제대로 작동하려면 PM2가 전경에서 실행되어야 하므로 --no-daemon 인수를 사용해야 합니다.

사용자 지정 시작 파일을 추가하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

사용자 지정 명령을 사용하여 실행

App Service는 run.sh 같은 실행 파일과 같은 사용자 지정 명령을 사용하여 앱을 시작할 수 있습니다. 예를 들어 실행 npm run start:prod하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

npm start로 실행

앱을 npm start시작하려면 스크립트가 startpackage.json 파일에 있는지 확인합니다. 예시:

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

프로젝트에서 사용자 지정 package.json을 사용하려면 Cloud Shell에서 다음 명령을 실행합니다.

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

원격 디버깅

.config.js, .yml 또는 .yaml 파일을 사용하여 실행하는 경우를 제외하고 PM2로 실행하도록 구성하는 경우 Visual Studio Code에서 Node.js 앱을 원격으로 디버그할 수 있습니다.

대부분의 경우 앱에 대한 추가 구성이 필요하지 않습니다. 앱이 process.json 파일(기본 또는 사용자 지정)을 사용하여 실행되는 경우 JSON 루트에 script 속성이 있어야 합니다. 예시:

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

Visual Studio Code에서 원격 디버깅을 설정하려면 App Service 확장을 설치합니다. 확장 페이지의 지침에 따라 Visual Studio Code에서 Azure에 로그인합니다.

Azure 탐색기에서 디버그할 앱을 찾아 마우스 오른쪽 단추로 클릭한 다음 원격 디버깅 시작을 선택합니다. 예를 선택하여 앱에 대한 원격 디버깅을 사용하도록 설정합니다. App Service는 터널 프록시를 시작하고 디버거를 연결합니다. 그런 다음 앱에 대한 요청을 수행하면 디버거가 중단점에서 일시 중지되는 것을 볼 수 있습니다.

디버깅을 마쳤으면 연결 끊기를 선택하여 디버거를 중지합니다. 메시지가 표시되면 예를 선택하여 원격 디버깅을 사용하지 않도록 설정해야 합니다. 나중에 사용하지 않도록 설정하려면 Azure 탐색기에서 앱을 다시 마우스 오른쪽 단추로 클릭하고 원격 디버깅 사용 안 함을 선택합니다.

환경 변수에 액세스

App Service에서, 앱 코드 외부에서 앱 설정을 지정할 수 있습니다. 그런 다음 표준 Node.js 패턴을 사용하여 액세스할 수 있습니다. 예를 들어 앱 설정 NODE_ENV에 액세스하려면 다음 코드를 사용합니다.

process.env.NODE_ENV

Grunt/Bower/Gulp 실행

기본적으로 App Service 빌드 자동화는 빌드 자동화를 사용하도록 설정된 Git 또는 Zip 배포를 통해 Node.js 앱이 배포되었음을 인식할 때 실행됩니다npm install --production. 앱이 Grunt, Bower 또는 Gulp와 같은 인기 있는 자동화 도구를 필요로 하는 경우 이를 실행하려면 사용자 지정 배포 스크립트를 제공하여 실행해야 합니다.

리포지토리에서 이러한 도구를 실행할 수 있도록 하려면 package.json.의 종속성에 추가해야 합니다. 예를 들어:

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

로컬 터미널 창에서 디렉터리를 리포지토리 루트로 변경하고 다음 명령을 실행합니다.

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

이제 리포지토리 루트에 .deployment 및 deploy.sh라는 두 개의 추가 파일이 있습니다.

deploy.sh를 열고 다음과 같은 Deployment 섹션을 찾습니다.

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

이 섹션 npm install --production 의 끝에서 실행됩니다. 필요한 도구를 실행하는 데 필요한 코드 섹션을 섹션의 '끝'에 추가합니다.

바우어
Gulp
으르렁거림

예제는 MEAN.js 샘플을 참조하세요. 이 샘플에서 배포 스크립트는 사용자 지정 npm install 명령도 실행합니다.

바우어

이 코드 조각은 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 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를 실행합니다.

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

HTTPS 세션 검색

App Service에서 TLS/SSL 종료 는 네트워크 부하 분산 장치에서 발생하므로 모든 HTTPS 요청이 암호화되지 않은 HTTP 요청으로 앱에 도달합니다. 앱 논리가 사용자 요청이 암호화되었는지 확인해야 하는 경우 헤더를 검사합니다 X-Forwarded-Proto .

인기 있는 웹 프레임워크를 사용하여 표준 앱 패턴의 X-Forwarded-* 정보에 액세스할 수 있습니다. Express에서는 신뢰 프록시를 사용할 수 있습니다. 예시:

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

진단 로그 액세스

App Service의 애플리케이션 코드 내에서 생성된 콘솔 로그에 액세스하려면 Cloud Shell에서 다음 명령을 실행하여 진단 로깅을 설정합니다.

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

가능한 값 --level 은 Error, Warning, Info및 Verbose. 각 후속 수준에는 이전 수준이 포함됩니다. 예를 들어 Error 오류 메시지만 포함합니다. Verbose 에는 모든 메시지가 포함됩니다.

진단 로깅을 켠 후 다음 명령을 실행하여 로그 스트림을 확인합니다.

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

콘솔 로그가 즉시 나타나지 않으면 30초 후에 다시 확인합니다.

언제든지 로그 스트리밍을 중지하려면 Ctrl+를 선택합니다.

컨테이너 내부에서 생성된 콘솔 로그에 액세스할 수 있습니다.

컨테이너 로깅을 켜려면 다음 명령을 실행합니다.

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

<app-name>과 <resource-group-name>을 웹앱에 적절한 이름으로 바꿉니다.

컨테이너 로깅을 켠 후 다음 명령을 실행하여 로그 스트림을 확인합니다.

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

콘솔 로그가 즉시 나타나지 않으면 30초 후에 다시 확인합니다.

언제든지 로그 스트리밍을 중지하려면 Ctrl+를 선택합니다.

URL 다시 쓰기

Linux용 Azure App Service에 Node.js 앱을 배포할 때 애플리케이션 내에서 직접 URL 다시 쓰기를 처리해야 할 수 있습니다. 이 구성은 웹 서버 구성을 사용하지 않고 특정 URL 패턴이 올바른 엔드포인트로 리디렉션되도록 하는 데 특히 유용합니다. Node.js에서 URL 다시 쓰기를 수행하는 방법에는 여러 가지가 있습니다. 한 가지 예는 express-urlrewrite 패키지를 사용하는 것입니다.

Application Insights를 사용하여 앱 모니터링

Application Insights를 사용하면 코드를 변경하지 않고도 애플리케이션의 성능, 예외 및 사용을 모니터링할 수 있습니다. Application Insights 에이전트를 연결하려면 포털에서 웹앱으로 이동하여 모니터링 아래에서 Application Insights를 선택한 다음 Application Insights 켜기를 선택합니다. 다음으로, 기존 Application Insights 리소스를 선택하거나 새 리소스를 만듭니다. 마지막으로 페이지 아래쪽에서 적용 을 선택합니다. PowerShell을 사용하여 웹앱을 계측하려면 다음 지침을 참조하세요.

이 에이전트는 서버 쪽 Node.js 애플리케이션을 모니터링합니다. 클라이언트 쪽 JavaScript를 모니터링하려면 JavaScript SDK를 프로젝트에 추가합니다.

자세한 내용은 .NET, Node.js, Python 및 Java 애플리케이션용 Azure App Service에서 애플리케이션 모니터링 사용을 참조하세요.

문제 해결

작동하는 Node.js 앱이 App Servce에서 다르게 동작하거나 오류가 발생할 경우 다음의 방법을 시도해보세요.

로그 스트림에 액세스합니다.
프로덕션 모드에서 로컬 상태로 앱을 테스트합니다. App Service가 프로덕션 모드에서 Node.js 앱을 실행하므로 프로젝트가 프로덕션 모드에서 로컬 상태로 예상과 같이 작동하는지 확인해야 합니다. 예:
- package.json에 따라, 프로덕션 모드에서 다른 패키지가 설치될 수 있습니다(dependencies vs. devDependencies).
- 특정 웹 프레임워크는 프로덕션 모드에서 다른 고정 파일을 배포할 수 있습니다.
- 특정 웹 프레임워크는 프로덕션 모드에서 실행될 때 사용자 지정 시작 스크립트를 사용합니다.
App Service에서 앱을 개발 모드로 실행합니다. 예를 들어 MEAN.js에서는 NODE_ENV 앱 설정을 설정하여 런타임 시 앱을 개발 모드로 설정할 수 있습니다.

이 디렉터리 또는 페이지를 볼 수 있는 권한이 없습니다

App Service에서 네이티브 Windows 앱에 Node.js 코드를 배포한 후 앱의 URL로 이동하면 브라우저에 메시지가 You do not have permission to view this directory or page 표시될 수 있습니다. 이 오류는 web.config 파일이 없기 때문에 발생할 가능성이 높습니다. (템플릿 및 예제를 참조하세요.)

Git을 사용하거나 빌드 자동화를 사용하도록 설정된 ZIP 배포를 사용하여 파일을 배포 하는 경우 다음 조건 중 하나가 충족되면 배포 엔진은 앱의 웹 루트(%HOME%\site\wwwroot)에web.config파일을 자동으로 생성합니다.

프로젝트 루트에는 JavaScript 파일의 경로가 포함된 스크립트를 start 정의하는 package.json 파일이 포함되어 있습니다.
프로젝트 루트는 server.js 또는 app.js 파일을 포함합니다.

생성된 web.config 파일은 검색된 시작 스크립트에 맞게 조정됩니다. 다른 배포 방법의 경우 web.config 파일을 수동으로 추가합니다. 파일의 형식이 올바르게 지정되었는지 확인합니다.

예를 들어 Visual Studio Code를 통해 ZIP 배포 를 사용하는 경우 빌드 자동화를 사용하도록 설정해야 합니다. 기본적으로 사용하지 않도록 설정됩니다. az webapp up은(는) 빌드 자동화를 사용하도록 설정된 ZIP 배포를 사용합니다.

로그에서 robots933456 메시지 무시

컨테이너 로그에 다음 메시지가 표시될 수 있습니다.

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

이 메시지는 무시해도 괜찮습니다. /robots933456.txt는 App Service에서 컨테이너가 요청을 처리할 수 있는지 확인하기 위해 사용하는 더미 URL 경로입니다. 404 응답은 경로가 존재하지 않음을 나타내며, 컨테이너가 정상이며 요청에 응답할 준비가 되었음을 App Service에 알릴 수 있습니다.

자습서: MongoDB를 사용하는 Linux Node.js 앱

Linux의 Azure App Service에 대한 FAQ.

환경 변수 및 앱 설정 참조

피드백

이 페이지가 도움이 되었나요?

다음을 통해 공유

Azure App Service용 Node.js 앱 구성

Node.js 버전 표시

Node.js 버전 설정

App Service에서 오래된 런타임은 어떻게 되나요?

포트 번호 설정

빌드 자동화 사용자 지정

Node.js 서버 구성

PM2를 사용하여 실행

사용자 지정 명령을 사용하여 실행

npm start로 실행

원격 디버깅

환경 변수에 액세스

Grunt/Bower/Gulp 실행

바우어

꿀꺽

끙끙

HTTPS 세션 검색

진단 로그 액세스

URL 다시 쓰기

Application Insights를 사용하여 앱 모니터링

문제 해결

이 디렉터리 또는 페이지를 볼 수 있는 권한이 없습니다

로그에서 robots933456 메시지 무시

관련 콘텐츠

피드백

추가 리소스