---

Node.js包管理器npm使用教程（基础篇）

在现代Web开发，尤其是Node.js生态系统中，包（Package）或模块（Module）是构建应用程序的基石。它们是可重用的代码单元，封装了特定的功能，允许开发者不必从零开始编写所有代码，而是可以利用社区已经创建和测试过的解决方案。Node.js自带了一个强大的官方包管理器，名为npm（Node Package Manager），它是世界上最大的软件注册表之一，让开发者能够轻松地发现、共享和使用代码包。本教程将详细介绍npm的基础使用方法，帮助您掌握在Node.js项目中管理依赖的核心技能。

一、 什么是npm？

npm最初代表Node Package Manager，但随着其生态系统的发展，它已不仅仅局限于Node.js包的管理。它主要包含三个组成部分：

1. 网站（npmjs.com）： 这是一个公共的在线数据库（注册表 Registry），开发者可以在这里查找、发现数以百万计的公开包，并发布自己的包。
2. 命令行工具（CLI）： 这是开发者在终端或命令行界面中与npm交互的主要方式。通过npm CLI，可以安装、卸载、更新包，管理项目依赖，运行脚本等。这个工具通常随着Node.js的安装而一同安装。
3. 注册表（Registry）： 这是存储包信息和代码的大型数据库。默认情况下，npm CLI连接到官方的公共npm注册表。

为什么需要npm？

• 代码复用： 轻松利用他人编写好的功能模块，避免重复造轮子。
• 依赖管理： 自动化地管理项目所依赖的各种包及其版本，确保项目环境的一致性和可复现性。
• 版本控制： 精确控制项目使用的包的版本，避免因版本不兼容导致的问题。
• 社区协作： 便于开发者共享自己的代码包，促进开源社区的发展。
• 项目脚本： 提供一种标准化的方式来运行项目相关的任务（如启动、测试、构建）。

二、 安装与环境准备

通常情况下，当你安装Node.js时，npm就已经被自动安装好了。你可以通过在终端（Terminal）或命令提示符（Command Prompt）中运行以下命令来验证安装是否成功以及查看它们的版本：

bash
node -v
npm -v

如果这两个命令都能成功输出版本号（例如 v18.16.0 和 9.5.1），那么你的开发环境就已经准备就绪了。如果提示命令未找到，你需要先去Node.js官网（nodejs.org）下载并安装适合你操作系统的Node.js版本。

三、 初始化你的Node.js项目

在使用npm管理项目依赖之前，你需要先创建一个项目目录，并在该目录下初始化npm项目。初始化过程会生成一个名为 package.json 的核心文件。

1. 创建项目目录：
   在你的工作区选择一个位置，创建一个新的文件夹作为你的项目根目录。例如：

   bash
mkdir my-node-app
cd my-node-app

2. 初始化项目：
   在项目根目录下运行 npm init 命令。

   bash
npm init

   这个命令会启动一个交互式的问答过程，引导你设置项目的基本信息。它会询问你以下内容（括号内是默认值或建议）：

   • package name: (文件夹名 my-node-app) – 包的名称，通常是小写字母和连字符。
   • version: (1.0.0) – 项目的初始版本号，遵循语义化版本（Semantic Versioning）规范。
   • description: (空) – 项目的简短描述。
   • entry point: (index.js) – 项目的主入口文件，当别人require()你的包时，默认加载这个文件。
   • test command: (空) – 运行测试用例的命令。
   • git repository: (空) – 项目的Git仓库地址。
   • keywords: (空) – 一些关键字，便于在npm网站上搜索到你的包。
   • author: (空) – 作者信息。
   • license: (ISC) – 项目的开源许可证。

   你可以直接按回车键接受默认值，或者输入你自己的信息。完成所有问题后，npm会显示即将生成的 package.json 内容，并询问 Is this OK? (yes)。输入 yes 或直接按回车确认。

   如果你想跳过所有问题并使用默认值快速生成 package.json，可以使用 -y 或 --yes 标志：

   bash
npm init -y

3. package.json 文件详解：
   初始化完成后，你的项目根目录下会多出一个 package.json 文件。这是一个JSON格式的文件，它是你项目的“身份证”和“说明书”，记录了项目的元数据和依赖信息。一个典型的 package.json 文件内容可能如下：

   json
{
"name": "my-node-app",
"version": "1.0.0",
"description": "A simple Node.js application",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node index.js"
},
"keywords": ["node", "app", "example"],
"author": "Your Name <[email protected]>",
"license": "ISC",
"dependencies": {},
"devDependencies": {}
}

   关键字段说明：
   * name: 包名，必须是唯一的（如果计划发布到npm）。
   * version: 当前版本号。
   * description: 包的描述。
   * main: 包的入口文件。
   * scripts: 定义了一些可以通过 npm run <script-name> 执行的脚本命令。例如 npm start 会执行 node index.js。
   * keywords: 搜索关键字。
   * author: 作者信息。
   * license: 许可证类型。
   * dependencies: 项目运行时所必需的依赖包列表。这些包会被部署到生产环境。
   * devDependencies: 项目开发时所需要的依赖包列表（例如测试框架、构建工具、代码检查工具）。这些包通常不会被部署到生产环境。

