تكوين تطبيق Node.js لـ Azure App Service

يجب نشر Node.js التطبيقات مع جميع تبعيات npm المطلوبة. يتم تشغيل npm install --production محرك نشر App Service تلقائيا عند نشر مستودع Git أو عند نشر حزمة Zip مع تمكين أتمتة الإنشاء. إذا قمت بنشر ملفاتك باستخدام FTP/S، فستحتاج إلى تحميل الحزم المطلوبة يدويا.

توضح هذه المقالة المفاهيم الأساسية وتوفر إرشادات لمطوري Node.js الذين ينتشرون إلى App Service. إذا لم تكن قد استخدمت 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"

إشعار

يستخدم هذا المثال بناء جملة tilde الموصى به لاستهداف أحدث إصدار متاح من وقت تشغيل Node.js 24 على App Service.

نظرا لأن وقت التشغيل يتم تصحيحه وتحديثه بانتظام بواسطة النظام الأساسي ، فإننا لا نوصي باستهداف إصدار / تصحيح ثانوي معين. نظرا لمخاطر الأمان المحتملة، لا يتم ضمان توفر هذه الإصدارات.

إشعار

عليك تعيين الإصدار Node.js في package.json لدى مشروعك. يشغل محرك النشر في عملية منفصلة تحتوي على جميع إصدارات Node.js المدعومة.

لتعيين تطبيقك إلى إصدار Node.js مدعوم، قم بتشغيل الأمر التالي في Cloud Shell:

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

يحدد هذا الإعداد إصدار Node.js لاستخدامه، سواء في وقت التشغيل أو في أثناء استعادة الحزمة التلقائية في Kudu.

إشعار

عليك تعيين الإصدار Node.js في package.json لدى مشروعك. يشغل محرك النشر في حاوية منفصلة، والتي تحتوي على جميع إصدارات Node.js المدعومة.

ماذا يحدث لأقات التشغيل القديمة في App Service؟

يتم إهمال أوقات التشغيل القديمة من قبل المؤسسة التي تحتفظ بها أو بها ثغرات أمنية كبيرة. وفقا لذلك، تتم إزالتها من إنشاء الصفحات وتكوينها في المدخل. عند إخفاء وقت تشغيل قديم من المدخل، يستمر تشغيل أي تطبيق لا يزال يستخدم وقت التشغيل هذا.

إذا كنت ترغب في إنشاء تطبيق بإصدار وقت تشغيل قديم لم يعد معروضا على المدخل، فاستخدم Azure CLI أو قالب ARM أو Bicep. تتيح لك بدائل التوزيع هذه إنشاء أوقات تشغيل مهملة تمت إزالتها من المدخل ولكن لا تزال مدعومة.

إذا تمت إزالة وقت التشغيل بالكامل من النظام الأساسي لخدمة التطبيقات، يتلقى مالك اشتراك Azure إشعارا بالبريد الإلكتروني قبل الإزالة.

تعيين رقم المنفذ

يحتاج تطبيق Node.js إلى الاستماع إلى المنفذ الصحيح لتلقي الطلبات الواردة.

في App Service على Windows، تتم استضافة التطبيقات Node.js مع IISNode، ويجب أن يستمع تطبيق Node.js إلى المنفذ المحدد في process.env.PORT المتغير. يوضح المثال التالي كيفية تعيين المنفذ في تطبيق Express بسيط:

تقوم App Service بتعيين متغير PORT البيئة في حاوية Node.js وإعادة توجيه الطلبات الواردة إلى الحاوية الخاصة بك في رقم المنفذ هذا. لتلقي الطلبات، يجب أن يستمع تطبيقك إلى المنفذ المحدد في المتغير 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، أو باستخدام حزم مضغوطة مع تمكين التنفيذ التلقائي للبناء، فإن التنفيذ التلقائي لبناء App Service يكمل الخطوات التالية:

