npx 使用入门教程：是什么、怎么用、和 npm 有什么区别

适合刚接触 Node.js 工具链的同学阅读。看完这篇文章，你会知道 npx 是什么、什么时候该用它，以及它和 npm 的职责到底有什么不同。

1. 教程简介

1.1 这篇教程讲什么

本教程带你从 0 开始认识 npx，并通过几个常见场景学会它的基本用法。你会看到：为什么很多前端项目初始化命令前面都是 npx，为什么它能直接执行一些你没有全局安装过的工具，以及它在日常开发中能帮你省掉哪些麻烦。

如果你以前只用过 npm install，但看到 npx create-vite@latest、npx prettier --write . 这类命令总觉得有点懵，这篇文章就是给你准备的。

1.2 学完后你会得到什么

能理解 npx 的核心作用
能区分 npx 和 npm 的使用场景
能用 npx 执行常见命令行工具
能知道常见报错该怎么排查

2. 前置知识

建议提前具备以下知识：

知道什么是 Node.js
知道什么是 npm
会打开终端并执行命令
知道"安装依赖"和"执行命令"是两件不同的事

如果没有也没关系，可以先记住一句最核心的话：

npm 更像"安装包的工具"，npx 更像"执行包里命令的工具"。

3. 环境准备

3.1 软件环境

操作系统：Windows / macOS / Linux 都可以
运行环境：建议 Node.js 18+
包管理工具：npm（通常会随 Node.js 一起安装）
编辑器：VS Code / TRAE / WebStorm / 其他都行

3.2 需要安装的依赖

npx 通常会随 npm 一起提供，所以大多数情况下你只需要安装 Node.js 即可。

bash 复制代码

node -v
npm -v
npx -v

如果这 3 个命令都能输出版本号，说明环境已经具备。

3.3 需要准备的账号 / Key / 权限

平台账号：不需要
API Key：不需要
网络环境要求：第一次执行某些 npx 命令时需要联网下载包
终端权限：普通终端通常即可，个别 Windows 环境可能需要注意脚本执行策略

4. 先讲清楚核心概念

先把概念弄清楚。

4.1 什么是 `npx`

npx 是一个用来执行 npm 包中命令行工具的命令。

它最常见的用途是：

执行你本地项目里已经安装的 CLI 工具
临时执行一个你还没有安装到全局的工具
指定某个包的版本来执行命令

你可以把它简单理解成：

"我不一定要先全局安装这个工具，我先直接跑一下再说。"

4.2 `npm` 和 `npx` 的区别

很多新人最容易把这两个混在一起。

npm 更偏向"安装和管理包"，例如：

bash 复制代码

npm install axios
npm install -D prettier

这类命令是在把依赖装进项目里。

npx 更偏向"执行命令"，例如：

bash 复制代码

npx prettier --write .
npx create-vite@latest

这类命令是在直接运行某个工具。

4.3 它们之间的关系

可以这样理解：

npm 负责下载和管理包
npx 负责运行包里的命令
二者经常配合使用，但职责不同

比如你在项目里安装了 prettier：

bash 复制代码

npm install -D prettier

然后你再执行：

bash 复制代码

npx prettier --write .

前者是"装工具"，后者是"用工具"。

4.4 补一张流程图

