npm 常用命令速查:按场景一眼查到要用的那条

每天写 Node 项目,真正会反复敲的 npm 命令也就二三十条。但偏偏总有几条记不牢:装开发依赖是 -D 还是 --dev?给脚本传 flag 为什么没生效?发 scope 包第一次为什么报 402?这篇按场景把高频命令理一遍,记不住的直接收藏 npm / yarn / pnpm 命令速查,三个工具的等价写法并排放,搜一个词三栏一起出。

初始化和装包

新项目第一步是 npm init,想跳过所有交互问题就 npm init -y,直接写出一份默认 package.json。注意 pnpm 这里有个坑:pnpm init 根本不交互提问,所以没有 -y 这个 flag,敲了反而报错,直接 pnpm init 就行。

装包是最高频的操作,按依赖类型分清楚:

npm install lodash          # 装运行时依赖,写进 dependencies
npm install -D vite         # 装开发依赖,写进 devDependencies
npm install -g pnpm         # 全局装工具
npm install react@18.2.0    # 装指定版本
npm ci                      # 严格按锁文件装,CI 专用

npm install 和 npm ci 的区别值得专门记:前者每次都做依赖解析,读 package.json、走依赖树、决定版本,如果 package.json 跑得比锁文件快,它会默默改锁文件去对齐。npm ci 完全跳过解析,先清空 node_modules,然后严格按锁文件装,一旦两者对不上就直接报错。所以 CI 环境一律用 npm ci:更快、可复现,而且谁忘了提交锁文件会当场暴露。

跑脚本

npm run <script> 跑 package.json 里 scripts 字段定义的命令,npm start 和 npm test 是两个常用别名。这里有个几乎人人踩过的坑:给脚本传参数得加 -- 分隔符。

npm run build -- --prod     # --prod 传给脚本
npm run build --prod        # 错:--prod 被 npm 自己吃掉了

脚本名后面不加分隔符,参数会被 npm 当成自己的 flag。yarn 和 pnpm 在这点上反而不用 --,这也是三工具混着用最容易翻车的地方。

package.json 你真正要管的几个字段

package.json 是整个项目的说明书,但日常真正会改的就那么几块:dependencies 和 devDependencies 装包时自动维护,scripts 是你手写命令的地方,version 决定发布版本号。不想手动编辑 JSON,可以用 npm pkg 系列命令直接读写:

npm pkg get version                       # 读字段
npm pkg set scripts.dev="vite"            # 写一条脚本

版本和更新

npm outdated                # 列出有新版的包
npm update                  # 在 semver 范围内更新
npm version patch           # 补丁号 +1,并打 git tag
npm version minor           # 次版本号 +1

npm version patch|minor|major 不只是改 package.json 里的版本号,它还会自动生成一个 git commit 和 tag,发布前用它来 bump 版本比手改干净得多。

发布:第一次发 scope 包的坑

发包流程是 npm login → npm publish,发之前可以 npm publish --dry-run 先看会打进哪些文件。最常见的卡点是首次发布 scope 包,比如 @acme/utils,直接 npm publish 会被拒绝并返回 402 Payment Required,因为 scope 包默认私有。解法是加 --access public:

npm publish --access public
npm publish --access public --otp 123456   # 开了 2FA 再补 OTP

公开 scope 包根本不用买付费计划,只是第一次得显式声明公开。

npm vs pnpm vs yarn,新项目选谁

我自己现在新项目一律上 pnpm。理由很实在:默认严格,能抓出 npm 会放过的幻影依赖(代码里 import 了某个包但 package.json 没列),冷启动 install 比 npm 快 2 到 3 倍,磁盘占用少约一半,因为它把包符号链接到一个内容寻址的全局 store,而不是每个项目复制一份。monorepo 场景 pnpm 的 --filter 选择器也更顺手,pnpm --filter "...pkg-a" test 能把依赖某个包的下游也一起带上测。

什么时候留 npm:公司锁机器装不了新全局工具,或者团队对符号链接的 node_modules 不熟、有老工具会卡。yarn 我现在只在已经在用 yarn classic 且迁移不划算的老项目里保留。

全局工具和缓存

npm install -g <pkg>        # 全局装
npm ls -g                   # 看全局装了什么
npm cache clean --force     # 清缓存

全局装包在某些系统会报 EACCES 权限错误,别上来就 sudo,优先用版本管理器(nvm / fnm)把 Node 装到用户目录下,权限问题自然消失。

按场景查命令是最省脑子的方式,完整的 80+ 条对照表和每条背后的坑都收在 npm / yarn / pnpm 命令速查里,搜索跨三栏一起过滤。如果你还在和 Git 较劲,顺手收一份 Git 命令速查一并放手边。

Made by Toolora · Updated 2026-06-13