為 Azure App Service 設定 Node.js 應用程式

Node.js 應用程式必須連同所有必要的 NPM 相依性一起部署。 當您部署 Git 存放庫已啟用組建自動化的Zip 封裝時,App Service 部署引擎會自動為您執行 npm install --production。 不過,如果您使用 FTP/S 來部署檔案,則需要手動上傳必要的封裝。

本指南針對負責部署至 App Service 的 Node.js 開發人員,提供重要概念和指示。 如果您從未使用過 Azure App Service,請先遵循 Node.js 快速入門Node.js 搭配 MongoDB 教學課程

顯示 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 版本,請巡覽至 https://<sitename>.scm.azurewebsites.net/api/diagnostics/runtime,或在 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 版本。

取得連接埠號碼

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 組建自動化會依下列順序逐步執行:

  1. 執行自訂指令碼 (如果 PRE_BUILD_SCRIPT_PATH 已指定)。
  2. 執行 npm install 但不指定任何旗標,其中包括 npm preinstallpostinstall 指令碼,還會安裝 devDependencies
  3. 如果 package.json 中指定 build 指令碼,則執行 npm run build
  4. 如果 package.json 中指定 build:azure 指令碼,則執行 npm run build:azure
  5. 執行自訂指令碼 (如果 POST_BUILD_SCRIPT_PATH 已指定)。

注意

npm 文件所述,名為 prebuildpostbuild 的指令碼 (如果指定) 分別在 build 之前和之後執行。 preinstallpostinstall 分別在 install 之前和之後執行。

PRE_BUILD_COMMANDPOST_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 或自訂命令啟動。

工具 目的
使用 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 或 .ymlPM2 檔案

注意

Node 14 LTS 開始,容器不會自動以 PM2 啟動應用程式。 若要以 PM2 啟動應用程式,請將啟動命令設定為 pm2 start <.js-file-or-PM2-file> --no-daemon。 請務必使用 --no-daemon 引數,因為 PM2 必須在前景執行,容器才能正常運作。

若要新增自訂啟動檔案,請在 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 啟動應用程式,請確定 package.json 檔案中有 start 指令碼。 例如:

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

若要在專案中使用自訂 package.json,請在 Cloud Shell 中執行下列命令:

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

遠端偵錯

注意

遠端偵錯目前為預覽版。

如果您將 Node.js 應用程式設為使用 PM2 執行,即可在 Visual Studio Code 中遠端偵錯此應用程式,但使用 .config.js,.yml 或 .yaml 執行時此應用程式時除外。

在大部分情況下,應用程式不需要額外的設定。 如果應用程式以 process.json 檔案執行 (預設或自訂),JSON 根中必須有 script 屬性。 例如:

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

若要設定 Visual Studio Code 來支援遠端偵錯,請安裝 App Service 延伸模組。 遵循延伸模組頁面上的指示,在 Visual Studio Code 中登入 Azure。

在 Azure 總管中,尋找您要偵錯的應用程式,以滑鼠右鍵按一下應用程式並選取 [啟動遠端偵錯]。 按一下 [是],對應用程式啟用此功能。 App Service 會為您啟動通道 Proxy,並附加偵錯工具。 接著,您可以對應用程式提出要求,並看到偵錯工具在中斷點暫停。

完成偵錯之後,選取 [中斷連線] 以停止偵錯工具。 出現提示時,您應該按一下 [是] 以停用遠端偵錯。 若要稍後停用,請在 Azure 總管中再次以滑鼠右鍵按一下應用程式,然後選取 [停用遠端偵錯]

存取環境變數

在 App Service 中,您可以於應用程式的程式碼外部設定應用程式設定。 然後,您可以使用標準 Node.js 模式來存取這些設定。 例如,若要存取稱為 NODE_ENV 的應用程式設定,請使用下列程式碼:

process.env.NODE_ENV

執行 Grunt/Bower/Gulp

當 App Service 組建自動化確認 Node.js 應用程式是透過 Git 部署,或透過已啟用組建自動化的 Zip 部署時,預設會執行 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。 在 Deployment 區段的「結尾」新增您執行必要工具所需的程式碼區段:

請參閱 MEAN.js 樣本中的範例,其中,deployment 指令碼也執行自訂 npm install 命令。