如果你觉得抽象，可以把 npx 的执行过程理解成下面这个流程：
#mermaid-svg-IaNn246dO5FsUjtR{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-IaNn246dO5FsUjtR .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-IaNn246dO5FsUjtR .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-IaNn246dO5FsUjtR .error-icon{fill:#552222;}#mermaid-svg-IaNn246dO5FsUjtR .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-IaNn246dO5FsUjtR .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-IaNn246dO5FsUjtR .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-IaNn246dO5FsUjtR .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-IaNn246dO5FsUjtR .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-IaNn246dO5FsUjtR .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-IaNn246dO5FsUjtR .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-IaNn246dO5FsUjtR .marker{fill:#333333;stroke:#333333;}#mermaid-svg-IaNn246dO5FsUjtR .marker.cross{stroke:#333333;}#mermaid-svg-IaNn246dO5FsUjtR svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-IaNn246dO5FsUjtR p{margin:0;}#mermaid-svg-IaNn246dO5FsUjtR .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-IaNn246dO5FsUjtR .cluster-label text{fill:#333;}#mermaid-svg-IaNn246dO5FsUjtR .cluster-label span{color:#333;}#mermaid-svg-IaNn246dO5FsUjtR .cluster-label span p{background-color:transparent;}#mermaid-svg-IaNn246dO5FsUjtR .label text,#mermaid-svg-IaNn246dO5FsUjtR span{fill:#333;color:#333;}#mermaid-svg-IaNn246dO5FsUjtR .node rect,#mermaid-svg-IaNn246dO5FsUjtR .node circle,#mermaid-svg-IaNn246dO5FsUjtR .node ellipse,#mermaid-svg-IaNn246dO5FsUjtR .node polygon,#mermaid-svg-IaNn246dO5FsUjtR .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-IaNn246dO5FsUjtR .rough-node .label text,#mermaid-svg-IaNn246dO5FsUjtR .node .label text,#mermaid-svg-IaNn246dO5FsUjtR .image-shape .label,#mermaid-svg-IaNn246dO5FsUjtR .icon-shape .label{text-anchor:middle;}#mermaid-svg-IaNn246dO5FsUjtR .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-IaNn246dO5FsUjtR .rough-node .label,#mermaid-svg-IaNn246dO5FsUjtR .node .label,#mermaid-svg-IaNn246dO5FsUjtR .image-shape .label,#mermaid-svg-IaNn246dO5FsUjtR .icon-shape .label{text-align:center;}#mermaid-svg-IaNn246dO5FsUjtR .node.clickable{cursor:pointer;}#mermaid-svg-IaNn246dO5FsUjtR .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-IaNn246dO5FsUjtR .arrowheadPath{fill:#333333;}#mermaid-svg-IaNn246dO5FsUjtR .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-IaNn246dO5FsUjtR .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-IaNn246dO5FsUjtR .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-IaNn246dO5FsUjtR .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-IaNn246dO5FsUjtR .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-IaNn246dO5FsUjtR .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-IaNn246dO5FsUjtR .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-IaNn246dO5FsUjtR .cluster text{fill:#333;}#mermaid-svg-IaNn246dO5FsUjtR .cluster span{color:#333;}#mermaid-svg-IaNn246dO5FsUjtR div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-IaNn246dO5FsUjtR .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-IaNn246dO5FsUjtR rect.text{fill:none;stroke-width:0;}#mermaid-svg-IaNn246dO5FsUjtR .icon-shape,#mermaid-svg-IaNn246dO5FsUjtR .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-IaNn246dO5FsUjtR .icon-shape p,#mermaid-svg-IaNn246dO5FsUjtR .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-IaNn246dO5FsUjtR .icon-shape .label rect,#mermaid-svg-IaNn246dO5FsUjtR .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-IaNn246dO5FsUjtR .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-IaNn246dO5FsUjtR .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-IaNn246dO5FsUjtR :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 有
没有
输入 npx 命令
本地项目里有这个工具吗
直接调用本地依赖
临时下载对应包
执行包里的 CLI
输出运行结果

这个图想说明的核心只有一句话：npx 的重点不是"安装"，而是"把命令跑起来"。

5. 实操步骤

第 1 步：检查环境是否可用

先确认你的机器已经有 Node.js、npm 和 npx。

bash 复制代码

node -v
npm -v
npx -v

预期结果：

text 复制代码

v22.14.0
10.9.2
10.9.2

到这一步为止，你应该能看到 3 个版本号。如果 npx 没有输出版本号，先不要继续，先处理环境问题。

第 2 步：执行一个最简单的临时命令

我们先用一个最容易观察结果的例子感受 npx 的作用。

bash 复制代码

npx cowsay hello

预期结果：

text 复制代码

 _______
< hello >
 -------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\\
                ||----w |
                ||     ||

这一步的重点不是 cowsay 本身，而是你会发现：即使你没有提前全局安装它，npx 也能帮你把命令跑起来。

第 3 步：用 `npx` 创建项目

这是 npx 最经典的使用场景之一。

bash 复制代码

npx create-vite@latest my-app

执行后，脚手架通常会引导你选择：

使用什么框架
用 JavaScript 还是 TypeScript
项目目录叫什么名字

为什么这里适合用 npx？

脚手架通常只在初始化项目时使用
没必要长期全局安装
一般希望直接使用较新的版本

第 4 步：执行项目里的本地工具

很多工具会安装在项目的 node_modules 里，而不是装到全局。

先安装 prettier：

bash 复制代码

npm install -D prettier

再执行：

bash 复制代码

npx prettier --write .

预期结果：当前目录下符合规则的文件会被格式化。

这一步体现的是：npx 会优先使用当前项目里已经安装好的工具版本，这对团队协作很有价值。

第 5 步：指定版本执行命令

