npx 命令快速入门

npm 5.2+ 内置的包执行器，无需全局安装即可运行 npm 包中的命令。

核心概念

npx <package>        # 下载并执行，执行完丢弃（不安装到本地）
npx <package>@1.2.3  # 指定版本执行
npm install -g xxx   # 全局安装（传统方式，npx 的替代）

npx 的本质：

1. 先找本地 node_modules/.bin/
2. 再找全局安装
3. 都没有 → 从 npm registry 临时下载最新版执行，执行完删除

npx -y @xxx/yyy 逐步拆解

npx -y @xxx/yyy
  │
  ├── 1. -y / --yes：跳过所有交互确认提示，适合 CI 和自动化
  ├── 2. @xxx/yyy：npm scoped 包名，@组织/包名，加命名空间避免重名
  ├── 3. 查本地 node_modules/.bin/ → 查全局 → 都没有
  ├── 4. 请求 npm registry 获取最新版本信息并下载
  │       GET https://registry.npmjs.org/@xxx/yyy
  ├── 5. 读包的 package.json 里 "bin" 字段，定位可执行入口
  │       {"bin": {"my-tool": "bin/cli.js"}}
  ├── 6. 用 node 执行该入口文件
  └── 7. 执行完毕，临时包丢弃（不留在 node_modules）

如何查看一个包的元数据（版本、bin 入口等）：

# 直接请求 registry，返回完整包信息 JSON
curl https://registry.npmjs.org/@aitoearn/openclaw-plugin-cli
 
# 只看最新版 bin 入口
curl -s https://registry.npmjs.org/@aitoearn/openclaw-plugin-cli | \
  python3 -c "import json,sys; d=json.load(sys.stdin); \
  latest=d['dist-tags']['latest']; \
  print('latest:', latest); \
  print('bin:', d['versions'][latest].get('bin',{}))"

返回的 bin 字段就是 npx 运行时执行的入口。如果包没有 bin 字段，npx 会报错无法运行。

常用场景

1. 一次性工具，不想全局安装

npx create-react-app my-app
npx create-next-app@latest my-app
npx degit user/repo my-project

2. 指定版本执行（不影响全局）

npx node@18 --version
npx typescript@4.9 tsc --version

3. 本地 package.json 脚本里调用本地安装的工具

# package.json 里 scripts 中可以直接用包名，不需要 npx
# 但在终端手动运行时需要 npx
npx eslint src/
npx prettier --write .

4. 运行 GitHub 上的包（不发布到 npm）

npx github:user/repo

5. 强制重新下载（跳过缓存）

npx --yes some-package          # 自动确认安装提示
npx --ignore-existing package   # 忽略本地已有版本，强制用远程

常用选项

选项	说明
--yes / -y	自动确认所有提示（CI 环境常用）
--no-install	只用本地或全局的，没有则报错（不下载）
--package <pkg>	指定包名（当命令名和包名不同时）
--call <cmd>	执行任意 shell 命令，在包的环境中运行
@latest	始终使用最新版

几个容易混淆的点

npx vs npm exec（npm 7+）

npm exec 是 npx 的官方替代，行为基本一致：

npx some-tool          # 等价于
npm exec some-tool

-- 分隔符

向被执行的命令传参数时，用 -- 区分 npx 自身的参数：

npx cowsay -- --help   # --help 传给 cowsay，不是 npx

缓存位置

npx 下载的临时包放在 npm 缓存目录，可用 npm cache clean --force 清除。

在 AI Agent Skill 里的典型用法

# 安装/管理 Agent Skill
npx skills add user/repo-name
npx skills list
npx skills update
 
# 一次性运行工具
npx @anthropic-ai/sdk

查看 npx 版本

npx --version
npm --version   # npx 随 npm 一起安装