Node.js 使用 NPM 管理项目依赖

1. 什么是 NPM 以及为什么在 Node.js 项目中使用它

在 Node.js 的生态系统里，NPM（Node Package Manager）是一个极其重要的工具。它本质上是一个包管理器，用来帮助开发者管理项目所依赖的各种包（也称作模块）。

想象一下，在开发一个大型的 Node.js 应用程序时，我们可能需要用到各种各样的功能，比如处理 HTTP 请求、连接数据库、进行文件操作等等。而 Node.js 的社区非常活跃，有大量优秀的开发者已经编写好了各种各样功能的模块供我们使用。但是，如果没有一个好的方式来管理这些模块，项目很快就会变得混乱不堪。

NPM 就像是一个智能的管家，它可以帮助我们：

安装包：轻松地将所需的模块安装到项目中。比如，当我们想要在 Node.js 项目中使用 Express 框架来搭建一个 Web 服务器时，只需要一个简单的命令，NPM 就能把 Express 及其所有依赖的模块都下载并安装到项目目录中。
管理版本：不同的项目可能对同一个模块有不同的版本要求。NPM 允许我们精确指定所需模块的版本，确保项目在不同环境下的一致性。例如，某个项目依赖于 lodash 库的 1.0.0 版本，而另一个项目可能需要 2.0.0 版本，NPM 能够很好地管理这种差异。
共享与发布包：如果你开发了一个优秀的 Node.js 模块，NPM 提供了一个平台，让你可以将这个模块发布出去，供其他开发者使用。

2. 初始化一个 Node.js 项目并使用 NPM

2.1 创建项目目录

首先，我们需要创建一个新的 Node.js 项目目录。在命令行中，使用以下命令创建一个名为 my - project 的目录：

mkdir my - project
cd my - project

这个新目录将是我们项目的根目录，所有相关的文件和依赖都会放在这里。

2.2 初始化 NPM 项目

进入项目目录后，我们使用 npm init 命令来初始化一个 NPM 项目。执行该命令后，NPM 会引导我们完成一系列的配置步骤，比如项目名称、版本、描述、入口文件等等。

npm init

在初始化过程中，NPM 会询问一系列问题，以下是一些常见问题及其含义：

package name：项目名称，通常与项目目录名称一致。例如，我们的项目目录是 my - project，这里可以输入 my - project。
version：项目版本号，遵循语义化版本号规范 MAJOR.MINOR.PATCH。初始版本通常可以设为 1.0.0。
description：项目的简短描述，有助于其他开发者了解项目的用途。
entry point：项目的入口文件，对于大多数 Node.js 项目，这通常是 index.js 或 app.js。
test command：用于运行测试的命令。如果项目还没有测试相关的配置，可以留空。
git repository：项目的 Git 仓库地址，如果项目使用 Git 进行版本控制，可以填写相应的 Git 仓库 URL。
keywords：与项目相关的关键词，方便其他开发者在 NPM 上搜索到我们的项目。
author：项目作者的信息。
license：项目的许可证，常见的如 MIT、Apache - 2.0 等。如果不确定，MIT 是一个比较宽松且常用的许可证。

在回答完所有问题后，NPM 会在项目根目录下生成一个 package.json 文件。这个文件非常重要，它记录了项目的所有元数据以及项目所依赖的包及其版本信息。

3. 使用 NPM 安装项目依赖

3.1 安装生产依赖

生产依赖是指项目在运行时所必需的模块。例如，当我们开发一个基于 Express 的 Web 应用时，Express 就是一个生产依赖。

要安装一个生产依赖，我们使用 npm install 命令加上包名。例如，安装 Express 包：

npm install express

执行上述命令后，NPM 会从 NPM 注册表（默认是 https://registry.npmjs.org/）下载 Express 包及其所有依赖，并将它们安装到项目目录下的 node_modules 文件夹中。同时，package.json 文件会自动更新，在 dependencies 字段中添加 express 及其版本信息。