有时候你希望执行某个明确版本的工具，可以这样写：

bash 复制代码

npx prettier@3.3.3 --version

这类写法适合：

排查版本问题
对比不同版本的行为
临时验证某个工具在特定版本下是否正常

6. 关键代码讲解

6.1 `npx create-vite@latest my-app`

bash 复制代码

npx create-vite@latest my-app

解释：

npx：负责执行命令
create-vite@latest：执行 create-vite 包的最新版本
my-app：表示新项目目录名

为什么这样写：

不需要手动全局安装脚手架
可以较方便地获取较新的初始化版本
创建完项目后不会长期占用全局环境

6.2 `npx prettier --write .`

bash 复制代码

npx prettier --write .

解释：

prettier：代码格式化工具
--write：直接把格式化结果写回文件
.：表示当前目录

输入是什么：

输出是什么：

被格式化后的文件内容

它在整体流程中的位置是什么：

一般放在开发过程中、提交代码前，或者配合 CI 使用

6.3 `npx <package>@<version>`

bash 复制代码

npx eslint@9.0.0 --version

解释：

<package> 是工具名
@<version> 是指定版本

适合什么场景：

你不想依赖当前默认版本
你想测试某个版本是否兼容
你要复现别人文档中的特定环境

7. 常见问题与报错排查

问题 1：`npx: command not found`

现象：

终端提示找不到 npx。

原因：

Node.js / npm 没装好
环境变量没有配置正确
终端没有刷新

解决方法：

先执行 node -v 和 npm -v 检查环境
重新安装 Node.js
重启终端或重启电脑后再试

问题 2：执行很慢，或者一直卡住

现象：

执行 npx xxx 时等待很久。

原因：

第一次执行时需要拉取相关包
网络环境较慢
目标包本身体积较大

解决方法：

耐心等待第一次下载完成
检查网络环境
必要时切换 npm 镜像源

问题 3：版本和预期不一致

现象：

明明执行了命令，但效果和教程里不一样。

原因：

你执行的是较新版本，教程写的是旧版本
本地项目依赖版本和全局 / 临时版本不同

解决方法：

显式指定版本，例如：

bash 复制代码

npx prettier@3.3.3 --version

检查当前项目是否已经安装了本地依赖

问题 4：命令能执行，但提示权限或脚本受限

现象：

Windows 下可能出现脚本执行限制或权限不足。

原因：

PowerShell 执行策略限制
当前终端权限不足

解决方法：

尝试换一个终端再执行
以管理员身份打开终端
检查 PowerShell 执行策略设置

8. 本节小结

npm 主要负责安装和管理包
npx 主要负责执行包里的命令
npx 很适合脚手架初始化、临时工具执行、本地 CLI 调用
它能帮你减少全局安装，保持开发环境更干净
遇到问题时，先检查 Node.js、npm、网络和版本

9. 课后练习

执行一次 npx cowsay hello，感受临时工具的运行方式。
用 npx create-vite@latest demo-app 创建一个测试项目。
在一个项目里安装 prettier，再用 npx prettier --write . 运行一次。
尝试指定一个版本执行命令，例如 npx prettier@3.3.3 --version。

10. 延伸阅读

官方文档：https://docs.npmjs.com/cli/v10/commands/npx
Node.js 官网：https://nodejs.org/
npm 官方文档：https://docs.npmjs.com/
Vite 官网：https://vite.dev/
Prettier 官网：https://prettier.io/

11. 可直接复用的图文增强区块

11.1 常用的命令行展示模板

如果文章里有命令操作，建议同时写"输入命令"和"预期输出"：

bash 复制代码

# 输入命令
npx cowsay hello

预期输出：

text 复制代码

 _______
< hello >
 -------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\\
                ||----w |
                ||     ||

这样做的好处：

读者知道自己有没有跑对
文档更像真实教程
更方便排查问题

附：什么时候该用 `npx`，什么时候该用 `npm`

更适合用 `npx` 的情况

我只是临时执行一个命令
我要创建一个新项目
我不想全局安装这个工具
我想直接运行本地依赖中的 CLI
我想临时指定某个版本

更适合用 `npm` 的情况

我要把依赖正式装进项目
我要管理 package.json
我要安装项目长期需要的包
我要新增开发依赖或生产依赖

一句话记忆

npm 负责"装"，npx 负责"跑"。

如果你是刚入门，先把这句话记住，后面很多 Node.js 教程都会顺很多。

npx 使用入门教程：是什么、怎么用、和 npm 有什么区别