ai-notebook

npx 完全指南

npx 是 npm 自带的命令运行器,用来执行「包暴露的可执行命令(bin)」。它屏蔽了「这个命令在本地、还是要去远程临时下载」的差异:本地依赖里有就直接跑,没有就临时下载、执行、留缓存,既不写进项目依赖也不污染全局。本指南从定位出发,逐层深入到解析流程、版本与缓存机制、安全模型,最后落到日常用法。

1. 快速认知

1.1 它解决了什么

在 npx 出现之前(npm 5.2 之前),执行包的命令有两条别扭的路:

npx 把这两件事统一成一句 npx foo。它的本质是:把「让命令出现在 PATH 里」这件事,从「提前永久配置」(全局软链接 / 写 scripts)改成「执行那一刻动态拼装 PATH」。 本地有就用本地的,没有就临时下,你不用提前决定。

说明:npx 在新版 npm 中构建于 npm exec 之上,行为基本一致。唯一可感知的差异是:经 npx 调用时,所有选项(flags)必须写在位置参数之前,否则会被当成要执行的命令的参数。

2. 底层基础:bin 字段

npx 能跑 foo,前提是某个包在 package.json 的 bin 字段里声明了「命令名 → 可执行文件」的映射。安装时,包管理器据此在 node_modules/.bin/ 下建符号链接(symlink);Windows 上则「创建一个 .cmd 命令文件来执行 bin 指向的脚本」。所谓「执行一个包的命令」,就是找到并运行这个 bin 文件。

2.1 两种写法

// 对象写法:key 是命令名,可暴露多个命令
{
  "name": "typescript",
  "bin": {
    "tsc": "./bin/tsc",
    "tsserver": "./bin/tsserver"
  }
}

// 字符串写法:命令名 = 包名
{
  "name": "cowsay",
  "bin": "./cli.js" // 等价于 { "cowsay": "./cli.js" }
}
写法 命令名来源 能否多命令
对象 对象的 key ✅
字符串 包名(scoped 包取去掉 scope 的部分) ❌ 仅一个

注意:作用域包 @scope/foo 用字符串写法时,命令名取 name 去掉 scope 的部分,即 foo,而非 @scope/foo。

2.2 bin 文件必须带 shebang

官方要求 bin 引用的文件以 shebang 开头,否则脚本会脱离 node 运行:

#!/usr/bin/env node
// 你的 CLI 入口代码

3. 解析流程

执行 npx foo 时,npx 按下面的顺序寻找 foo 这个 bin,并据此动态拼装执行环境的 PATH:

npx foo
 ├─ 1. 当前目录 node_modules/.bin/        ← 本地优先
 ├─ 2. 逐级向上的父目录 .bin/             ← monorepo 友好
 ├─ 3. 当前 shell 的 PATH                 ← 全局安装命中这里
 ├─ 4. 都没有 → 远程下载到 npm 缓存,把缓存目录临时加进 PATH
 └─ 5. 用拼好的 PATH 找到 bin → 执行 → 退出

「本地优先」是关键,它直接决定了团队协作的正确姿势(见 7.1)。对比一下与全局安装的差异:

维度 全局安装 npx
bin 怎么被找到 永久软链接 + 固定 PATH 运行时临时拼 PATH
生命周期 长期占用 用完即走(只留缓存)
多版本共存 难(软链接全局唯一) 天然支持(可指定版本)

提示:官方在 npm v10 已移除 --ignore-existing 选项——本地安装的 bin 始终存在于执行环境的 PATH 中,无法绕过。

4. 版本解析与缓存机制

这是 npx 最容易让人困惑的部分:为什么有时拿不到最新的 bin?很多人以为「pin 版本才吃缓存,@latest 一定最新」,这是错的——即便写了 @latest,也可能拿到旧版本。要讲清楚,得先拆开「版本解析」和「环境构建」两步,再看缓存在每一步怎么介入。

4.1 第一步:包说明符决定要不要重新解析

npx 命令后的 foo@x 在官方文档里叫包说明符(package specifier)。它确不确定,决定了要不要解析版本:

写法 包说明符是否确定 是否需要解析版本
npx foo@1.2.0 确定(具体版本) 不需要,说明符本身就是答案
npx foo@latest 不确定(dist-tag) 需要:把 latest 解析成具体版本
npx foo(裸名) 不确定(= @latest) 同上

关键点:latest 只是一个 dist-tag(指向某个版本的标签),要知道它当前指向哪个版本号,必须读包的元数据文档(npm 工具链中称 packument,由 registry 返回的版本清单)——这本身就是一次「请求」。而这次请求会不会真的走网络,取决于元数据的缓存新鲜度,这正是下一节的隐式缓存。

4.2 三个缓存参与者

_cacache 里其实存了两类东西,加上 npx 专用的 _npx,一次 npx foo 涉及三个缓存:

