如何使用 npm 本地包的可执行文件

本地安装（不带 -g）的 npm 包如果提供命令行工具，可执行文件会链接到 node_modules/.bin/ 目录。 三种调用方式：① npx eslint .（最推荐，自动查找 .bin）；② 在 npm scripts 里直接写命令名（npm 运行时自动把 .bin 加进 PATH）；③ 显式路径 ./node_modules/.bin/eslint .。

三种方式详解

npm install --save-dev eslint   # 本地安装

npx eslint .                    # 方式一：npx 自动定位
./node_modules/.bin/eslint .    # 方式二：显式路径

{
  "scripts": {
    "lint": "eslint .",
    "test": "mocha"
  }
}

方式三最常用——scripts 里的 eslint 会被解析到 .bin/eslint，npm run lint 就能跑。

为什么不全局安装

• 版本可复现：通过 lockfile 固定依赖解析，换机器用匹配的 npm ci 复现安装；
• 避免全局污染：不同项目可以用同一工具的不同版本；
• CI 友好：流水线里 npm ci && npm test 无需额外全局安装步骤。

npx 的高级用法

npx eslint@8 .          # 指定版本运行
npm exec --package=eslint@8 -- eslint .  # 包可下载到缓存执行，-- 后为命令参数

当前 npx 基于 npm exec：未指定版本时可使用匹配的本地包，显式指定版本时本地包必须匹配该版本；缺少匹配包时可能提示安装到缓存。不能把它理解为本地版本永远优先。包名与 bin 命令名也可能不同。

常见问题（FAQ）

Q：怎么查看一个包提供了哪些可执行文件？

看包的 package.json 里的 bin 字段，或直接 ls node_modules/.bin/。一个包可以提供多个命令（如 mocha 提供 mocha 和 _mocha）。

Q：.bin 目录里是什么？

符号链接（Windows 是 .cmd shim），指向包的实际入口脚本。删除 node_modules 后它们随之消失，npm install 时按 bin 字段重建。

Q：monorepo 里 .bin 在哪？

布局取决于包管理器及提升配置，不保证全部统一在根 .bin/。npm workspaces 可用 npm exec -w <工作区> -- <命令> 或 workspace scripts 明确执行上下文。

参考资料

• Node.js 官方文档
• npm CLI 官方文档