Compartir a través de

Configuración de una aplicación de Node.js para Azure App Service

Las aplicaciones de Node.js se deben implementar con todas las dependencias de npm necesarias. El motor de implementación de App Service se ejecuta npm install --production automáticamente al implementar un repositorio de Git o al implementar un paquete Zipcon la automatización de compilación habilitada. Sin embargo, si implementa los archivos mediante FTP/S, debe cargar manualmente los paquetes necesarios.

En este artículo se describen los conceptos clave y se proporcionan instrucciones para Node.js desarrolladores que se implementan en App Service. Si nunca ha usado Azure App Service, complete primero el inicio rápido deNode.js y el tutorial deNode.js con MongoDB .

Mostrar la versión de Node.js

Para mostrar la versión actual de Node.js, ejecute el siguiente comando en Cloud Shell:

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

Para mostrar todas las versiones compatibles de Node.js, ejecute el siguiente comando en Cloud Shell:

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

Para mostrar la versión actual de Node.js, ejecute el siguiente comando en Cloud Shell:

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

Para mostrar todas las versiones compatibles de Node.js, ejecute el siguiente comando en Cloud Shell:

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

Establecimiento de la versión de Node.js

Para establecer la aplicación en una versión compatible de Node.js, ejecute el siguiente comando en Cloud Shell para configurar WEBSITE_NODE_DEFAULT_VERSION en una versión compatible:

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

Nota

En este ejemplo se usa la sintaxis de tilde recomendada para tener como destino la versión más reciente disponible del entorno de ejecución de Node.js 24 en App Service.

Dado que el tiempo de ejecución se revisa y actualiza periódicamente en la plataforma, no se recomienda que tenga como destino una versión secundaria o revisión específica. Debido a posibles riesgos de seguridad, no se garantiza que estas versiones estén disponibles.

Nota

Debe establecer la versión de Node.js en el archivo package.json del proyecto. El motor de implementación se ejecuta en un proceso independiente que contiene todas las versiones compatibles de Node.js.

Para establecer la aplicación en una versión compatible de Node.js, ejecute el siguiente comando en Cloud Shell:

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

Esta configuración especifica la versión de Node.js que usa, tanto en tiempo de ejecución como durante la restauración automatizada de paquetes en Kudu.

Nota

Debe establecer la versión de Node.js en el archivo package.json del proyecto. El motor de implementación se ejecuta en un contenedor independiente que contiene todas las versiones compatibles de Node.js.

¿Qué ocurre con los tiempos de ejecución obsoletos en App Service?

Los tiempos de ejecución obsoletos están en desuso por parte de la organización de mantenimiento o tienen vulnerabilidades significativas. En consecuencia, se eliminan de las páginas de creación y configuración en el portal. Cuando un tiempo de ejecución obsoleto está oculto en el portal, cualquier aplicación que siga usando ese tiempo de ejecución continúa ejecutándose.

Si quiere crear una aplicación con una versión en tiempo de ejecución obsoleta que ya no se muestra en el portal, use la CLI de Azure, una plantilla de ARM o Bicep. Estas alternativas de implementación le permiten crear entornos de ejecución en desuso que se quitan del portal, pero que todavía se admiten.

Si un entorno de ejecución se quita completamente de la plataforma de App Service, el propietario de la suscripción de Azure recibe un aviso por correo electrónico antes de la eliminación.

Establecer el número de puerto

La aplicación de Node.js debe escuchar al puerto correcto para recibir las solicitudes entrantes.

En App Service de Windows, las aplicaciones de Node.js se hospedan con IISNode y la aplicación de Node.js debe escuchar el puerto especificado en la variable process.env.PORT. En el ejemplo siguiente se muestra cómo establecer el puerto en una aplicación express sencilla:

App Service establece la variable PORT de entorno en el contenedor de Node.js y reenvía las solicitudes entrantes al contenedor en ese número de puerto. Para recibir las solicitudes, la aplicación debe escuchar el puerto especificado en la process.env.PORT variable . En el ejemplo siguiente se muestra cómo establecer el puerto en una aplicación express sencilla:

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}`)
})

Personalización de la automatización de compilaciones

Si implementa la aplicación mediante Git o mediante paquetes ZIP con la automatización de compilación habilitada, la automatización de compilaciones de App Service completa los pasos siguientes:

  1. Ejecute un script personalizado, si se especifica uno mediante PRE_BUILD_SCRIPT_PATH.
  2. Ejecute npm install sin marcas. Este paso incluye npm preinstall y postinstall scripts y también instala devDependencies.
  3. Ejecute npm run build si se especifica un script de compilación en el archivo package.json .
  4. Ejecute npm run build:azure si se especifica un build:azure script en el archivo package.json .
  5. Ejecute un script personalizado, si se especifica uno mediante POST_BUILD_SCRIPT_PATH.

Nota

Como se describe en la documentación de npm, los scripts denominados prebuild y postbuild se ejecutan antes y después de build, respectivamente, si se especifican. Los scripts denominados preinstall y postinstall se ejecutan antes y después installde , respectivamente.

PRE_BUILD_COMMAND y POST_BUILD_COMMAND son variables de entorno que, de forma predeterminada, están vacías. Para ejecutar comandos anteriores a la compilación, defina PRE_BUILD_COMMAND. Para ejecutar comandos posteriores a la compilación, defina POST_BUILD_COMMAND.

En el ejemplo siguiente se usan las dos variables para especificar una serie de comandos, que están separados por comas.

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"

Para obtener información sobre las variables de entorno adicionales para personalizar la automatización de la compilación, consulte Configuración de Oryx.

Para más información sobre cómo se ejecuta App Service y se compilan aplicaciones de Node.js en Linux, consulte la documentación de Oryx sobre cómo se detectan y se compilan las aplicaciones de Node.js.

Configurar el servidor Node.js

Los contenedores de Node.js se suministran con PM2, un administrador de procesos de producción. Puede configurar la aplicación para que comience con PM2, con npm starto con un comando personalizado.

Herramienta Propósito
Ejecutar con PM2 Recomendado. Uso de producción o almacenamiento provisional. PM2 proporciona una plataforma de administración de aplicaciones de servicio completo.
Ejecución con npm start Solo en entornos de desarrollo.
Ejecución con un comando personalizado Entornos de desarrollo o ensayo.

Ejecutar con PM2

El contenedor inicia automáticamente la aplicación con PM2 cuando se encuentra uno de los archivos comunes de Node.js en el proyecto:

  • bin/www
  • server.js
  • app.js
  • index.js
  • hostingstart.js
  • Uno de los siguientes archivos PM2: process.json o ecosystem.config.js

También puede configurar un archivo de inicio personalizado con las siguientes extensiones:

  • Un archivo .js
  • Un archivo PM2 que tiene la extensión .json, .config.js, .yaml o .yml

Nota

Con Node.js versiones después de Node 14 LTS, el contenedor no inicia automáticamente la aplicación con PM2. Para iniciar la aplicación con PM2, establezca el comando de inicio en pm2 start <.js-file-or-PM2-file> --no-daemon. Asegúrese de usar el argumento --no-daemon porque PM2 debe ejecutarse en primer plano para que el contenedor funcione correctamente.

Para agregar un archivo de inicio personalizado, ejecute el siguiente comando en Cloud Shell:

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

Ejecución con un comando personalizado

App Service puede iniciar la aplicación mediante un comando personalizado, como un ejecutable como run.sh. Por ejemplo, para ejecutar npm run start:prod, ejecute el siguiente comando en Cloud Shell:

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

Ejecución con npm start

Para iniciar la aplicación con npm start, asegúrese de que un start script está en el archivo package.json . Por ejemplo:

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

Para utilizar un archivo package.json personalizado en el proyecto, ejecute el siguiente comando en Cloud Shell:

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

Depuración remota

Puede depurar la aplicación de Node.js de forma remota en Visual Studio Code si la configura para que se ejecute con PM2, excepto cuando se ejecuta mediante un archivo .config.js, .yml o .yaml .

En la mayoría de los casos, no es necesaria ninguna configuración adicional para la aplicación. Si la aplicación se ejecuta con un archivo process.json (predeterminado o personalizado), debe tener una script propiedad en la raíz JSON. Por ejemplo:

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

Para configurar Visual Studio Code para la depuración remota, instale la extensión App Service. Siga las instrucciones que aparecen en la página de la extensión e inicie sesión en Azure en Visual Studio Code.

En el Explorador de Azure, busque la aplicación que desea depurar, haga clic con el botón derecho en ella y seleccione Iniciar depuración remota. Seleccione Sí a fin de habilitar la depuración remota para la aplicación. App Service inicia un proxy de túnel y asocia el depurador. A continuación, puede realizar solicitudes a la aplicación y ver al depurador detenerse en los puntos de interrupción.

Cuando haya terminado con la depuración, detenga el depurador seleccionando Desconectar. Cuando se le solicite, debe selecciona Sí para deshabilitar la depuración remota. Para deshabilitarla más adelante, haga clic en su aplicación de nuevo en el explorador de Azure y seleccione Disable Remote Debugging (Deshabilitar la depuración remota).

Acceso a variables de entorno

En App Service, puede establecer la configuración de la aplicación fuera del código de la aplicación. A continuación, puede acceder a ellos mediante el patrón estándar Node.js. Por ejemplo, para acceder a una configuración de una aplicación denominada NODE_ENV, use el código siguiente:

process.env.NODE_ENV

Ejecutar Grunt, Bower o Gulp

De forma predeterminada, la automatización de compilación de App Service se ejecuta npm install --production cuando reconoce que una aplicación de Node.js se implementa a través de Git o mediante la implementación zip con la automatización de compilación habilitada. Si la aplicación requiere alguna de las herramientas de automatización más populares, como Grunt, Bower o Gulp, deberá suministrar un script de implementación personalizado para ejecutarla.

Para habilitar que el repositorio ejecute estas herramientas, deberá agregarlas a las dependencias en el archivo package.json. Por ejemplo:

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

Desde una ventana de terminal local, cambie el directorio a la raíz del repositorio y ejecute los siguientes comandos:

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

La raíz del repositorio ahora tiene dos archivos adicionales: .deployment y deploy.sh.

Abra deploy.sh y busque la sección Deployment, que tiene el siguiente aspecto:

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

Al final de esta sección, npm install --production se ejecuta. Agregue la sección de código que necesita para ejecutar la herramienta necesaria al final de la sección Deployment:

Para obtener un ejemplo, consulte el ejemplo deMEAN.js. En este ejemplo, el script de implementación también ejecuta un comando personalizado npm install .

Glorieta

Este fragmento de código ejecuta 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

Trago

Este fragmento de código ejecuta 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

Gruñido

Este fragmento de código ejecuta grunt.

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

Detección de sesión de HTTPS

En App Service, la terminación TLS/SSL se produce en los equilibradores de carga de red, por lo que todas las solicitudes HTTPS llegan a la aplicación como solicitudes HTTP sin cifrar. Si la lógica de la aplicación necesita comprobar si las solicitudes de usuario están cifradas, inspeccione el X-Forwarded-Proto encabezado.

Los marcos web más usados le permiten acceder a la información de X-Forwarded-* en el patrón de aplicación estándar. En Express, puede usar trust proxy. Por ejemplo:

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

Acceso a los registros de diagnóstico

Para acceder a los registros de consola generados desde el código de la aplicación en App Service, active el registro de diagnóstico mediante la ejecución del siguiente comando en Cloud Shell:

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

Los valores posibles para --level son Error, Warning, Info y Verbose. Todos los niveles incluyen el nivel anterior. Por ejemplo, Error solo incluye mensajes de error. Verbose incluye todos los mensajes.

Después de activar el registro de diagnóstico, ejecute el siguiente comando para ver la secuencia de registro:

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

Si los registros de consola no aparecen inmediatamente, vuelva a comprobar en 30 segundos.

Para detener el streaming de registros en cualquier momento, seleccione Ctrl+C.

Puede acceder a los registros de consola que se generan desde dentro del contenedor.

Para activar el registro de contenedores, ejecute el siguiente comando:

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

Reemplace los <app-name> valores y <resource-group-name> por los nombres adecuados para la aplicación web.

Después de activar el registro de contenedores, ejecute el siguiente comando para ver la secuencia de registro:

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

Si los registros de consola no aparecen inmediatamente, vuelva a comprobar en 30 segundos.

Para detener el streaming de registros en cualquier momento, use el método abreviado de teclado Ctrl+C.

Reescrituras de direcciones URL

Al implementar aplicaciones Node.js en Azure App Service para Linux, es posible que tenga que controlar las reescrituras de direcciones URL directamente dentro de la aplicación. Esta configuración es especialmente útil para garantizar que los patrones de dirección URL específicos se redirigen a los puntos de conexión correctos sin depender de configuraciones de servidor web. Hay varias maneras de realizar reescrituras de direcciones URL en Node.js. Un ejemplo es mediante el paquete express-urlrewrite .

Supervisión de la aplicación mediante Application Insights

Application Insights le permite supervisar el rendimiento, las excepciones y el uso de la aplicación sin realizar cambios en el código. Para adjuntar el agente de Application Insights, vaya a la aplicación web en el portal, seleccione Application Insights en Supervisión y, a continuación, seleccione Activar Application Insights. A continuación, seleccione un recurso de Application Insights existente o cree uno. Por último, seleccione Aplicar en la parte inferior de la página. Para instrumentar la aplicación web mediante PowerShell, consulte estas instrucciones.

Este agente supervisará su aplicación de Node.js del lado servidor. Para supervisar el código JavaScript del lado cliente, agregue el SDK de JavaScript al proyecto.

Para más información, consulte Habilitación de la supervisión de aplicaciones en Azure App Service para .NET, Node.js, Python y aplicaciones Java.

Solución de problemas

Cuando una aplicación de Node.js en funcionamiento se comporta de manera diferente en App Service o genera errores, intente lo siguiente:

  • Acceso a la secuencia de registros.
  • Pruebe la aplicación localmente en modo de producción. App Service ejecuta las aplicaciones de Node.js en el modo de producción, por lo que deberá asegurarse de que el proyecto funciona según lo previsto en modo de producción localmente. Por ejemplo:
    • En función del archivo package.json, se pueden instalar distintos paquetes para el modo de producción (dependencies frente a devDependencies).
    • Es posible que algunas plataformas web implementen archivos estáticos de forma diferente en modo de producción.
    • Es posible que algunas plataformas web usen scripts de inicio personalizados cuando se ejecutan en modo de producción.
  • Ejecute la aplicación en App Service en el modo de desarrollo. Por ejemplo, en MEAN.js, puede establecer la aplicación en modo de desarrollo en tiempo de ejecución si establece la configuración de aplicación NODE_ENV.

No tiene permiso para ver este directorio o esta página

Después de implementar el código de Node.js en una aplicación nativa de Windows en App Service, es posible que vea el mensaje You do not have permission to view this directory or page en el explorador cuando vaya a la dirección URL de la aplicación. Es más probable que se produzca este error porque no tiene un archivo web.config . (Vea la plantilla y un ejemplo).

Si implementa los archivos mediante Git o mediante la implementación ZIP con la automatización de compilación habilitada, el motor de implementación genera un archivo web.config en la raíz web de la aplicación (%HOME%\site\wwwroot) automáticamente si se cumple una de las condiciones siguientes:

  • La raíz del proyecto contiene un archivo package.json que define un start script que contiene la ruta de acceso de un archivo JavaScript.
  • La raíz del proyecto contiene un server.js o un archivo app.js .

El archivo web.config generado se adapta al script de inicio detectado. Para otros métodos de implementación, agregue el archivo web.config manualmente. Asegúrese de que el archivo tiene el formato correcto.

Si usa la implementación zip (a través de Visual Studio Code, por ejemplo), asegúrese de habilitar la automatización de la compilación. que no está habilitado de manera predeterminada. az webapp up usa la implementación ZIP con la automatización de compilación habilitada.

Omitir el mensaje robots933456 en los registros

Es posible que vea el mensaje siguiente en los registros de contenedor:

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

Puede omitir este mensaje sin problemas. /robots933456.txt es una ruta de URL ficticia. App Service lo usa para comprobar si el contenedor es capaz de atender solicitudes. Una respuesta de error "404" indica que la ruta de acceso no existe y indica a App Service que el contenedor está en buen estado y listo para responder a las solicitudes.

Contenido relacionado

  • Last updated on