将 Node.js 模块与 Azure 应用程序一起使用Using Node.js Modules with Azure applications

本文档提供有关将 Node.js 模块与托管在 Azure 中的应用程序一起使用的指南。This document provides guidance on using Node.js modules with applications hosted on Azure. 其中提供有关确保应用程序使用特定版本的模块以及对 Azure 使用本机模块的指南。It provides guidance on ensuring that your application uses a specific version of a module as well as using native modules with Azure.

如果已了解如何使用 Node.js 模块、package.json 和 npm-shrinkwrap.json 文件,可参阅以下信息快速概览本文讨论的内容: 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:

  • Azure 应用服务了解 package.jsonnpm-shrinkwrap.json 文件,可基于这些文件中的条目安装模块。Azure App Service understands package.json and npm-shrinkwrap.json files and can install modules based on entries in these files.

  • Azure 云服务需要所有模块都安装在开发环境中,并将 node_modules 目录包含为部署包的一部分。Azure Cloud Services expects all modules to be installed on the development environment, and the node_modules directory to be included as part of the deployment package. 可为使用 package.json 或 npm-shrinkwrap.json 文件在云服务上安装模块提供相应支持,但此配置需要自定义云服务项目使用的默认脚本。 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. 有关如何配置此环境的示例,请参阅运行 npm install 避免部署 Node 模块的 Azure 启动任务For an example of how to configure this environment, see Azure Startup task to run npm install to avoid deploying node modules

备注

本文不讨论 Azure 虚拟机,因为 VM 中的开发体验取决于虚拟机托管的操作系统。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.

Node.js 模块Node.js Modules

模块是可加载的 JavaScript 包,可为应用程序提供特定功能。Modules are loadable JavaScript packages that provide specific functionality for your application. 通常使用 npm 命令行工具安装模块,但一些模块(如 http 模块)作为核心 Node.js 包的一部分提供。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.

在安装模块后,这些模块存储在应用程序目录结构根目录下的 node_modules 目录中。When modules are installed, they are stored in the node_modules directory at the root of your application directory structure. node_modules 目录中的每个模块都保留自己的目录,其中包含它依赖的所有模块,此行为对于依赖项链上的每个模块均是如此。Each module within the node_modules directory maintains its own directory that contains any modules that it depends on, and this behavior repeats for every module all the way down the dependency chain. 此环境使得安装的每个模块均对其依赖的模块具有自己的版本要求,但这会导致目录结构很大。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.

与使用 package.json 或 npm-shrinkwrap.json 文件相比时,随附应用程序部署 node_modules 目录会增加部署的大小;但是,它确实可保证生产中使用的模块版本与开发中使用的相同。 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.

本机模块Native Modules

虽然多数模块都只是纯文本 JavaScript 文件,但一些模块是特定于平台的二进制映像。While most modules are simply plain-text JavaScript files, some modules are platform-specific binary images. 这些模块通常是在安装时使用 Python 和 node-gyp 编译的。These modules are compiled at install time, usually by using Python and node-gyp. 由于 Azure 云服务依赖作为应用程序一部分部署的 node_modules 文件夹,因此只要作为已安装模块一部分包含的任何本机模块是在 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.

Azure 应用服务不支持部分本机模块,并且在编译具有特定先决条件的模块时可能失败。Azure App Service does not support all native modules, and might fail when compiling modules with specific prerequisites. 虽然一些常用模块(如 MongoDB)可选择性使用本机依赖项,且没有这些依赖项也可正常工作,但经证明有两种解决方法几乎可成功适用于当今所有本机模块: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:

  • 在安装了所有系统必备组件的 Windows 计算机运行 npm installRun npm install on a Windows machine that has all the native module's prerequisites installed. 然后,将创建的 node_modules 文件夹作为应用程序的一部分部署到 Azure 应用服务。Then, deploy the created node_modules folder as part of the application to Azure App Service.

    • 在编译之前, 检查本地 Node.js 安装是否具有匹配的体系结构以及版本是否尽可能接近在 Azure 中使用的版本(可以在运行时从属性 process.archprocess.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).
  • 可以将 Azure 应用服务配置为在部署期间执行自定义 bash 或 shell 脚本,以便能够执行自定义命令并精确配置 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. 有关演示如何配置该环境的视频,请参阅使用 Kudu 自定义网站部署脚本For a video showing how to configure that environment, see Custom Website Deployment Scripts with Kudu.

使用 package.json 文件Using a package.json file

可使用 package.json 文件来指定应用程序所需的顶级依赖项,以便托管平台能够安装这些依赖项,而不是要求在部署中包含 node_modules 文件夹。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. 部署应用程序后,可使用 npm install 命令分析 package.json 文件并安装列出的所有依赖项。After the application has been deployed, the npm install command is used to parse the package.json file and install all the dependencies listed.

在开发期间,可以在安装模块时使用 --save--save-dev--save-optional 参数,自动将模块条目添加到 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. 有关详细信息,请参阅 npm-installFor more information, see npm-install.

package.json 文件的一个潜在问题是它仅指定顶级依赖项的版本。One potential problem with the package.json file is that it only specifies the version for top-level dependencies. 安装的每个模块不一定会指定它所依赖的模块的版本,因此最终使用的依赖项链可能与开发过程中使用的不同。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.

备注

部署到 Azure 应用服务时,如果 package.json 文件引用本机模块,在使用 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

使用 npm-shrinkwrap.json 文件Using a npm-shrinkwrap.json file

npm-shrinkwrap.json 文件用于尝试消除 package.json 文件的模块版本控制限制。The npm-shrinkwrap.json file is an attempt to address the module versioning limitations of the package.json file. 虽然 package.json 文件仅包含顶级模块的版本,但 npm-shrinkwrap.json 文件包含所有模块依赖项链的版本要求。 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.

应用程序准备好生产后,便可锁定版本要求,使用 npm shrinkwrap 命令创建 npm-shrinkwrap.json 文件。 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. 此命令会使用当前安装在 node_modules 文件夹中的版本,并将这些版本记录到 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. 将应用程序部署到托管环境后,可使用 npm install 命令来分析 npm-shrinkwrap.json 文件并安装列出的所有依赖项。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. 有关详细信息,请参阅 npm-shrinkwrapFor more information, see npm-shrinkwrap.

备注

部署到 Azure 应用服务时,如果 npm-shrinkwrap.json 文件引用本机模块,在使用 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

后续步骤Next steps

了解如何将 Node.js 模块与 Azure 一起使用后,请学习如何指定 Node.js 版本生成和部署 Node.js Web 应用,以及如何使用适用于 Mac 和 Linux 的 Azure 命令行接口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.

有关详细信息,请参阅 Node.js 开发人员中心For more information, see the Node.js Developer Center.