Utilizzo di moduli Node.js con le applicazioni AzureUsing Node.js Modules with Azure applications

In questo documento vengono fornite le linee guida per l'utilizzo dei moduli Node.js con le applicazioni ospitate in Azure.This document provides guidance on using Node.js modules with applications hosted on Azure. Queste indicazioni consentono di garantire che l'applicazione utilizzi una versione specifica di moduli, nonché di utilizzare i moduli nativi con Azure.It provides guidance on ensuring that your application uses a specific version of module as well as using native modules with Azure.

Se si ha familiarità con l'uso dei moduli Node.js e dei file package.json e npm-shrinkwrap.json, le informazioni seguenti offrono un breve riepilogo degli argomenti illustrati in questo articolo:If you are already familiar with using Node.js modules, package.json and npm-shrinkwrap.json files, the following information provides a quick summary of what is discussed in this article:

  • Nel Servizio app di Azure vengono riconosciuti i file package.json e npm-shrinkwrap.json ed è possibile installare moduli in base alle voci incluse in tali file.Azure App Service understands package.json and npm-shrinkwrap.json files and can install modules based on entries in these files.

  • In Servizi cloud di Azure è previsto che tutti i moduli vengano installati nell'ambiente di sviluppo e che la directory node_modules sia inclusa come parte del pacchetto di distribuzione.Azure Cloud Services expect all modules to be installed on the development environment, and the node_modules directory to be included as part of the deployment package. È possibile abilitare il supporto per l'installazione dei moduli tramite i file package.json o npm-shrinkwrap.json in Servizi cloud, ma questa configurazione richiede la personalizzazione degli script predefiniti usati dai progetti del servizio cloud.It is possible to enable support for installing modules using package.json or npm-shrinkwrap.json files on Cloud Services; however, this configuration requires customization of the default scripts used by Cloud Service projects. Per un esempio di come configurare questo ambiente, vedere Azure Startup task to run npm install to avoid deploying node modules (Attività di avvio di Azure per l'esecuzione dell'installazione di npm per evitare la distribuzione dei moduli Node)For an example of how to configure this environment, see Azure Startup task to run npm install to avoid deploying node modules

Nota

Macchine virtuali di Azure non è incluso in questo articolo, perché l'esperienza di distribuzione in una macchina virtuale dipende dal sistema operativo ospitato dalla macchina virtuale.Azure Virtual Machines are not discussed in this article, as the deployment experience in a VM is dependent on the operating system hosted by the Virtual Machine.

Moduli Node.jsNode.js Modules

I moduli sono pacchetti JavaScript caricabili che forniscono funzionalità specifiche per l'applicazione.Modules are loadable JavaScript packages that provide specific functionality for your application. I moduli vengono in genere installati usando lo strumento da riga di comando npm, tuttavia, alcuni moduli, ad esempio il modulo HTTP, sono forniti nel pacchetto Node.js di base.Modules are usually installed using the npm command-line tool, however some modules (such as the http module) are provided as part of the core Node.js package.

Quando i moduli sono installati, vengono archiviati nella directory node_modules nella radice della struttura di directory dell'applicazione.When modules are installed, they are stored in the node_modules directory at the root of your application directory structure. Ogni modulo nella directory node_modules mantiene la propria directory node_modules che contiene i moduli da cui dipende e questo comportamento si ripete per tutti i moduli fino alla fine della catena delle dipendenze.Each module within the node_modules directory maintains its own node_modules directory that contains any modules that it depends on, and this behavior repeats for every module all the way down the dependency chain. Questo ambiente consente a ogni modulo installato di avere requisiti di versione specifici per i moduli da cui dipende, anche se ciò può determinare una struttura di directory molto grande.This environment allows each module installed to have its own version requirements for the modules it depends on, however it can result in quite a large directory structure.