{
  "name": "my - project",
  "version": "1.0.0",
  "description": "My Node.js project",
  "main": "index.js",
  "dependencies": {
    "express": "^4.18.2"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Your Name",
  "license": "MIT"
}

这里版本号前面的 ^ 符号表示允许安装该包的兼容的最新版本。例如，^4.18.2 表示只要主版本号还是 4，就可以安装后续的小版本和补丁版本（如 4.18.3、4.19.0 等）。

3.2 安装开发依赖

开发依赖是指在项目开发过程中使用，但在生产环境中不需要的模块。例如，用于测试的 mocha 和 chai，用于代码检查的 eslint 等。

要安装开发依赖，我们使用 npm install --save - dev 命令（也可以简写成 npm install - D）加上包名。例如，安装 mocha 作为开发依赖：

npm install --save - dev mocha

同样，NPM 会将 mocha 及其依赖安装到 node_modules 文件夹中，并且在 package.json 文件的 devDependencies 字段中添加 mocha 及其版本信息。

{
  "name": "my - project",
  "version": "1.0.0",
  "description": "My Node.js project",
  "main": "index.js",
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "mocha": "^10.2.0"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Your Name",
  "license": "MIT"
}

4. 理解 NPM 版本号与语义化版本控制

4.1 语义化版本号规范

语义化版本号采用 MAJOR.MINOR.PATCH 的格式，其中：

MAJOR：主版本号，当进行不兼容的 API 修改时，主版本号递增。例如，从 1.x.x 升级到 2.x.x，可能意味着很多接口、方法的使用方式发生了改变，原有的代码可能无法直接运行。
MINOR：次版本号，当以向后兼容的方式添加新功能时，次版本号递增。例如，在 1.0.0 版本基础上添加了一些新的功能模块，版本号可能变为 1.1.0，原有的代码通常可以继续正常运行。
PATCH：补丁版本号，当进行向后兼容的错误修复时，补丁版本号递增。例如，修复了 1.0.0 版本中的一个 bug，版本号可能变为 1.0.1。

4.2 NPM 版本号前缀

在 package.json 文件中，我们会看到版本号前面有一些前缀，常见的有：

^：允许安装兼容的最新版本。例如，^1.2.3 表示可以安装 1.2.4、1.3.0 等，但不能安装 2.0.0。
~：允许安装指定版本号的最新补丁版本。例如，~1.2.3 表示可以安装 1.2.4，但不能安装 1.3.0。
无前缀：固定安装指定版本，不会自动升级到任何其他版本。例如，1.2.3 就只会安装 1.2.3 版本。

5. 管理项目依赖的生命周期

5.1 更新依赖

随着时间推移，我们安装的包可能会发布新的版本，这些新版本可能包含新功能、性能优化或 bug 修复。我们可以使用 npm update 命令来更新项目的依赖。

如果要更新所有依赖，可以在项目根目录下执行：

npm update

NPM 会根据 package.json 文件中指定的版本范围，更新所有可更新的依赖到最新的兼容版本。

如果只想更新某个特定的依赖，比如 express，可以执行：

npm update express

需要注意的是，更新依赖有时可能会引入兼容性问题，尤其是当更新涉及到主版本号的变化时。因此，在更新依赖后，一定要进行充分的测试。

5.2 删除依赖

当项目不再需要某个依赖时，可以使用 npm uninstall 命令来删除它。

如果要删除生产依赖，例如 express，执行：

npm uninstall express

这会从 node_modules 文件夹中移除 express 及其相关依赖，并且会从 package.json 文件的 dependencies 字段中删除 express 的记录。

如果要删除开发依赖，例如 mocha，执行：

npm uninstall --save - dev mocha

或者

npm uninstall - D mocha

这会从 node_modules 文件夹中移除 mocha 及其相关依赖，并从 package.json 文件的 devDependencies 字段中删除 mocha 的记录。

6. 使用 `package - lock.json` 文件

6.1 `package - lock.json` 的作用

当我们使用 NPM 安装依赖时，除了 package.json 文件，还会生成一个 package - lock.json 文件。这个文件记录了项目依赖的每个包的精确版本以及它们之间的依赖关系树。

它的主要作用有：

确保一致性：在不同的开发环境或部署环境中，package - lock.json 能保证安装的依赖版本完全一致。因为 package.json 中的版本号可能只是一个范围，不同时间安装可能会得到不同的具体版本，但 package - lock.json 记录的是确切的版本。
提高安装速度：NPM 在安装依赖时，如果 package - lock.json 文件存在，会根据其中记录的版本信息直接下载相应的包，而不需要再次解析依赖关系和查找合适的版本，从而加快安装过程。

6.2 与 `package.json` 的关系

package.json 定义了项目的依赖及其版本范围，而 package - lock.json 则记录了实际安装的依赖的精确版本。当我们使用 npm install 命令安装依赖时，如果 package - lock.json 文件不存在，NPM 会根据 package.json 中的版本范围解析并安装依赖，同时生成 package - lock.json 文件。如果 package - lock.json 文件已存在，NPM 会优先使用其中记录的版本进行安装，除非我们使用 npm install --force 等命令强制重新解析依赖。

7. 发布自己的 Node.js 包到 NPM 注册表

7.1 准备工作

在发布包之前，我们需要确保以下几点：

编写好代码：包的代码逻辑要完整、测试通过，并且功能符合预期。
配置 package.json：package.json 文件中的各项信息要准确，包括 name、version、description、main 等字段。name 要保证在 NPM 注册表中是唯一的，避免与其他已发布的包重名。
添加许可证：在 package.json 中指定合适的许可证，如 MIT、Apache - 2.0 等，明确包的使用权限。

7.2 登录 NPM

首先，我们需要在命令行中登录到 NPM 注册表。如果还没有 NPM 账号，可以在 https://www.npmjs.com/ 上注册一个。在命令行中执行：

npm login

然后按照提示输入用户名、密码和邮箱地址。

7.3 发布包

登录成功后，在项目根目录下执行：

npm publish

如果发布成功，我们的包就会出现在 NPM 注册表上，其他开发者可以通过 npm install <package - name> 来安装使用我们的包。

需要注意的是，如果包的 version 字段与之前发布的版本相同，NPM 会拒绝发布，提示版本冲突。因此，每次发布新的版本时，要记得更新 package.json 中的 version 字段。

8. 使用私有 NPM 注册表

8.1 为什么使用私有 NPM 注册表

在企业开发中，有些内部使用的 Node.js 包可能不适合公开到公共的 NPM 注册表上，这时就需要使用私有 NPM 注册表。私有 NPM 注册表可以提供安全的、仅内部可用的包管理服务，保护企业的代码资产。

8.2 搭建私有 NPM 注册表

有多种方式可以搭建私有 NPM 注册表，其中一种常用的工具是 verdaccio。

首先，确保已经安装了 Node.js 和 NPM。然后，使用以下命令全局安装 verdaccio：

npm install -g verdaccio

安装完成后，执行 verdaccio 命令启动私有 NPM 注册表服务。默认情况下，它会监听在 http://localhost:4873 地址上。

8.3 使用私有 NPM 注册表

要使用私有 NPM 注册表，我们需要配置 NPM 的注册表地址。可以通过以下命令临时设置：

npm config set registry http://localhost:4873

或者，通过修改 ~/.npmrc 文件（Windows 下是 %USERPROFILE%\.npmrc）来永久设置：

registry = http://localhost:4873

之后，我们就可以像使用公共 NPM 注册表一样，在私有 NPM 注册表上安装、发布和管理包了。

9. 常见的 NPM 命令与技巧

9.1 `npm list` 命令

npm list 命令用于查看项目安装的所有依赖及其版本信息。在项目根目录下执行：

npm list

这会以树形结构列出项目的所有依赖，包括直接依赖和间接依赖。例如：

my - project@1.0.0 /path/to/my - project
├── express@4.18.2
│   ├── accepts@1.3.8
│   │   ├── negotiator@0.6.3
│   │   └── utils - merge@1.0.1
│   ├── array - flatten@1.1.1
│   ├── body - parser@1.20.2
│   │   ├── bytes@3.1.1
│   │   ├── content - type@1.0.4
│   │   ├── cookie - parse@1.4.6
│   │   ├── depd@2.0.0
│   │   ├── http - errors@2.0.0
│   │   ├── iconv - lite@0.6.3
│   │   ├── on - headers@2.0.1
│   │   ├── qs@6.11.0
│   │   └── raw - body@2.4.1
│   ├── content - type@1.0.4
│   ├── cookie - parser@1.4.6
│   ├── debug@4.3.4
│   ├── depd@2.0.0
│   ├── encodeurl@1.0.2
│   ├── escape - html@1.0.5
│   ├── etag@1.8.2
│   ├── finalhandler@1.2.0
│   ├── fresh@1.3.0
│   ├── http - errors@2.0.0
│   ├── invariant@2.2.4
│   ├── merge - fresh@1.1.3
│   ├── methods@1.1.2
│   ├── on - headers@2.0.1
│   ├── parseurl@1.3.3
│   ├── path - to - regexp@0.1.7
│   ├── proxy - addr@2.0.7
│   ├── qs@6.11.0
│   ├── range - parser@1.2.1
│   ├── safe - buffer@5.2.1
│   ├── send@0.18.0
│   ├── serve - static@1.15.0
│   ├── setprototypeof@1.2.0
│   ├── statuses@2.0.1
│   ├── type - is@1.6.18
│   ├── utils - merge@1.0.1
│   └── vary@1.1.2
└── mocha@10.2.0
    ├── anymatch@3.1.2
    │   ├── micromatch@4.0.8
    │   │   ├── arr - flatten@1.1.1
    │   │   ├── braces@3.0.2
    │   │   ├── expand - range@3.0.2
    │   │   ├── fill - range@7.0.1
    │   │   ├── is - glob@4.0.1
    │   │   ├── kind - of@8.0.0
    │   │   ├── normalize - path@3.0.0
    │   │   ├── object.omit@3.0.1
    │   │   ├── parse - glob@5.0.1
    │   │   ├── regex - escape@3.0.1
    │   │   └── snapdragon@0.8.2
    │   │       ├── source - map@0.6.1
    │   │       └── snapdragon - node@1.1.1
    │   └── path - is - absolute@1.0.1
    ├── archy@1.0.0
    ├── balanced - match@1.0.2
    ├── bn.js@6.2.1
    ├── braces@3.0.2
    ├── browser - globals@1.11.1
    ├── callsites@4.0.0
    ├── chokidar@3.5.3
    ├── cli - ui@8.0.1
    ├── columnify@1.6.0
    ├── commander@8.3.1
    ├── debug@4.3.4
    ├── diff@5.0.0
    ├── escape - string - regexp@4.0.0
    ├── expand - range@3.0.2
    ├── fast - deep - equal@3.1.3
    ├── fill - range@7.0.1
    ├── glob@7.2.3
    ├── inherits@2.0.4
    ├── is - arrayish@0.3.2
    ├── is - buffer@1.0.2
    ├── is - glob@4.0.1
    ├── is - object@3.0.1
    ├── is - promise@3.0.1
    ├── is - windows@1.0.2
    ├── kind - of@8.0.0
    ├── locate - stack@2.0.0
    ├── make - error@1.3.6
    ├── micromatch@4.0.8
    ├── minimatch@3.1.2
    ├── ms@2.1.2
    ├── node - for - each@1.0.0
    ├── object.omit@3.0.1
    ├── on - exit@1.2.0
    ├── parse - glob@5.0.1
    ├── path - is - absolute@1.0.1
    ├── process - nextick - callback@2.0.1
    ├── proxyquire@2.1.3
    ├── regex - escape@3.0.1
    ├── resolve@1.22.1
    ├── snapdragon@0.8.2
    ├── source - map@0.6.1
    ├── source - map - support@0.5.21
    ├── string_decoder@1.3.1
    ├── supports - color@9.3.0
    ├── text - table@0.2.0
    ├── unpipe@1.0.0
    └── util - deprecate@1.0.2

如果只想查看直接依赖，可以使用 npm list --depth = 0 命令。

9.2 `npm cache` 命令

NPM 会缓存下载的包，以提高后续安装的速度。但是，有时缓存可能会出现问题，导致安装失败或安装的版本不正确。这时可以使用 npm cache 命令来清理缓存。

清理整个 NPM 缓存：

npm cache clean --force

9.3 使用别名

在 package.json 的 scripts 字段中，我们可以定义一些自定义的命令别名。例如，如果我们经常要运行 node app.js 命令来启动项目，可以在 package.json 中添加：

{
  "scripts": {
    "start": "node app.js"
  }
}

之后，就可以使用 npm start 来代替 node app.js 命令启动项目了。

10. 解决 NPM 安装依赖时的常见问题

10.1 网络问题

NPM 从远程注册表下载包，因此网络连接不稳定可能会导致安装失败。常见的网络问题及解决方法有：

超时问题：如果下载过程中出现超时错误，可以尝试增加 npm install 命令的超时时间。例如，将超时时间设置为 60000 毫秒（60 秒）：

npm install --timeout = 60000

代理问题：如果在公司内部网络或使用代理服务器的环境中，需要配置 NPM 的代理。可以通过以下命令设置代理：

npm config set proxy http://proxy.example.com:8080
npm config set https - proxy http://proxy.example.com:8080

如果代理需要认证，格式为 http://username:password@proxy.example.com:8080。

10.2 版本冲突问题

当多个依赖对同一个包有不同的版本要求时，可能会出现版本冲突。NPM 会尽量安装一个兼容的版本，但有时可能无法自动解决。

解决版本冲突的方法有：

手动调整版本：在 package.json 文件中，手动调整相关依赖的版本范围，使其兼容。例如，如果 packageA 依赖 lodash@1.0.0，而 packageB 依赖 lodash@2.0.0，可以尝试将 packageA 的 lodash 版本范围调整为兼容 2.0.0 的版本，如 ^2.0.0。
使用 npm - resolve - conflict 工具：这是一个第三方工具，可以帮助分析和解决 NPM 依赖版本冲突。首先安装该工具：

npm install -g npm - resolve - conflict

然后在项目根目录下执行：

npm - resolve - conflict

该工具会分析项目的依赖关系，找出版本冲突，并提供可能的解决方案。

10.3 权限问题

在某些操作系统（如 Linux 和 macOS）中，如果使用 npm install 命令时没有足够的权限，可能会导致安装失败。例如，在全局安装包时可能会遇到权限不足的错误。

解决方法是使用 sudo 命令（在 Linux 和 macOS 下）以管理员权限运行 npm install。但不建议经常使用 sudo npm install，因为这可能会导致文件权限问题。更好的方法是将 NPM 的全局安装目录设置为一个用户可写的目录。可以通过以下命令设置：

npm config set prefix ~/.npm - global

然后将 ~/.npm - global/bin 添加到系统的 PATH 环境变量中。这样，就可以在不使用 sudo 的情况下全局安装包了。

通过以上内容，相信你对在 Node.js 项目中使用 NPM 管理项目依赖有了全面且深入的了解。无论是小型项目还是大型企业级应用，合理使用 NPM 能够极大地提高开发效率和项目的可维护性。