缓存 位置 存什么 影响哪一步
元数据缓存 ~/.npm/_cacache packument(版本清单) latest 解析成哪个版本
tarball 缓存 ~/.npm/_cacache 包的压缩包字节 要不要从网络下字节
执行环境缓存 ~/.npm/_npx 组装好的临时执行环境 要不要重新组装环境

官方把 _cacache 描述为「存放所有 HTTP 请求数据」(元数据 + tarball 都在内),按标准 HTTP 缓存规则管理;_npx 则是 npx 专用,每条调用建一个临时「小项目」(含 node_modules + .bin),按包说明符(spec)做 hash 分目录。

说明:~/.npm/_npx 属实现细节,可能随 npm 版本变化,依赖它写脚本(如下文 rm -rf ~/.npm/_npx)需留意稳健性。

4.3 latest 的隐式缓存:为什么 @latest 也可能拿到旧版本

这是最反直觉、也最容易被忽略的一层。@latest 确实「每次都要解析」,但解析时读的 packument 自己就在 _cacache 里有缓存。npm 用官方所谓的新鲜度检查(staleness check)来决定要不要回 registry 核对:数据分新鲜(fresh)和陈旧(stale)两态,默认策略是:

数据只要还「新鲜」,就直接用缓存里的版本号,不向 registry 查更新。 采用 --prefer-online 时会强制做新鲜度检查,即便数据仍新鲜(fresh)也立即查更新。

于是会出现这种情况:

14:00  你跑过一次 npx foo  → 缓存了 foo 的 packument(此刻 latest = 1.0.0)
14:05  作者发布了 foo@2.0.0
14:06  你又跑 npx foo       → packument 还在新鲜期 → 直接用缓存 → latest 仍解析成 1.0.0 ❌

所以「@latest 拿不到最新」不是矛盾,而是版本解析这一步命中了元数据的隐式缓存。三种缓存状态对应三种结果:

元数据缓存状态 npx foo 解析 latest 的行为
新鲜(未过期) 直接用缓存版本号,可能落后于 registry
过期 / 不存在 发条件请求重验证 → 拿到真正的最新
加 --prefer-online 强制重验证,无视新鲜期 → 拿到真正的最新

4.4 第二步:执行环境缓存(pin 版本为何「卡」在旧 bin)

版本解析出具体版本号后,npx 再看 _npx/<hash> 有没有现成环境:

把两步连起来,npx foo 要拿到「真正的最新 bin」,得连续通过两次缓存检查:

npx foo
 ├─ ① 元数据新鲜度检查:packument 新鲜 → 用缓存版本(可能旧);陈旧或 --prefer-online → 回 registry 重解析
 └─ ② 执行环境缓存:该版本的 _npx 环境已存在 → 复用;否则重建(tarball 命中则不重下字节)

注意:pin 死版本复用环境缓存不是 bug,是特性——它保证「同样的 spec,任何机器、任何时间跑的都是同一个 bin」,这是可复现的基础。唯一的坑是语义错配:你 pin 了版本,却期待它自动更新。

确定性 ↔ 新鲜度是一对取舍,版本说明符与 --prefer-online 就是你表达取舍的旋钮:

场景 你要的 写法
CI / 可复现 / 团队一致 确定性 pin 版本,拥抱缓存复用
脚手架(create-*) 永远最新 @latest(必要时配 --prefer-online)
验证刚发布的新版 拿到最新 npx --prefer-online foo@latest

4.5 怀疑跑了旧 bin 时的排查(由轻到重)

对照前面两次缓存检查,由轻到重逐级强制刷新:

# 1. 先比对版本
npx foo --version

# 2. 元数据新鲜度检查:强制重验证 packument,拿到真正的 latest
npx --prefer-online foo@latest

# 3. 执行环境缓存:只删 _npx,强制重组环境(不重下字节)
rm -rf ~/.npm/_npx

# 4. 兜底:连 _cacache 一起清,下次全从网络来
npm cache clean --force

提示:第 3 步删 _npx 留 _cacache 后,下次会重新组装环境(重新解包、建软链接),但 tarball 仍从 _cacache 本地取,不会从网络重下字节。这是个廉价、安全的「刷新」手段。

5. 多 bin 消歧与多包环境

5.1 npx 怎么决定跑哪个命令

情况 npx 的决策
包内只有一个 bin(或都是同一命令的别名) 直接跑它(哪怕命令名和包名不同)
包内多个 bin,有一个匹配包名 跑匹配包名(非 scope 部分)的那个
包内多个 bin,无一匹配 需用 npx -p 包名 <command> 显式点名要跑哪个

这也解释了 npx 包名 简写为什么常常能用:很多包只暴露一个 bin。

5.2 用 -p 指定包、用 -c 跑命令串

npx -p A -p B <command> 表示「把 A、B 都装进同一个临时环境,再在里面执行 <command>」。<command> 能同时看到 A、B 提供的 bin。

# 包名 ≠ 命令名:指定包 typescript,跑其中的 tsc
npx -p typescript tsc --init

# 多包同环境:命令本体与运行时依赖分属不同包
npx -p @angular/cli -p typescript ng build