四、 安装依赖包

npm最核心的功能之一就是安装依赖包。

1. 安装生产依赖（Dependencies）：
   假设你的项目需要使用一个非常流行的工具库 lodash。要将其添加为项目的生产依赖，运行以下命令：

   “`bash
   npm install lodash

   或者使用简写

   npm i lodash
   “`

   执行这个命令后，npm会做几件事情：
   * 下载包： 从npm注册表下载 lodash 包及其所有依赖的包。
   * 创建 node_modules 目录： 如果尚不存在，会在项目根目录下创建一个 node_modules 文件夹，并将下载的所有包都存放在这里。这个目录通常非常庞大，不应该提交到版本控制系统（如Git），一般会在 .gitignore 文件中添加 node_modules/。
   * 更新 package.json： 自动将 lodash 及其版本号添加到 package.json 文件的 dependencies 字段中。例如：
   json
"dependencies": {
"lodash": "^4.17.21"
}
   这里的 ^4.17.21 表示接受 lodash 的 4.17.21 版本以及之后的所有次版本（minor）和补丁版本（patch）更新，但不接受主版本（major）的更新（例如 5.x.x）。这是npm默认的版本范围表示法，有助于在保持兼容性的前提下获取更新。
   * 生成/更新 package-lock.json 文件： 这个文件后面会详细介绍，它精确记录了当前安装的每个包的具体版本号及其依赖树结构，确保团队成员或不同环境中安装依赖时得到完全一致的结果。这个文件应该提交到版本控制系统。

2. 安装开发依赖（DevDependencies）：
   假设你需要一个开发服务器工具 nodemon，它可以在你修改代码后自动重启Node.js应用，非常适合开发阶段。这种只在开发时使用的工具，应该作为开发依赖安装：

   “`bash
   npm install nodemon –save-dev

   或者使用简写

   npm i nodemon -D
   “`

   --save-dev 或 -D 标志告诉npm将这个包添加到 package.json 的 devDependencies 字段中：

   json
"devDependencies": {
"nodemon": "^2.0.20"
}

3. 安装指定版本的包：
   如果你需要安装特定版本的包，可以在包名后面加上 @<version>：

   “`bash

   安装 lodash 的 4.17.0 版本

   npm install [email protected]

   安装 lodash 的最新 3.x 版本

   npm install lodash@^3.0.0
   “`

4. 全局安装（Global Installation）：
   有些npm包是命令行工具，你可能希望在系统的任何目录下都能直接运行它们，而不是局限于某个项目。这时可以使用全局安装，添加 -g 标志：

   bash
npm install -g http-server

   这样安装后，你就可以在任何目录下打开终端，运行 http-server 命令来快速启动一个本地静态文件服务器。
   注意： 全局安装的包不会被记录在项目的 package.json 中，它们是安装在你的系统环境中，而不是项目本地。对于项目运行所必需的依赖，永远不要使用全局安装，必须进行本地安装。全局安装主要适用于独立的CLI工具。

5. 一次性安装 package.json 中的所有依赖：
   当你从版本控制系统（如Git）克隆了一个项目，或者与他人协作时，你通常会得到一个包含 package.json 但没有 node_modules 目录的项目副本。这时，只需要在项目根目录下运行：

   “`bash
   npm install

   或者

   npm i
   “`

   npm会读取 package.json 和 package-lock.json 文件，自动下载并安装所有在 dependencies 和 devDependencies 中声明的依赖包到 node_modules 目录。

五、 使用已安装的包

安装了依赖包之后，你就可以在你的Node.js代码（通常是 index.js 或其他 .js 文件）中引入并使用它们了。Node.js使用CommonJS模块系统（require）或ES模块系统（import，需要在package.json中设置"type": "module"或使用.mjs扩展名）。

使用 require (CommonJS – 默认)：

“`javascript
// index.js

// 引入安装的 lodash 包
const _ = require(‘lodash’);

// 使用 lodash 的功能
const numbers = [1, 2, 3, 4, 5];
const shuffledNumbers = _.shuffle(numbers);

console.log(‘Original numbers:’, numbers);
console.log(‘Shuffled numbers:’, shuffledNumbers);

const chunkedArray = _.chunk([‘a’, ‘b’, ‘c’, ‘d’], 2);
console.log(‘Chunked array:’, chunkedArray);
“`

当你运行 node index.js 时，Node.js会在当前目录的 node_modules 文件夹中查找名为 lodash 的包，并加载其主文件（由 lodash 包自己的 package.json 中的 main 字段指定），然后你就可以使用 _ 变量访问 lodash 提供的功能了。

六、 管理依赖

随着项目的进展，你可能需要更新、查看或移除依赖。

1. 查看已安装的包：
   列出当前项目安装的所有包（包括它们的依赖）：

   “`bash
   npm list

   或者简写

   npm ls
   “`

   这个列表可能会很长。如果只想看顶层（直接安装的）依赖，可以指定深度：

   bash
npm list --depth=0

