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

Node.js 應用程式必須連同所有必要的 NPM 相依性一起部署。當您部署 npm install --production，或當您部署已啟用組建自動化的 Zip 封裝時，App Service 部署引擎會自動執行。不過，如果您使用 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 版本，請在 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="~24"

附註

此範例採用建議的波狀符號語法，以 App Service 上可用的最新版 Node.js 24 執行階段為目標。

因為平台會定期修補和更新執行階段，我們不建議您以特定的次要版本/修補程式為目標。因為潛在的安全性風險，無法保證這些版本可供使用。

附註

您應該在專案的 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|24-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。
如果 npm run build 檔案中指定了 build 指令碼，則執行。
如果 npm run build:azure 檔案中指定了 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 之後的 Node.js 版本，容器不會自動啟動 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 啟動應用程式，請確定 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 部署，或透過npm install --production Zip 部署時，預設會執行。如果應用程式需要任何熱門的自動化工具，例如 Grunt、Bower 或 Gulp，則您必須提供自訂部署指令碼來執行應用程式。

若要讓存放庫執行這些工具，您必須將工具新增至 package.json 中的 dependencies。例如：

"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 範例。在此範例中，部署指令碼也會執行自訂 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

的可能值為 --levelError、 Warning、 Info和 Verbose。後續的每個層級都包含上一個層級。例如， Error 只包含錯誤訊息。 Verbose 包含所有訊息。

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

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

如果主控台記錄未立即出現，請在30秒後再次檢查。

若要隨時停止記錄串流，請選取 Ctrl+C。

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

若要開啟容器記錄，請執行下列命令：

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

請將 <app-name> 和 <resource-group-name> 的值取代為 Web 應用程式適用的名稱。

開啟容器記錄之後，請執行下列命令來查看記錄數據流：

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

如果主控台記錄未立即出現，請在30秒後再次檢查。

要隨時停止日誌串流，請使用鍵盤快捷鍵 Ctrl+C。

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 新增至您的專案。

如需詳細資訊，請參閱在適用於 .NET、Node.js、Python 和 Java 應用程式的 Azure App Service 中啟用應用程式監視。

疑難排解

當運作中的 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 檔案：

您的專案根目錄包含 package.json 檔案，其會定義包含 JavaScript 檔案路徑的 start 指令碼。
您的專案根目錄包含 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 常見問題集

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19