La distribuzione della directory node_modules come parte dell'applicazione aumenta le dimensioni della distribuzione rispetto a quando si usa un file package.json o npm-shrinkwrap.json, ma questa soluzione garantisce che le versioni dei moduli usate in fase di produzione siano le stesse dei moduli usati in fase di sviluppo.Deploying the node_modules directory as part of your application increases the size of the deployment when compared to using a package.json or npm-shrinkwrap.json file; however, it does guarantee that the versions of the modules used in production are the same as the modules used in development.

Moduli nativiNative Modules

Sebbene la maggior parte dei moduli sia semplicemente costituita da file JavaScript in testo normale, alcuni di essi sono immagini binarie specifiche della piattaforma.While most modules are simply plain-text JavaScript files, some modules are platform-specific binary images. Questi moduli vengono compilati in fase di installazione, in genere tramite Python e node-gyp.These modules are compiled at install time, usually by using Python and node-gyp. Poiché Servizi cloud di Azure si basa sulla distribuzione della cartella node_modules come parte dell'applicazione, qualsiasi modulo nativo incluso come parte dei moduli installati può funzionare in un servizio cloud purché sia stato installato e compilato in un sistema di sviluppo Windows.Since Azure Cloud Services rely on the node_modules folder being deployed as part of the application, any native module included as part of the installed modules should work in a cloud service as long as it was installed and compiled on a Windows development system.

Servizio app di Azure non supporta tutti i moduli nativi e potrebbe non riuscire a compilare i moduli con prerequisiti specifici.Azure App Service does not support all native modules, and might fail when compiling modules with specific prerequisites. Mentre alcuni moduli più diffusi, come MongoDB, hanno dipendenze native facoltative e funzionano anche senza di esse, due soluzioni alternative hanno fornito risultati positivi con quasi tutti i moduli nativi disponibili attualmente:While some popular modules like MongoDB have optional native dependencies and work fine without them, two workarounds proved successful with almost all native modules available today:

  • Eseguire npm install in un computer Windows con installati tutti i prerequisiti del modulo nativo.Run npm install on a Windows machine that has all the native module's prerequisites installed. Distribuire quindi la cartella node_modules creata come parte dell'applicazione in Servizio app di Azure.Then, deploy the created node_modules folder as part of the application to Azure App Service.

    • Prima di eseguire la compilazione, verificare che l'installazione locale di Node.js disponga di un'architettura corrispondente e che la versione sia molto simile a quella usata in Azure (i valori correnti possono essere verificati in fase di esecuzione tramite le proprietà process.arch e process.version).Before compiling, check that your local Node.js installation has matching architecture and the version is as close as possible to the one used in Azure (the current values can be checked on runtime from properties process.arch and process.version).
  • È possibile configurare Servizio app di Azure per l'esecuzione di script bash o della shell durante la distribuzione, offrendo la possibilità di eseguire comandi personalizzati e di configurare con precisione la modalità di esecuzione di npm install .Azure App Service can be configured to execute custom bash or shell scripts during deployment, giving you the opportunity to execute custom commands and precisely configure the way npm install is being run. Per un video che illustra come configurare tale ambiente, vedere Custom Website Deployment Scripts with Kudu.For a video showing how to configure that environment, see Custom Website Deployment Scripts with Kudu.

Utilizzare un file package.jsonUsing a package.json file

Il file package.json consente di specificare le dipendenze di livello superiore necessarie all'applicazione in modo che la piattaforma di hosting possa installare le dipendenze invece di richiedere l'aggiunta della cartella node_modules come parte della distribuzione.The package.json file is a way to specify the top level dependencies your application requires so that the hosting platform can install the dependencies, rather than requiring you to include the node_modules folder as part of the deployment. Dopo che l'applicazione è stata distribuita, viene usato il comando npm install per analizzare il file package.json e installare le dipendenze elencate.After the application has been deployed, the npm install command is used to parse the package.json file and install all the dependencies listed.

In fase di sviluppo è possibile usare i parametri --save, --save-dev o --save-optional durante l'installazione dei moduli per aggiungere automaticamente una voce per il modulo al file package.json.During development, you can use the --save, --save-dev, or --save-optional parameters when installing modules to add an entry for the module to your package.json file automatically. Per ulteriori informazioni, vedere npm-install.For more information, see npm-install.

