如何使用 npm 执行本地安装 npm 包里的二进制文件

笔者在做产品开发时，需要标题提到的这方面的知识储备，因此做了一些调研，把学习笔记以文章的形式输出，以备将来查阅。

什么是 npm 包的二进制文件？

当我们谈论二进制文件时，我们指的是那些可执行的程序文件。

通常，这些文件是以 .exe 或者没有扩展名的形式存在于操作系统中，例如 Unix 系统中的可执行脚本。这些文件能够直接运行，通常包含在某个软件包中，或是该软件包的一部分。

在 npm 环境中，很多包不仅仅提供 JavaScript 库，还包含命令行工具，这些工具往往以二进制文件的形式存在。例如，像 webpack、eslint、typescript 这样的工具，它们本质上都是可以在命令行中直接执行的二进制文件。

本地安装的 npm 包

在 Node.js 项目中，npm 包可以以两种方式安装：全局安装（global installation）和本地安装（local installation）。

• 全局安装：当你使用 npm install -g package-name 命令时，这个包会被安装到你的全局 node_modules 目录中，并且它的二进制文件会被放置到全局 bin 目录中。这意味着你可以在任何地方运行这个命令，无需指定路径。例如，全局安装 typescript 后，可以直接在命令行中输入 tsc 来执行 TypeScript 编译器。

• 本地安装：本地安装是指将 npm 包安装到项目的 node_modules 目录下。当你执行 npm install package-name（不带 -g 参数）时，包会被安装到当前项目的 node_modules 目录中，而对应的二进制文件会被放置到 node_modules/.bin/ 目录中。

npm scripts 和二进制文件

在 npm 项目的 package.json 文件中，你可以定义脚本命令，使用 scripts 字段。你可以在这些脚本中直接调用安装在项目中的 npm 包的二进制文件，而无需指定完整路径。这是因为当你使用 npm run 来执行脚本时，npm 会自动将 node_modules/.bin/ 目录加入到 PATH 环境变量中。

举例说明

假设你在一个项目中安装了 typescript 和 eslint：

npm install typescript eslint

安装完成后，typescript 和 eslint 的二进制文件将分别被放置在 node_modules/.bin/tsc 和 node_modules/.bin/eslint 路径下。

在 package.json 中，你可以定义如下脚本：

{
  "scripts": {
    "lint": "eslint .",
    "build": "tsc"
  }
}

当你执行 npm run lint 时，npm 会查找 eslint 的二进制文件，并执行它。这种机制的强大之处在于，你无需关心 eslint 二进制文件的完整路径，npm 会自动处理。这不仅简化了脚本的书写，也避免了路径硬编码带来的问题，确保了跨平台的一致性。

为什么使用本地安装的 npm 包？

使用本地安装的 npm 包有几个显著的优势：

• 项目隔离：每个项目可以有自己的依赖包和版本，确保不同项目之间的依赖不会冲突。这在开发多个项目时非常重要，因为不同项目可能需要不同版本的同一包。

• 版本一致性：通过本地安装，你可以确保团队中的所有成员使用相同版本的依赖包。这有助于避免由于依赖包版本不一致而导致的问题。

• 环境一致性：在 CI/CD 管道中，通常会使用本地安装的 npm 包来确保构建和测试环境与开发环境一致。

真实世界的案例研究

让我们来看一个更复杂的案例：假设你正在开发一个大型的前端项目，该项目使用 Webpack 进行打包，使用 Babel 进行代码转换，并且还依赖 ESLint 进行代码质量检查。

项目设置

你在项目中安装了以下 npm 包：

npm install webpack webpack-cli babel-loader @babel/core @babel/preset-env eslint

这些包安装完成后，它们的二进制文件将被放置在 node_modules/.bin/ 目录下：

• webpack 和 webpack-cli：用于执行 Webpack 打包的命令。
• babel-loader、@babel/core、@babel/preset-env：用于 Babel 转换。
• eslint：用于执行 ESLint 代码质量检查。

你可以在 package.json 中定义如下脚本：

{
  "scripts": {
    "build": "webpack --mode production",
    "lint": "eslint src/**/*.js",
    "start": "webpack serve --mode development"
  }
}

执行脚本

当你执行 npm run build 时，npm 会自动查找 node_modules/.bin/webpack，并执行 Webpack 的打包命令。这意味着即使你在命令行中没有全局安装 webpack，你仍然可以通过 npm run build 运行 Webpack。

类似地，当你执行 npm run lint 时，npm 会查找 node_modules/.bin/eslint 并执行 ESLint 的代码质量检查。这样做的好处是，即使你没有在全局安装 ESLint，项目中的 ESLint 也可以正常运行。

跨平台的好处

假设你的团队中有开发者使用 Windows，有的使用 macOS 或者 Linux。在不同的操作系统中，路径格式是不一样的。如果你在 package.json 中直接硬编码二进制文件的路径，那么脚本在不同操作系统上运行时可能会出问题。

例如，Windows 系统中的路径是 node_modules\.bin\webpack.cmd，而在 Unix 系统中路径则是 node_modules/.bin/webpack。通过使用 npm scripts，你可以避免这些跨平台问题，因为 npm 会自动根据操作系统设置正确的路径。

自动化与 CI/CD 集成

在 CI/CD 流水线中，通常会自动执行构建、测试和部署任务。使用本地安装的 npm 包，可以确保流水线中使用的工具版本与开发环境一致。

例如，当你在 GitHub Actions 或 Jenkins 中配置 CI 流水线时，可以通过执行 npm install 来安装所有依赖包，然后使用 npm run build 来构建项目。因为依赖包是本地安装的，CI 流水线不会受到开发者本地环境中可能存在的全局包的影响，从而确保构建的一致性和可重复性。

总结

本地安装的 npm 包的二进制文件在 Node.js 项目中起着至关重要的作用。它不仅简化了脚本的书写，也通过项目隔离、版本控制和跨平台支持增强了项目的可维护性和可靠性。在 npm scripts 中，能够直接调用这些本地安装的二进制文件，是 npm 管理器为开发者提供的一个强大功能。

通过实例和案例研究可以看出，本地安装的 npm 包不仅使得项目更加灵活和可控，还确保了团队协作中的一致性，尤其是在自动化和持续集成场景下。本地安装的方式显著减少了因全局依赖冲突导致的问题，并且在不同的操作系统环境中都能够无缝运行。