npm

npm（Node Package Manager）是 Node 的默认包管理器，安装 Node.js 时自动附带。提供包的安装、更新、发布和脚本运行等功能，是全球最大的开源包仓库（registry.npmjs.org）。

同类工具：yarn（更快的锁文件）、pnpm（硬链接节省磁盘）。

初始化项目

npm init              # 交互式创建 package.json
npm init -y           # 全部默认值，快速生成

生成的 package.json 核心字段：

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "项目描述",
  "main": "index.js",          // CJS 入口
  "module": "dist/index.mjs",  // ESM 入口（打包工具识别）
  "type": "module",            // 文件默认为 ESM（省略则为 CJS）
  "scripts": {
    "dev": "node --watch src/index.js",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "jest"
  },
  "dependencies": {},
  "devDependencies": {},
  "engines": { "node": ">=18.0.0" }
}

安装包

# 安装生产依赖（写入 dependencies）
npm install express
npm install express@4.18.2      # 指定版本
npm i express                   # 缩写
 
# 安装开发依赖（写入 devDependencies）
npm install --save-dev typescript jest
npm i -D typescript jest        # 缩写
 
# 安装全局命令行工具
npm install -g typescript
npm install -g nodemon
 
# 安装 package.json 中的所有依赖（CI 场景）
npm install
npm ci                          # 严格按 package-lock.json，不更新锁文件
 
# 安装可选依赖（写入 optionalDependencies，安装失败不报错）
npm install --save-optional fsevents

卸载与更新

# 卸载
npm uninstall express
npm uninstall -g nodemon        # 卸载全局包
 
# 查看可更新版本
npm outdated
 
# 更新到语义版本范围内的最新版
npm update
npm update express
 
# 强制升级到最新版（超出 package.json 范围）
npm install express@latest

查看包信息

# 列出已安装的直接依赖
npm list --depth=0
 
# 列出全局安装的包
npm list -g --depth=0
 
# 查看包的详细信息（版本、依赖、发布日期）
npm info express
npm info express version         # 只看最新版本号
npm info express versions        # 查看所有历史版本
 
# 查找包
npm search lodash

npm scripts

package.json 的 scripts 是项目的任务入口，npm 会在执行时自动将 node_modules/.bin 加入 PATH：

{
  "scripts": {
    "dev": "vite",                          // 直接使用本地 vite，无需全局安装
    "build": "tsc && vite build",           // 串行执行
    "lint": "eslint src --ext .ts,.tsx",
    "test": "jest --coverage",
    "test:watch": "jest --watch",
    "format": "prettier --write 'src/**/*.{ts,tsx,css}'",
    "prepare": "husky install",            // 钩子：npm install 后自动执行
    "postbuild": "cp -r public dist/"      // 钩子：build 完成后执行
  }
}

npm run dev
npm run build
npm test            # test 可省略 run
npm start           # start 可省略 run

脚本钩子

钩子	触发时机
`pre<script>`	对应脚本执行前
`post<script>`	对应脚本执行后
`prepare`	`npm install` 完成后
`prepublish`	`npm publish` 前

依赖类型

字段	说明	安装时机
`dependencies`	运行时依赖（Express、Lodash）	`npm install`
`devDependencies`	开发工具（TypeScript、Jest、ESLint）	`npm install`（`--production` 时跳过）
`peerDependencies`	宿主环境须提供的依赖（插件声明宿主版本）	不自动安装，只做版本校验
`optionalDependencies`	可选依赖，失败不影响安装	`npm install`

语义版本（SemVer）

版本格式：主版本.次版本.补丁版本（MAJOR.MINOR.PATCH）

范围符号	含义	示例
`^1.2.3`	主版本锁定，次版本和补丁可升级	允许 `1.x.x`，不允许 `2.0.0`
`~1.2.3`	次版本锁定，只升补丁	允许 `1.2.x`，不允许 `1.3.0`
`1.2.3`	精确版本，锁死	只允许 `1.2.3`
`>=1.2.0 <2.0.0`	范围区间	—
`*`	任意版本（不推荐）	—