Un potenziale problema che può essere riscontrato con il file package.json è che specifica solo la versione delle dipendenze di livello superiore.One potential problem with the package.json file is that it only specifies the version for top-level dependencies. Ogni modulo installato può specificare o meno la versione dei moduli da cui dipende, pertanto è possibile che venga specificata una catena delle dipendenze diversa da quella utilizzata in fase di sviluppo.Each module installed may or may not specify the version of the modules it depends on, and so it is possible that you may end up with a different dependency chain than the one used in development.

Nota

Durante la distribuzione di Servizio app di Azure, se il file package.json fa riferimento a un modulo nativo, potrebbe essere visualizzato un errore simile all'esempio seguente durante la pubblicazione dell'applicazione tramite Git:When deploying to Azure App Service, if your package.json file references a native module you might see an error similar to the following example when publishing the application using Git:

npm ERR!npm ERR! module-name@0.6.0 install: 'node-gyp configure build'module-name@0.6.0 install: 'node-gyp configure build'

npm ERR!npm ERR! 'cmd "/c" "node-gyp configure build"' failed with 1'cmd "/c" "node-gyp configure build"' failed with 1

Utilizzare un file npm-shrinkwrap.jsonUsing a npm-shrinkwrap.json file

Il file npm-shrinkwrap.json costituisce un tentativo per risolvere i limiti relativi al controllo delle versioni dei moduli del file package.json.The npm-shrinkwrap.json file is an attempt to address the module versioning limitations of the package.json file. Mentre il file package.json include solo le versioni per i moduli di livello superiore, il file npm-shrinkwrap.json contiene i requisiti della versione per l'intera catena delle dipendenze dei moduli.While the package.json file only includes versions for the top-level modules, the npm-shrinkwrap.json file contains the version requirements for the full module dependency chain.

Quando l'applicazione è pronta per la produzione, è possibile bloccare i requisiti della versione e creare un file npm-shrinkwrap.json usando il comando npm shrinkwrap.When your application is ready for production, you can lock down version requirements and create an npm-shrinkwrap.json file by using the npm shrinkwrap command. Questo comando userà le versioni attualmente installate nella cartella node_modules, che verranno registrate nel file npm-shrinkwrap.json.This command will use the versions currently installed in the node_modules folder, and record these versions to the npm-shrinkwrap.json file. Dopo che l'applicazione è stata distribuita nell'ambiente host, viene usato il comando npm install per analizzare il file npm-shrinkwrap.json e installare le dipendenze elencate.After the application has been deployed to the hosting environment, the npm install command is used to parse the npm-shrinkwrap.json file and install all the dependencies listed. Per ulteriori informazioni, vedere npm-shrinkwrap.For more information, see npm-shrinkwrap.

Nota

Durante la distribuzione di Servizio app di Azure, se il file npm-shrinkwrap.json fa riferimento a un modulo nativo, potrebbe essere visualizzato un errore simile all'esempio seguente durante la pubblicazione dell'applicazione tramite Git:When deploying to Azure App Service, if your npm-shrinkwrap.json file references a native module you might see an error similar to the following example when publishing the application using Git:

npm ERR!npm ERR! module-name@0.6.0 install: 'node-gyp configure build'module-name@0.6.0 install: 'node-gyp configure build'

npm ERR!npm ERR! 'cmd "/c" "node-gyp configure build"' failed with 1'cmd "/c" "node-gyp configure build"' failed with 1

Passaggi successiviNext steps

Dopo avere imparato a usare i moduli Node.js con Azure, per altre informazioni vedere gli articoli che illustrano come specificare una versione di Node.js, compilare e distribuire un'App Web Node.js e usare l'interfaccia della riga di comando di Azure per Mac e Linux.Now that you understand how to use Node.js modules with Azure, learn how to [specify the Node.js version], build and deploy a Node.js web app, and [How to use the Azure Command-Line Interface for Mac and Linux].

Per ulteriori informazioni, vedere il Centro per sviluppatori di Node.js.For more information, see the Node.js Developer Center.