Bower

此程式碼片段執行 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

此程式碼片段執行 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

此程式碼片段執行 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 標頭。

熱門的 Web 架構可讓您在標準的應用程式模式中存取 X-Forwarded-* 資訊。 在 Express 中,您可以使用信任 Proxy。 例如:

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 的可能值為:ErrorWarningInfoVerbose。 後續的每個層級都包含上一個層級。 例如:Error 只包含錯誤訊息,而 Verbose 包含所有訊息。

開啟診斷記錄後,請執行下列命令來查看記錄資料流:

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

如果您沒有立即看到主控台記錄,請在 30 秒後再查看。

注意

您也可以在瀏覽器中的 https://<app-name>.scm.azurewebsites.net/api/logs/docker 檢查記錄檔。

若要隨時停止記錄資料流,請輸入 Ctrl+C

您可以存取從容器產生的主控台記錄。

請先執行下列命令來開啟容器記錄:

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

以適合您 Web 應用程式的名稱取代 <app-name><resource-group-name>

開啟容器記錄後,請執行下列命令來查看記錄資料流:

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

如果您沒有立即看到主控台記錄,請在 30 秒後再查看。

若要隨時停止記錄資料流,請輸入 Ctrl+C

您也可以在瀏覽器中的 https://<app-name>.scm.azurewebsites.net/api/logs/docker 檢查記錄檔。

使用 Application Insights 進行監視

Application Insights 可讓您監視應用程式的效能、例外狀況和使用方式,完全不需要變更程式碼。 若要附加 App Insights 代理程式,請在入口網站中移至您的 Web 應用程式,在 [設定] 下選取 [Application Insights],然後選取 [開啟 Application Insights]。 接著,選取現有的或建立新的 App Insights 資源。 最後,選取底部的 [套用]。 若要使用 PowerShell 檢測 Web 應用程式,請參閱這些指示

此代理程式會監視伺服器端 Node.js 應用程式。 若要監視用戶端 JavaScript,請將 JavaScript SDK 新增至您的專案

如需詳細資訊,請參閱 Application Insights 延伸模組版本資訊

疑難排解

當運作中的 Node.js 應用程式在 App Service 中行為有異或發生錯誤時,請嘗試下列動作:

  • 存取記錄資料流
  • 在生產模式中於本機測試應用程式。 App Service 會在生產模式中執行 node.js 應用程式,因此您必須確定項目生產模式下按預期在本機中運作。 例如:
    • 視 package.json 而定,可能為生產模式安裝不同的封裝 (dependenciesdevDependencies)。
    • 某些 web 架構可以在生產模式中以不同的方式部署靜態檔案。
    • 在生產模式中執行時,某些 web 架構可能會使用自訂啟動指令碼。
  • 在 App Service 中以開發模式執行應用程式。 例如,在 MEAN.js中,您可以在執行階段設定 NODE_ENV 應用程式設定,將應用程式設定為開發模式。

您無權檢視此目錄或頁面

將 Node.js 程式碼部署至 App Service 中的原生 Windows 應用程式之後,在瀏覽器中巡覽至應用程式的 URL 時,您可能會看到 You do not have permission to view this directory or page. 訊息。 這最有可能因為您沒有 web.config 檔案 (請參閱範本範例)。

如果您使用 Git 或已啟用組建自動化的 ZIP 部署來部署檔案,只要下列其中一個條件成立,部署引擎會在應用程式的 Web 根目錄 (%HOME%\site\wwwroot) 中自動產生 web.config

  • 專案根目錄有 package.json 定義 start 指令碼,其中包含 JavaScript 檔案的路徑。
  • 專案根目錄有 server.js 或 app.js

產生的 web.config 是針對偵測到的 start 指令碼而量身打造。 如需其他部署方法,請手動新增此 web.config。 請確定檔案的格式正確。

如果您使用 ZIP 部署 (例如透過 Visual Studio Code),請務必啟用組建自動化 (因為預設不啟用)。 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 是一個虛擬 URL 路徑,App Service 會使用該路徑來檢查容器是否可以處理要求。 404 回應只是指出路徑不存在,但其可讓 App Service 知道容器狀況良好,並已準備好回應要求。

下一步

或者,請參閱其他資源:

環境變數和應用程式設定參考