package-lock.json 锁定实际安装的精确版本，确保团队和 CI 环境一致。锁文件应提交到 Git。

.npmrc 配置

项目根目录或用户目录（~/.npmrc）的配置文件：

# 镜像源（国内加速）
registry=https://registry.npmmirror.com
 
# 私有包作用域使用私有仓库
@myorg:registry=https://npm.mycompany.com
 
# 保存 exact 版本（不加 ^ 范围符）
save-exact=true
 
# 安装时不生成 package-lock.json（不推荐，CI 使用 npm ci 时必须有锁文件）
# package-lock=false

临时指定源：

npm install --registry https://registry.npmmirror.com

npx — 执行包命令

npx 随 npm 5.2+ 自动附带，无需全局安装即可运行 npm 包的命令行工具。

执行优先级

npx 按以下顺序查找命令：

node_modules/.bin（本地已安装）
系统 PATH（全局已安装）
npm registry（临时下载后执行，用完即弃）

常用场景

# 创建项目脚手架（最常见用法）
npx create-react-app my-app
npx create-next-app@latest my-next-app
npx create-vite my-vite-app --template vue-ts
npx degit user/template-repo my-project   # 克隆模板仓库
 
# 执行本地 node_modules/.bin 中的命令（无需 npm run）
npx tsc --init
npx eslint src/
npx prettier --write .
 
# 一次性运行远程工具，不写入 package.json
npx cowsay "Hello"
npx serve .                   # 快速启动静态文件服务器
npx http-server . -p 3000
 
# 指定版本执行（测试兼容性）
npx node@18 script.js
npx typescript@5.0 tsc --version

常用标志

标志	说明
`--yes` / `-y`	跳过”是否安装”确认提示
`--no-install`	禁止从 registry 下载，仅用本地已有的
`--prefer-offline`	优先使用本地缓存，无缓存再联网
`--package <pkg>`	明确指定要从哪个包中运行命令（命令名与包名不同时）

# 包名和命令名不一致时，用 --package 指定
npx --package @vue/cli vue create my-app
npx --yes create-vite my-app

npx vs npm exec

npm 7+ 引入了 npm exec，是 npx 的官方替代，行为基本相同：

npx eslint src/
npm exec -- eslint src/    # 等价，-- 分隔 npm 自身参数和命令参数

主要区别：npm exec 默认不会自动从 registry 下载缺失的包（更安全），而 npx 默认会。

注意事项

临时下载的包不写入 package.json，不影响项目依赖
不要用 npx 执行来自不可信来源的脚本（下载后立即运行，有安全风险）
在 CI 中建议明确安装依赖再调用 npx，避免每次构建重复下载

发布包

# 登录 npm（需要 npmjs.com 账号）
npm login
 
# 发布（package.json 中 name 须唯一）
npm publish
 
# 发布带标签（避免成为 latest）
npm publish --tag beta
 
# 更新版本号
npm version patch    # 1.0.0 → 1.0.1
npm version minor    # 1.0.0 → 1.1.0
npm version major    # 1.0.0 → 2.0.0
 
# 查看当前登录用户
npm whoami

.npmignore

控制哪些文件不发布到 registry（类似 .gitignore）：

src/
tests/
*.test.ts
.env
tsconfig.json

常见问题

清除缓存

npm cache clean --force

查看全局安装路径

npm root -g        # 全局 node_modules 路径
npm bin -g         # 全局 bin 路径

依赖冲突

# 查看为何安装了某个版本
npm explain lodash
 
# 查看完整依赖树
npm list

npm vs yarn vs pnpm 速度对比

场景	npm	yarn	pnpm
全新安装	较慢	较快	最快
有缓存安装	中等	快	最快
磁盘占用	最高	高	最低（硬链接）
幽灵依赖	存在	存在	严格隔离

知识仓库

探索

npm

npm