zhaoweiguo 的知识库

npm

5分钟阅读

Node Package Manager，Node.js 自带的包管理工具，全球最大的 JavaScript 软件包生态系统之一。

定位

npm 既是 registry 客户端，也是项目依赖安装器、脚本执行入口和发布工具。日常开发里最常用的 4 类能力：

  • 安装与卸载依赖
  • 维护 package.json / package-lock.json
  • 执行 scripts
  • 发布包到 npm registry

安装

npm 随 Node.js 一起安装。升级 npm：

npm install -g npm

项目里通常会同时看到两个核心文件：

  • package.json：声明你“期望依赖什么”
  • package-lock.json：锁定一次实际解析出来的完整依赖树，保证团队和 CI 安装结果尽量一致

常见命令分工：

npm install   # 按 package.json + package-lock.json 安装，并可能更新 lock
npm ci        # 严格按现有 package-lock.json 安装，常用于 CI

如果仓库已经提交了 package-lock.json，团队协作时一般应保留并一起提交。

常用命令

初始化

npm -v
npm init

安装包

npm install
npm install <package>
npm install <package>@<version>
npm install -D <package>
npm install -g <package>

npm install <package> 默认写入 dependencies。常见保存 flags：

npm install <package>              # 默认写入 dependencies
npm install -D <package>          # 写入 devDependencies
npm install -P <package>          # 显式写入 dependencies
npm install -O <package>          # 写入 optionalDependencies
npm install --save-peer <package> # 写入 peerDependencies
npm install --no-save <package>   # 安装但不写 package.json
npm install -E <package>          # 精确锁定版本号，不写 ^/~ 范围

其中 npm install -D <package> 等价于 npm install --save-dev <package>，作用是：

  • 安装指定包到当前项目
  • 将该包写入 package.json 的 devDependencies
  • 同步更新 package-lock.json

典型场景：

  • 构建工具：vite、webpack
  • 代码检查：eslint、oxlint
  • 测试工具：vitest、jest
  • 类型工具：typescript、@types/node

说明：

  • --save / -S 在现代 npm 里基本不需要显式写，默认就是保存到 dependencies
  • -D 是最常见的“开发依赖”快捷写法

依赖字段

字段什么时候放这里
dependencies应用在生产环境运行时必须加载
devDependencies只在开发、测试、构建、类型检查阶段需要
peerDependencies当前包期望宿主项目自己提供，常见于插件、组件库
optionalDependencies可选增强项，安装失败不应阻断主流程

实用判断标准：

  • “线上启动后会 require/import 到吗？”会，就优先放 dependencies
  • “只在本地开发、CI、构建时用到吗？”是，就放 devDependencies
  • “这是给别人安装的库，而且要和宿主共用同一份 React/Vue 吗？”是，就考虑 peerDependencies

不适合放到 -D 的，通常是生产运行时必须存在的包，比如：

  • Web / SSR 运行时依赖：react、next
  • 服务端依赖：express、koa
  • 业务运行时 SDK：axios、zod

查看包

npm list          # 查看已安装的包
npm list -g       # 查看全局安装的包
npm show <package> # 显示模块详情
npm outdated       # 查看可升级依赖

卸载与更新

npm uninstall <package>
npm uninstall -g <package>
npm update <package>

运行脚本与工具

npm audit          # 检查安全漏洞
npm run <script>   # 执行 scripts
npm exec <cmd>     # 运行本地依赖里的可执行文件

发布包

npm login
npm publish
npm unpublish <package>@<version>

缓存

npm cache clean --force
npm cache verify

工具边界

场景推荐
通用 Node.js 项目npm
追求速度 / 磁盘节省pnpm
需要兼容旧项目 / 既有团队习惯yarn
全栈工具链一体化bun

踩坑点

  • npm install 默认会把新包写进 dependencies，不是“只下载不保存”
  • 全局安装路径与 nvm 版本切换冲突，切版本后全局包需重装
  • --save 在 npm 5+ 已是默认行为，无需显式加
  • 把运行时依赖误装成 -D，常见结果是线上启动时报 module not found
  • 库项目里把宿主依赖写进 dependencies 而不是 peerDependencies，容易导致 React/Vue 多实例问题

相关

关系图谱

反向链接