2. 检查可更新的包：
   查看哪些已安装的包有新版本可用（根据 package.json 中定义的版本范围）：

   bash
npm outdated

3. 更新包：

   • 更新所有可更新的包到 package.json 允许的最新版本：

     bash
npm update

   • 更新指定的包：

     bash
npm update lodash

   • 注意： npm update 只会根据 package.json 中定义的版本范围（如 ^4.17.21）进行更新。如果想升级到超出范围的新主版本（例如从 4.x 升级到 5.x），你需要显式地重新安装：

     “`bash

     升级 lodash 到最新的主版本

     npm install lodash@latest
     ``
或者使用专门的工具如npm-check-updates(需要先npm install -g npm-check-updates`) 来管理主版本升级。

4. 卸载包：
   从项目中移除一个包：

   “`bash
   npm uninstall lodash

   或者简写

   npm un lodash

   或者

   npm rm lodash
   “`

   这个命令会：
   * 从 node_modules 目录中删除该包。
   * 从 package.json 的 dependencies 或 devDependencies 中移除对应的条目。
   * 更新 package-lock.json 文件。

   如果要卸载的是开发依赖，最好也加上 -D 或 --save-dev 标志（虽然npm通常能自动判断，但显式指定更清晰）：

   bash
npm uninstall nodemon --save-dev

七、 理解 package-lock.json

前面多次提到 package-lock.json 文件。这个文件非常重要，它的作用是：

• 锁定依赖版本： 它精确地记录了你在执行 npm install 或 npm update 时，实际安装到 node_modules 目录中的每一个包（包括依赖的依赖）的确切版本号、下载地址 (resolved) 和 内容哈希值 (integrity)。
• 确保一致性： 当团队其他成员、持续集成（CI）服务器或部署环境执行 npm install 时，npm会优先使用 package-lock.json 来确定安装哪些版本的包，而不是仅仅依赖 package.json 中的版本范围。这保证了无论何时何地安装依赖，得到的 node_modules 结构都是完全一样的，避免了“在我机器上能跑”的问题。
• 优化安装速度： 由于版本和依赖关系已经确定，npm可以跳过一些版本解析的步骤，加快安装速度。

关键点：
* package-lock.json 是自动生成的，不应该手动修改它。
* 必须将 package-lock.json 文件提交到你的版本控制系统（如Git）。

八、 使用 npm run 执行脚本

package.json 文件中的 scripts 字段允许你定义一些常用的项目命令。这是一个强大的功能，可以统一项目的构建、测试、启动等操作。

在上面 package.json 示例中，我们有：

json
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node index.js"
}

你可以通过 npm run <script-name> 来执行这些脚本：

• 运行 start 脚本：

  bash
npm run start

  对于 start 这个特殊的脚本名称，你甚至可以省略 run：

  bash
npm start

  这会执行 node index.js 命令。

• 运行 test 脚本：

  “`bash
  npm run test

  或者

  npm test
  “`

  这会执行 echo "Error: no test specified" && exit 1。

你可以定义任何你需要的脚本。例如，如果你安装了 nodemon 作为开发依赖，可以添加一个 dev 脚本来使用 nodemon 启动应用：

json
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"start": "node index.js",
"dev": "nodemon index.js"
}

然后通过 npm run dev 来启动开发服务器。npm会自动将 ./node_modules/.bin 目录添加到执行脚本时的 PATH 环境变量中，所以即使 nodemon 是本地安装的，你也可以在 scripts 中直接调用它，而无需写完整路径 node_modules/.bin/nodemon。

除了 start 和 test，还有一些其他特殊的脚本名称，如 stop, restart 等，它们也有对应的简写命令（例如 npm stop）。

九、 查找包

如果你想寻找解决特定问题的包，可以在npm的官方网站 https://www.npmjs.com/ 上进行搜索。网站提供了强大的搜索功能，你可以看到包的文档、版本历史、下载量、依赖关系、开源许可证等信息，帮助你评估和选择合适的包。

虽然npm CLI也提供了 npm search <keyword> 命令，但它返回的信息不如网站丰富直观，通常推荐直接使用网站进行查找。

十、 总结

npm是Node.js开发中不可或缺的工具。通过本篇基础教程，你应该掌握了：

• npm是什么及其重要性。
• 如何检查npm安装并初始化一个npm项目（npm init）。
• package.json 文件的核心作用和关键字段。
• 如何安装生产依赖（npm install <package>）和开发依赖（npm install <package> -D）。
• 本地安装与全局安装的区别。
• node_modules 目录和 package-lock.json 文件的意义及管理（后者应提交到版本控制）。
• 如何在代码中引入和使用安装的包（require）。
• 如何管理依赖：查看（npm list）、更新（npm update）、卸载（npm uninstall）。
• 如何使用 npm run 执行在 package.json 中定义的脚本。
• 如何查找npm包（推荐使用npmjs.com）。

掌握这些基础知识，你就能有效地在Node.js项目中利用npm来管理依赖、复用代码、规范项目流程，从而更高效地进行开发。随着你经验的增长，还可以探索npm更高级的功能，如发布自己的包、使用私有注册表、管理npm配置、使用npx运行包命令等。

---