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

發行項
10/16/2024

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

如果 PRE_BUILD_SCRIPT_PATH 已指定自訂指令碼，請執行該自訂指令碼。
執行 npm install 但不指定任何旗標，其中包括 npm preinstall 和 postinstall 指令碼，還會安裝 devDependencies。
如果 package.json 中指定 build 指令碼，則執行 npm run build。
如果 package.json 中指定 build:azure 指令碼，則執行 npm run build:azure。
執行自訂指令碼 (如果 POST_BUILD_SCRIPT_PATH 已指定)。

注意

如 npm 文件中所指定，名為 prebuild 和 postbuild 的指令碼 (如果指定) 分別會在 build 之前和之後執行。 preinstall 和 postinstall 分別在 install 之前和之後執行。

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 檔案

注意

從 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 區段的「結尾」新增您執行必要工具所需的程式碼區段：

Bower
Gulp
Grunt

請參閱 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 的可能值為：Error、Warning、Info 和 Verbose。後續的每個層級都包含上一個層級。例如：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 檢查記錄檔。

URL 重寫

在適用於 Linux 的 Azure App Service 上部署 Node.js 應用程式時，您可能需要直接在應用程式中處理 URL 重寫。這特別適用於確保特定 URL 模式會重新導向至正確的端點，而不需要依賴 Web 伺服器設定。有數種方式可以在 Node.js 中完成 URL 重寫。其中一個範例是透過 express-urlrewrite 套件。

使用 Application Insights 進行監視

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

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

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

疑難排解

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

存取記錄資料流。
在生產模式中於本機測試應用程式。 App Service 會在生產模式中執行 node.js 應用程式，因此您必須確定項目生產模式下按預期在本機中運作。例如：
- 視 package.json 而定，可能為生產模式安裝不同的封裝 (dependencies 與 devDependencies)。
- 某些 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 知道容器狀況良好，並已準備好回應要求。

下一步

教學課程：使用 MongoDB 的 Node.js 應用程式

Linux 上的 Azure App Service 常見問題

或者，請參閱其他資源：

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

共用方式為