قم بتشغيل برنامج نصي مخصص ، إذا تم تحديد واحد بواسطة PRE_BUILD_SCRIPT_PATH.
اركض npm install بدون أي أعلام. تتضمن هذه الخطوة npm preinstall والبرامج postinstall النصية وأيضا عمليات التثبيت devDependencies.
قم بتشغيله npm run build إذا تم تحديد برنامج نصي للإنشاء في ملف package.json الخاص بك.
قم بتشغيله npm run build:azure إذا تم تحديد برنامج نصي build:azure في ملف package.json الخاص بك.
قم بتشغيل برنامج نصي مخصص ، إذا تم تحديد واحد بواسطة 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"

للحصول على معلومات حول متغيرات البيئة الإضافية لتخصيص أتمتة البناء، راجع تكوين Ourix.

لمزيد من المعلومات حول كيفية تشغيل خدمة التطبيقات وبناء Node.js التطبيقات في Linux، راجع وثائق Oryx: كيفية اكتشاف التطبيقات Node.js وبنائها.

تكوين خادم Node.js

تأتي حاويات Node.js مع PM2، مدير عمليات الإنتاج. يمكنك تكوين تطبيقك ليبدأ ب PM2 أو باستخدام npm startأمر مخصص أو باستخدامه.

أداة	الغرض
تشغيل مع PM2	موصى به. الإنتاج أو استخدام التدريج. يوفر «PM2» نظامًا أساسيًا لإدارة تطبيقات الخدمة الكاملة.
تشغيل مع بدء npm	استخدام التطوير فقط.
تشغيل باستخدام أمر مخصص	إما تطوير أو تقسيم مرحلي.

تشغيل باستخدام PM2

تبدأ الحاوية تشغيل تطبيقك تلقائيًا باستخدام PM2 عند العثور على أحد ملفات Node.js الشائعة في مشروعك:

bin/www
server.js
app.js
index.js
hostingstart.js
أحد ملفات PM2 التالية: process.json أو ecosystem.config.js

بإمكانك أيضًا تكوين ملف بدء مخصص بالملحقات التالية:

ملف .js
ملف PM2 يحتوي على الملحق .jsonأو .config.jsأو .yaml أو .yml

إشعار

مع Node.js الإصدارات بعد 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

لبدء تشغيل تطبيقك ، npm startفقط تأكد من وجود برنامج نصي start في ملف package.json . على سبيل المثال:

{
  ...
  "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 الخاص بك عن بعد في Visual Studio Code إذا قمت بتكوينه لتشغيله باستخدام PM2، إلا عند تشغيله باستخدام ملف .config.jsأو .yml أو .yaml .

في معظم الحالات، لا يتطلب تكوين إضافي لتطبيقك. إذا تم تشغيل تطبيقك بملف process.json (افتراضي أو مخصص)، فيجب أن يكون له script خاصية في جذر JSON. على سبيل المثال:

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

لإعداد Visual Studio Code لتصحيح الأخطاء عن بعد، قم بتثبيت ملحق App Service. اتبع الإرشادات الموجودة في صفحة الملحق وسجل دخول إلى Azure في Visual Studio Code.

في مستكشف Azure، ابحث عن التطبيق الذي تريد تصحيحه، وانقر بزر الماوس الأيمن فوقه، وحدد بدء تصحيح الأخطاء عن بعد. حدد نعم لتمكين تصحيح الأخطاء عن بعد لتطبيقك. تبدأ App Service وكيل نفق وتعلق مصحح الأخطاء. بإمكانك بعد ذلك تقديم طلبات إلى التطبيق ورؤية مصحح الأخطاء يتعطل عند نقاط التوقف.

عند الانتهاء من تصحيح الأخطاء، أوقف مصحح الأخطاء عن طريق تحديد قطع الاتصال. عند المطالبة، يجب تحديد نعم لتعطيل تصحيح الأخطاء عن بعد. لتعطيله لاحقا، انقر بزر الماوس الأيمن فوق تطبيقك مرة أخرى في مستكشف Azure وحدد تعطيل تصحيح الأخطاء عن بعد.

الوصول إلى متغيرات البيئة

في App Service، يمكنك تعيين إعدادات التطبيق خارج التعليمات البرمجية للتطبيق. يمكنك بعد ذلك الوصول إليها باستخدام نمط Node.js القياسي. على سبيل المثال، للوصول إلى إعداد تطبيق يسمى NODE_ENV، استخدم التعليمات البرمجية التالية:

process.env.NODE_ENV

تشغيل Grunt/Bower/Gulp

بشكل افتراضي، يتم تشغيل npm install --production أتمتة إنشاء App Service عندما تتعرف على نشر تطبيق Node.js عبر Git أو عبر نشر Zip مع تمكين أتمتة الإنشاء. إذا كان تطبيقك يتطلب أيا من أدوات الأتمتة الشائعة، مثل 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. في هذا النموذج، يقوم البرنامج النصي للنشر أيضا بتشغيل أمر مخصص 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و WarningInfoو و.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> بأسماء مناسبة لتطبيق الويب الخاص بك.

بعد تشغيل تسجيل الحاوية، قم بتشغيل الأمر التالي لمشاهدة دفق السجل:

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

إذا لم تظهر سجلات وحدة التحكم على الفور، فتحقق مرة أخرى في 30 ثانية.

لإيقاف بث السجلات في أي وقت، استخدم اختصار لوحة المفاتيح Ctrl+C.

إعادة كتابة عنوان URL

عند نشر تطبيقات Node.js على Azure App Service لنظام Linux، قد تحتاج إلى التعامل مع إعادة كتابة عنوان URL مباشرة داخل التطبيق الخاص بك. يعد هذا التكوين مفيدا بشكل خاص لضمان إعادة توجيه أنماط عناوين URL محددة إلى نقاط النهاية الصحيحة دون الاعتماد على تكوينات خادم الويب. هناك عدة طرق لإنجاز إعادة كتابة عنوان URL في Node.js. أحد الأمثلة على ذلك هو استخدام حزمة express-urlrewrite .

مراقبة تطبيقك باستخدام Application Insights

يمكنك Application Insights من مراقبة أداء التطبيق والاستثناءات والاستخدام دون إجراء أي تغييرات في التعليمات البرمجية. لإرفاق عامل Application Insights، انتقل إلى تطبيق الويب الخاص بك في المدخل، وحدد Application Insights ضمن المراقبة، ثم حدد تشغيل Application Insights. بعد ذلك، حدد مورد Application Insights موجود أو أنشئ موردا جديدا. أخيرا ، حدد تطبيق في أسفل الصفحة. لأداة تطبيق الويب الخاص بك باستخدام PowerShell، راجع هذه الإرشادات.

سيراقب هذا العامل تطبيق Node.js من جانب الخادم الخاص بك. لمراقبة JavaScript من جانب العميل، أضف JavaScript SDK إلى مشروعك.

لمزيد من المعلومات، راجع تمكين مراقبة التطبيقات في Azure App Service لتطبيقات .NET وNode.jsوPython وJava.

استكشاف الأخطاء وإصلاحها

عندما يتصرف تطبيق Node.js يعمل على نحو مختلف في App Service أو يحتوي على أخطاء، جرب ما يلي:

الوصول إلى دفق السجل.
قم باختبار التطبيق محلياً في وضع الإنتاج. يقوم App Service بتشغيل تطبيقات Node.js الخاصة بك في وضع الإنتاج، لذلك تحتاج إلى التأكد من أن مشروعك يعمل كما هو متوقع في وضع الإنتاج محليًا. على سبيل المثال:
- اعتمادا على package.json، قد يتم تثبيت حزم مختلفة لوضع الإنتاج (dependencies مقابل devDependencies).
- قد تقوم أطر عمل ويب معينة بنشر ملفات ثابتة بشكل مختلف في وضع الإنتاج.
- قد تستخدم أطر عمل ويب معينة برامج نصية مخصصة لبدء التشغيل عند التشغيل في وضع الإنتاج.
شغل تطبيقك في App Service في وضع التطوير. على سبيل المثال، في MEAN.js، يمكنك تعيين تطبيقك إلى وضع التطوير في وقت التشغيل عن طريق تعيين NODE_ENV إعداد التطبيق.

لا تمتلك إذنًا لعرض هذا الدليل أو الصفحة

بعد نشر التعليمات البرمجية Node.js إلى تطبيق Windows أصلي في App Service، قد ترى الرسالة You do not have permission to view this directory or page في المستعرض عند الانتقال إلى عنوان URL لتطبيقك. يحدث هذا الخطأ على الأرجح لأنه لا يوجد لديك ملف web.config . (راجع القالب ومثال.)

إذا قمت بنشر ملفاتك باستخدام Git أو باستخدام نشر ZIP مع تمكين أتمتة الإنشاء، يقوم محرك النشر بإنشاء ملف web.config في جذر الويب لتطبيقك (%HOME%\site\wwwroot) تلقائيا إذا كان أحد الشروط التالية صحيحا:

يحتوي جذر المشروع على ملف package.json يحدد نصا start برمجيا يحتوي على مسار ملف JavaScript.
يحتوي جذر المشروع على ملف server.js أو ملفapp.js .

تم تخصيص ملف web.config الذي تم إنشاؤه وفقا لبرنامج البدء المكتشف. بالنسبة لطرق النشر الأخرى، أضف ملفweb.config يدويا. تأكد من تنسيق الملف على نحو صحيح.

إذا كنت تستخدم نشر ZIP (عبر Visual Studio Code، على سبيل المثال)، فتأكد من تمكين أتمتة الإنشاء. لا يتم تمكينه افتراضيًا. az webapp up يستخدم نشر ZIP مع تمكين أتمتة الإنشاء.

تجاهل رسالة الروبوتات933456 في السجلات

قد ترى الرسالة التالية في سجلات الحاوية:

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

يمكنك تجاهل هذه الرسالة بأمان. /robots933456.txt هو مسار URL وهمي. تستخدم خدمة التطبيقات هذا النموذج للتحقق مما إذا كانت الحاوية قادرة على تلبية الطلبات. يشير رد خطأ "404" إلى أن المسار غير موجود، ويشير إلى خدمة التطبيقات بأن الحاوية سليمة وجاهزة للرد على الطلبات.

البرنامج التعليمي: Node.js التطبيق مع MongoDB

الأسئلة المتداولة حول Azure App Service على Linux

متغيرات البيئة ومرجع إعدادات التطبيق

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-08-29

مشاركة عبر

تكوين تطبيق Node.js لـ Azure App Service

إظهار الإصدار Node.js

تعيين الإصدار Node.js

ماذا يحدث لأقات التشغيل القديمة في App Service؟

تعيين رقم المنفذ

تخصيص أتمتة البناء

تكوين خادم Node.js

تشغيل باستخدام PM2

تشغيل باستخدام أمر مخصص

تشغيل مع بدء npm

تصحيح الأخطاء عن بُعد

الوصول إلى متغيرات البيئة

تشغيل Grunt/Bower/Gulp

باور

جرع

نعر

الكشف عن جلسة عمل HTTPS

الوصول إلى سجلات التشخيص

إعادة كتابة عنوان URL

مراقبة تطبيقك باستخدام Application Insights

استكشاف الأخطاء وإصلاحها

لا تمتلك إذنًا لعرض هذا الدليل أو الصفحة

تجاهل رسالة الروبوتات933456 في السجلات

المحتوى ذو الصلة

الملاحظات

الموارد الإضافية