# -c:在「已把指定包加进 PATH」的环境里执行整串命令
npx -p node@18 -c "node -v && npm -v"

这正好印证了第 1 章的本质:npx 干的就是「临时拼一个把指定包纳入的环境,在里面执行命令」。-p 多包只是往临时环境里多塞几个包。

6. 安全机制与风险

6.1 默认交互确认

当 npx foo 需要从远程下载一个本地没有的包时,npx 默认会停下来确认:

Need to install the following packages:
  foo@1.0.0
Ok to proceed? (y)

它防的是「手滑 / 打错包名就静默联网下载并执行任意代码」。

标志 作用
-y / --yes 自动同意(CI 常用)
--no 强制拒绝下载

6.2 经典风险:typosquatting

攻击者注册一个和热门包拼写相近的恶意包(例如仿 cross-env 的 crossenv)。你 npx cross-env 手滑打成 npx crossenv,npx 找不到本地的 → 直接下这个恶意包 → 执行它的 bin = 在你机器上跑任意代码。

6.3 npx 是 install 的「风险超集」

一个常见误区是「npm install 只下载不执行,所以比 npx 安全」。这不准确——npm install 会执行依赖的安装期生命周期脚本(preinstall → install → postinstall),这正是 npm 供应链攻击最经典的落地点。

风险面 npm i 拼错包 npx 拼错包
安装期钩子(postinstall 等) ✅ 会跑 ✅ 会跑(下载时走一遍安装流程)
bin 本体 ❌ 不跑 ✅ 必跑(npx 的目的)
落地范围 写进项目,可被 lockfile 追踪 临时环境,跑完即走,更隐蔽

所以准确的结论是:npx = 安装期钩子 + bin 执行,是 install 的风险超集。

注意:--ignore-scripts 能禁掉生命周期钩子(npm 和 npx 都支持),但挡不住 npx 的 bin 执行——跑 bin 是你主动要的。对 npx 最有效的防线是:确认包名 + 显式版本 + 不在不信任的包上手滑。

7. 常见用法

类型 例子 命中
跑本地 CLI npx eslint . 本地 .bin,不联网
一次性脚手架 npx create-vite@latest app 远程临时,带 @latest
临时试用工具 npx http-server 远程临时,不污染全局
锁版本跑工具 npx -y tsc@5.4.0 --init 远程临时 + 确定性

7.1 用 npx 保证团队工具版本一致

在已把 eslint 装进 devDependencies 的项目里:

# ✅ 保证跑的是项目锁定的版本
npx eslint .

# ❌ 跑的可能是别人机器上全局装的另一个版本
eslint .

因此团队统一工具版本的正解是三件套:工具进 devDependencies(锁版本)+ lockfile(锁依赖树)+ 统一用 npx 或 npm scripts 调用(保证走本地那一份)。

8. 常见问题

Q1:npx foo 和 ./node_modules/.bin/foo 有什么区别?

项目内已安装时二者效果一致,npx 更省事且会逐级向上查找父目录的 .bin(monorepo 友好);区别在于本地没有时,npx 会临时去远程下载,而直接敲路径会直接报「文件不存在」。

Q2:为什么 npx create-vite 有时跑的还是旧版本?

即便是 @latest 也可能旧——解析 latest 读的 packument 在 _cacache 里有新鲜期,默认对新鲜数据不查更新(见 4.3 的隐式缓存)。想确保最新就加 --prefer-online 强制重验证:npx --prefer-online create-vite@latest。

Q3:npx -p typescript 不带命令为什么报错?

typescript 包暴露了多个 bin(tsc、tsserver),且无一与包名相同,npx 无法替你猜。需要写成 npx -p typescript tsc。

Q4:怎么在完全离线的环境用 npx?

加 --offline(只用缓存,缺则失败)或 --prefer-offline(优先用缓存,缺才联网)。前提是目标包此前已进过 _cacache。

9. 总结

npx 的核心是一句话:把「让命令出现在 PATH 里」从提前永久配置,改成执行那一刻动态拼装。 围绕这一点,关键机制速查如下:

主题 要点
解析顺序 本地 .bin → 父目录 .bin → PATH → 远程下载;本地优先
bin 字段 对象写法 key 即命令名;字符串写法命令名 = 包名(scoped 去前缀)
版本解析 两次缓存检查:元数据新鲜度检查定 latest 解析到哪版,执行环境缓存定是否重组
隐式缓存 @latest 也可能旧:packument 新鲜时默认不查更新,--prefer-online 强制重验证
三个缓存 _cacache 存 packument + tarball;_npx 存组装好的执行环境
刷新手段 @latest → --prefer-online → 删 _npx → cache clean --force
多 bin 单 bin 直跑;多 bin 无匹配用 -p 包 命令 点名
安全 默认交互确认;typosquatting;npx = install 风险超集(钩子 + bin)
团队一致 工具进 devDependencies + lockfile + 统一 npx 调用

10. 参考资源