npx 是 npm 自带的命令运行器,用来执行「包暴露的可执行命令(bin)」。它屏蔽了「这个命令在本地、还是要去远程临时下载」的差异:本地依赖里有就直接跑,没有就临时下载、执行、留缓存,既不写进项目依赖也不污染全局。本指南从定位出发,逐层深入到解析流程、版本与缓存机制、安全模型,最后落到日常用法。
在 npx 出现之前(npm 5.2 之前),执行包的命令有两条别扭的路:
PATH 里没有项目的 node_modules/.bin,所以要么把命令写进 package.json 的 scripts(靠 npm run 临时把 .bin 加进 PATH),要么手敲 ./node_modules/.bin/foo 这种长路径。npm install -g foo 全局安装,用完污染全局、版本还容易过期。npx 把这两件事统一成一句 npx foo。它的本质是:把「让命令出现在 PATH 里」这件事,从「提前永久配置」(全局软链接 / 写 scripts)改成「执行那一刻动态拼装 PATH」。 本地有就用本地的,没有就临时下,你不用提前决定。
说明:
npx在新版 npm 中构建于npm exec之上,行为基本一致。唯一可感知的差异是:经npx调用时,所有选项(flags)必须写在位置参数之前,否则会被当成要执行的命令的参数。
npx 能跑 foo,前提是某个包在 package.json 的 bin 字段里声明了「命令名 → 可执行文件」的映射。安装时,包管理器据此在 node_modules/.bin/ 下建符号链接(symlink);Windows 上则「创建一个 .cmd 命令文件来执行 bin 指向的脚本」。所谓「执行一个包的命令」,就是找到并运行这个 bin 文件。
// 对象写法: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。
官方要求 bin 引用的文件以 shebang 开头,否则脚本会脱离 node 运行:
#!/usr/bin/env node
// 你的 CLI 入口代码
执行 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 中,无法绕过。
这是 npx 最容易让人困惑的部分:为什么有时拿不到最新的 bin?很多人以为「pin 版本才吃缓存,@latest 一定最新」,这是错的——即便写了 @latest,也可能拿到旧版本。要讲清楚,得先拆开「版本解析」和「环境构建」两步,再看缓存在每一步怎么介入。
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 返回的版本清单)——这本身就是一次「请求」。而这次请求会不会真的走网络,取决于元数据的缓存新鲜度,这正是下一节的隐式缓存。
_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)需留意稳健性。
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 |
强制重验证,无视新鲜期 → 拿到真正的最新 |
版本解析出具体版本号后,npx 再看 _npx/<hash> 有没有现成环境:
npx foo@1.2.0:包说明符完全确定,跳过解析 → _npx/<hash> 直接命中 → 复用旧环境,根本不回源。npx foo:先经 4.3 的元数据新鲜度检查解析出版本,再查执行环境缓存。把两步连起来,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 |
对照前面两次缓存检查,由轻到重逐级强制刷新:
# 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本地取,不会从网络重下字节。这是个廉价、安全的「刷新」手段。
| 情况 | npx 的决策 |
|---|---|
| 包内只有一个 bin(或都是同一命令的别名) | 直接跑它(哪怕命令名和包名不同) |
| 包内多个 bin,有一个匹配包名 | 跑匹配包名(非 scope 部分)的那个 |
| 包内多个 bin,无一匹配 | 需用 npx -p 包名 <command> 显式点名要跑哪个 |
这也解释了 npx 包名 简写为什么常常能用:很多包只暴露一个 bin。
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多包只是往临时环境里多塞几个包。
当 npx foo 需要从远程下载一个本地没有的包时,npx 默认会停下来确认:
Need to install the following packages:
foo@1.0.0
Ok to proceed? (y)
它防的是「手滑 / 打错包名就静默联网下载并执行任意代码」。
| 标志 | 作用 |
|---|---|
-y / --yes |
自动同意(CI 常用) |
--no |
强制拒绝下载 |
攻击者注册一个和热门包拼写相近的恶意包(例如仿 cross-env 的 crossenv)。你 npx cross-env 手滑打成 npx crossenv,npx 找不到本地的 → 直接下这个恶意包 → 执行它的 bin = 在你机器上跑任意代码。
一个常见误区是「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 最有效的防线是:确认包名 + 显式版本 + 不在不信任的包上手滑。
| 类型 | 例子 | 命中 |
|---|---|---|
| 跑本地 CLI | npx eslint . |
本地 .bin,不联网 |
| 一次性脚手架 | npx create-vite@latest app |
远程临时,带 @latest |
| 临时试用工具 | npx http-server |
远程临时,不污染全局 |
| 锁版本跑工具 | npx -y tsc@5.4.0 --init |
远程临时 + 确定性 |
在已把 eslint 装进 devDependencies 的项目里:
npx eslint → 走解析流程,命中项目本地那一份。eslint → 普通 shell 的 PATH 里没有本地 .bin,只能命中全局安装的版本(可能与团队不一致)。# ✅ 保证跑的是项目锁定的版本
npx eslint .
# ❌ 跑的可能是别人机器上全局装的另一个版本
eslint .
因此团队统一工具版本的正解是三件套:工具进 devDependencies(锁版本)+ lockfile(锁依赖树)+ 统一用 npx 或 npm scripts 调用(保证走本地那一份)。
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。
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 调用 |