npm 常用命令

npm（Node Package Manager）是 Node.js 自带的包管理器，也是目前最大的 JavaScript 包生态系统。

安装 & 初始化

bash

# npm 随 Node.js 一起安装，无需单独安装
node -v                    # 查看 Node.js 版本
npm -v                     # 查看 npm 版本

# 初始化项目（交互式问答生成 package.json）
npm init

# 跳过问答，生成默认配置
npm init -y                # -y 表示 yes，所有选项使用默认值

# 使用指定模板初始化（常用于创建 Vue、React 等项目）
npm init vite@latest my-app -- --template vue

依赖管理

四种依赖类型说明

类型	安装命令	说明	大白话解释	使用场景
`dependencies`	`npm install <pkg>`	生产环境依赖	项目运行必须用到的包	vue、react、axios、lodash 等
`devDependencies`	`npm install -D <pkg>`	开发环境依赖	只在开发时用，打包后不需要	vite、eslint、typescript、jest 等
`peerDependencies`	`npm install -P <pkg>`	对等依赖	你的包「期望」使用者自己安装的依赖	组件库期望使用者已安装 vue
`optionalDependencies`	`npm install -O <pkg>`	可选依赖	安装失败不会报错，项目照样能跑	跨平台兼容包、性能优化包

安装依赖

bash

# 安装所有依赖（根据 package-lock.json）
npm install                 # 完整写法
npm i                       # 简写，效果一样

# 安装指定包（添加到 dependencies）
npm install <package>
npm i <package>

# 安装指定包（添加到 devDependencies）
# -D 是 --save-dev 的简写，表示只在开发环境使用
npm install -D <package>
npm i -D <package>

# 安装指定版本
npm i <package>@1.2.3

# 安装最新版本
npm i <package>@latest

# 安装指定范围版本（语义化版本）
npm i <package>@">=1.0.0 <2.0.0"

# 安装 Git 仓库（直接从 GitHub 安装）
npm i git+https://github.com/user/repo.git
npm i github:user/repo

# 安装本地目录（monorepo 或本地开发调试）
npm i ../my-local-package
npm i file:../my-local-package

# 全局安装（-g 是 --global 的简写）
# 全局安装的包可以在任何地方直接使用命令
npm i -g <package>

# 安装并保存到 peerDependencies
# -P 是 --save-peer 的简写
npm i -P <package>

# 安装并保存到 optionalDependencies
# -O 是 --save-optional 的简写
npm i -O <package>

升级 & 卸载

bash

# 升级指定包（遵守 package.json 中的版本范围）
npm update <package>

# 升级到最新版本（忽略版本范围，直接装最新）
npm i <package>@latest

# 交互式升级所有依赖（需先安装 npm-check-updates）
npx npm-check-updates -u    # 更新 package.json 中的版本号
npm install                 # 重新安装

# 卸载指定包
npm uninstall <package>     # 完整写法
npm rm <package>            # 简写
npm r <package>             # 更短的简写

# 全局卸载
npm uninstall -g <package>

# 卸载并从 package.json 中移除
npm uninstall --save <package>          # 从 dependencies 移除
npm uninstall --save-dev <package>      # 从 devDependencies 移除

查看依赖

bash

# 列出已安装的包（树形结构）
npm list                    # 完整写法
npm ls                      # 简写

# 只列出顶层依赖（不显示嵌套的子依赖）
# --depth 控制显示层级，0 表示只显示顶层
npm ls --depth=0

# 列出全局安装的包
npm ls -g

# 查看某个包的详细信息（版本、依赖、仓库、作者等）
npm info <package>
npm view <package>

# 查看指定版本信息
npm info <package>@1.2.3

# 查看包的所有历史版本
npm info <package> versions

# 查看包的依赖关系（这个包依赖了哪些其他包）
npm info <package> dependencies

# 查看为什么安装了某个包（显示依赖链，知道是谁引入的）
npm explain <package>
# npm why <package> 也行（别名）

运行脚本

bash

# 运行 package.json 中定义的脚本
npm run <script-name>

# 可省略 run 的内置脚本（npm 默认识别这几个名称）
npm start                   # 启动项目
npm test                    # 运行测试
npm stop                    # 停止项目
npm restart                 # 重启项目

# 传递参数给脚本（-- 分隔符说明）
# - `--` 是参数分隔符，用于区分 npm 本身的参数和脚本的参数
# - `--` 之后的所有参数都会传递给脚本
# - 脚本通过 process.argv 获取这些参数（Node.js 环境）
npm run build -- --mode production
npm test -- --watch

# 可以传递多个参数
npm run build -- --mode production --verbose

# 常见工具参数示例：

# Vite 构建工具：
npm run dev -- --port 3001        # 指定开发服务器端口
npm run dev -- --host             # 允许外部访问（局域网其他设备可访问）
npm run build -- --mode staging   # 指定构建模式（staging 是预发布环境）
npm run build -- --outDir dist2   # 指定输出目录

# ESLint 代码检查：
npm run lint -- --fix             # 自动修复可修复的问题
npm run lint -- --ext .js,.ts     # 指定检查的文件扩展名（ESLint 9+ 已废弃此参数）
npm run lint -- --no-error-on-unmatched-pattern  # 无匹配文件时不报错

# Vitest 测试框架：
npm test -- --watch               # 监听模式，文件变化时重新测试
npm test -- --coverage            # 生成测试覆盖率报告
npm test -- --reporter verbose    # 使用详细报告器
npm test -- --bail 1              # 第一个测试失败后停止

# TypeScript 编译器：
npm run build -- --noEmit         # 只检查类型，不输出文件（常用于类型检查）
npm run build -- --sourceMap      # 生成 source map（调试时定位源码）
npm run build -- --watch          # 监听模式，文件变化时自动编译

# 查看所有可用脚本
npm run

# 并行执行多个脚本（& 表示并行，两个命令同时执行）
npm run <script1> & npm run <script2>

# 顺序执行多个脚本（&& 表示顺序，前一个成功才执行后一个）
npm run <script1> && npm run <script2>

创建自定义脚本

在 package.json 的 scripts 字段中定义脚本：

json

{
  "scripts": {
    "dev": "vite",                    // 启动开发服务器
    "build": "vite build",            // 构建生产版本
    "preview": "vite preview",        // 预览构建产物
    "lint": "eslint src/",            // 检查代码规范
    "test": "vitest",                 // 运行测试
    "format": "prettier --write src/", // 格式化代码
    "clean": "rimraf dist"            // 清理构建目录
  }
}

脚本命名规范

常用命名：dev（开发）、build（构建）、start（启动）、test（测试）、lint（检查）、format（格式化）
自定义名称：可以使用任意名称，如 deploy、db:migrate、generate
组合脚本：使用 && 顺序执行，& 并行执行

脚本编写技巧

使用已安装的工具：直接调用 node_modules/.bin 中的命令

json

"scripts": {
  "lint": "eslint src/",
  "build": "tsc && vite build"
}

传递参数：使用 -- 分隔符
bash
```
npm run build -- --mode production
```

环境变量：使用 cross-env 跨平台设置

json

"scripts": {
  "dev": "cross-env NODE_ENV=development vite"
}

组合命令：使用 && 顺序执行，|| 失败后执行

json

"scripts": {
  "build": "tsc && vite build",
  "deploy": "npm run build && gh-pages -d dist"
}

使用 npm 配置变量：通过 npm_package_ 前缀访问

json

"scripts": {
  "info": "echo 'Project: $npm_package_name, Version: $npm_package_version'"
}

Vue 项目完整配置示例

json

{
  "name": "my-vue-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "preview": "vite preview",
    "lint": "eslint src/",
    "lint:fix": "eslint --fix src/",
    "format": "prettier --write src/",
    "type-check": "vue-tsc --noEmit",
    "test": "vitest",
    "test:coverage": "vitest run --coverage",
    "clean": "rimraf dist",
    "prepare": "husky"
  },
  "dependencies": {
    "vue": "^3.4.0",
    "vue-router": "^4.3.0",
    "pinia": "^2.1.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "vite": "^5.4.0",
    "vue-tsc": "^2.0.0",
    "typescript": "^5.5.0",
    "eslint": "^9.0.0",
    "prettier": "^3.3.0",
    "vitest": "^2.0.0"
  }
}

生命周期脚本

npm 支持 pre/post 钩子，在脚本执行前后自动触发：

json

{
  "scripts": {
    "prebuild": "echo '构建前...'",    // build 之前自动执行
    "build": "vite build",
    "postbuild": "echo '构建后...'",   // build 之后自动执行
    "pretest": "eslint src/",          // test 之前自动执行（确保代码规范）
    "test": "vitest"
  }
}

bash

# 执行 npm run build 时，实际执行顺序：
# 1. prebuild（构建前准备）
# 2. build（正式构建）
# 3. postbuild（构建后处理，如上传、通知等）

内置生命周期

json

{
  "scripts": {
    "preinstall": "echo '安装前'",           // npm install 之前触发
    "postinstall": "echo '安装后'",          // npm install 之后触发（常用于编译原生模块）
    "prepublish": "echo '发布前'",           // npm publish 之前触发（已废弃，建议用 prepublishOnly）
    "prepublishOnly": "echo '仅发布前'",     // 只在 npm publish 之前触发（推荐）
    "prepare": "echo '准备阶段（install 后、publish 前）'"  // install 后和 publish 前触发
  }
}

依赖检查

bash

# 检查过期的依赖（显示当前版本、期望版本、最新版本）
npm outdated

# 输出示例：
# Package    Current  Wanted  Latest  Location
# vue          3.3.0   3.4.0   3.4.0  my-project
# vite         4.5.0   4.5.1   5.0.0  my-project
# Current：当前安装的版本
# Wanted：符合 package.json 版本范围的最新版本
# Latest：npm 上的最新版本

# 安全漏洞检查
npm audit

# 查看漏洞详情（JSON 格式，便于程序处理）
npm audit --json

# 自动修复安全漏洞（只修复兼容版本，不破坏现有依赖）
npm audit fix

# 强制修复（可能有破坏性变更，慎用）
npm audit fix --force

# 只查看，不修复（预览模式）
npm audit --dry-run

CI/CD 安装

bash

# 根据 package-lock.json 精确安装（CI/CD 推荐）
# ci 是 clean install 的缩写
npm ci

npm ci vs npm install

特性	npm ci	npm install
lock 文件	严格按 lock 安装，不修改	可能更新 lock 文件
node_modules	先删除再安装（干净安装）	增量安装（保留已有）
速度	较快（跳过依赖解析，但会删除 node_modules）	增量安装，已有包不重复下载
package.json	必须与 lock 一致才安装	自动创建/更新 lock
适用场景	CI/CD、自动化部署	本地开发

通俗解释：

npm install：智能安装，会根据 package.json 自动更新 lock 文件，适合本地开发
npm ci：严格安装，完全按照 lock 文件安装，不更新任何文件，适合 CI/CD 环境确保一致性

镜像源配置

为什么需要配置镜像源？

npm 默认从国外服务器下载包，国内访问速度慢。配置国内镜像源可以大幅提升下载速度。

临时使用镜像源

bash

# 临时使用淘宝镜像安装单个包
npm install <package> --registry https://registry.npmmirror.com

# 临时使用指定镜像源运行命令
npm install --registry https://registry.npmmirror.com

永久配置镜像源

bash

# 设置淘宝镜像源（推荐国内用户使用）
npm config set registry https://registry.npmmirror.com

# 查看当前镜像源
npm config get registry

# 恢复官方镜像源
npm config set registry https://registry.npmjs.org

使用 nrm 管理镜像源（推荐）

bash

# 安装 nrm（镜像源管理工具）
npm install -g nrm

# 查看可用镜像源列表
nrm ls

# 切换到淘宝镜像
nrm use taobao

# 切换到官方镜像
nrm use npm

# 测试镜像源速度
nrm test taobao

.npmrc 文件配置镜像源

在项目根目录创建 .npmrc 文件：

bash

# 项目级镜像源配置
registry=https://registry.npmmirror.com

# 针对特定 scope 使用不同镜像源
@my-company:registry=https://npm.company.com/

lock 文件说明

什么是 lock 文件？

lock 文件（package-lock.json）是 npm 自动生成的依赖锁定文件，记录了每个依赖的精确版本和下载地址。

为什么需要 lock 文件？

问题	没有 lock 文件	有 lock 文件
版本不一致	不同环境安装的版本可能不同	所有环境安装完全相同的版本
构建失败	依赖更新导致构建失败	依赖版本固定，构建稳定
协作问题	团队成员依赖版本不一致	团队成员使用相同版本

lock 文件的三个作用

锁定版本：确保所有环境安装相同版本
提升速度：记录下载地址，跳过依赖解析
保证安全：记录包的完整性校验值

lock 文件必须提交到 Git

bash

# .gitignore 中不要忽略 package-lock.json
# 但要忽略 node_modules
node_modules/

lock 文件冲突解决

bash

# 方案一：删除重新安装（简单粗暴，推荐新手）
rm -rf node_modules package-lock.json
npm install

# 方案二：使用 Git 合并（保留自己的版本）
git checkout --theirs package-lock.json
npm install

# 方案三：使用 npm-merge-driver（自动合并）
npx npm-merge-driver install

什么时候会更新 lock 文件？

bash

# 以下操作会更新 lock 文件：
npm install                    # 安装新包
npm update                     # 更新包
npm uninstall                  # 卸载包
npm ci                         # 不会更新（严格按 lock 安装）

缓存管理

bash

# 查看缓存目录路径
npm config get cache

# 清除所有缓存（--force 表示强制执行，不提示确认）
npm cache clean --force

# 验证缓存完整性（检查缓存是否损坏）
npm cache verify

# 查看缓存中的包数量
npm cache ls 2>/dev/null | wc -l

缓存的作用

提升安装速度：已下载的包会缓存，下次安装直接从缓存读取
离线安装：有缓存时可以离线安装（部分场景）
减少网络请求：避免重复下载相同的包

什么时候需要清理缓存？

安装失败且提示缓存相关错误
缓存占用空间过大（通常在 ~/.npm/_cacache 目录）
切换镜像源后需要清理旧缓存

配置管理

bash

# 查看所有配置
npm config list                # 简洁格式
npm config list -l             # 详细格式（包含所有默认值）

# 查看某个配置项
npm config get registry        # 查看镜像源
npm config get prefix          # 查看全局安装目录

# 设置配置项
npm config set registry https://registry.npmmirror.com
npm config set prefix ~/.npm-global

# 删除配置项
npm config delete registry

# 编辑配置文件（用默认编辑器打开 .npmrc）
npm config edit

.npmrc 文件

.npmrc 有三个级别，优先级从高到低：

项目级：项目根目录/.npmrc      # 优先级最高，只影响当前项目
用户级：~/.npmrc               # 影响当前用户的所有项目
全局级：$PREFIX/etc/npmrc      # 优先级最低，影响所有用户

bash

# .npmrc 常用配置

# 镜像源
registry=https://registry.npmmirror.com

# 私有仓库认证（使用环境变量 NPM_TOKEN）
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# 公司私有仓库
@my-company:registry=https://npm.company.com/
//npm.company.com/:_authToken=${COMPANY_TOKEN}

# 安装时的行为
save-exact=true          # 精确版本（不用 ^ 和 ~，锁定精确版本）
save-prefix=""           # 不加版本前缀（同上）
engine-strict=true       # 严格检查 engines 字段（Node 版本不匹配时报错）

# 包安装限制
ignore-scripts=true      # 禁止执行生命周期脚本（安全考虑，防止恶意脚本）

scope 配置

bash

# 不同 scope 使用不同 registry
# scope 是包名前的 @xxx，如 @vue/cli、@babel/core
@my-company:registry=https://npm.company.com/
@another:registry=https://npm.another.com/

npx

npx 是 npm 附带的工具，可以直接运行包中的命令而无需全局安装。

bash

# 运行本地安装的包（在 node_modules/.bin 中查找）
npx eslint src/
npx vite build

# 运行未安装的包（临时下载执行，执行完自动删除）
npx create-vite my-app
npx degit user/repo my-app

# 运行指定版本
npx <package>@<version>

# 执行多个命令（-y 表示自动确认，不提示）
npx -y concurrently "npm run dev" "npm run server"

# 指定要安装的包（-p 是 --package 的缩写，用于指定依赖包）
npx -p cowsay cowsay "hello"

npx vs 全局安装

场景	推荐	原因
脚手架工具（create-*）	npx	只用一次，不需要全局安装
项目构建工具（vite、webpack）	本地安装	项目依赖，需要版本锁定
代码检查工具（eslint）	本地安装	版本锁定，避免全局版本冲突
一次性命令	npx	不污染全局环境

npm workspaces（Monorepo）

什么是 Monorepo？

Monorepo（单一仓库）是一种项目管理方式：把多个相关的项目（包）放在同一个代码仓库中管理。

传统方式（Multirepo）：

repo-utils/          # 独立仓库
  └── package.json

repo-components/     # 独立仓库
  └── package.json

repo-app/            # 独立仓库
  └── package.json

Monorepo 方式：

my-project/          # 一个仓库
├── package.json     # 根配置
├── packages/
│   ├── utils/       # 工具库
│   │   └── package.json
│   └── components/  # 组件库
│       └── package.json
└── apps/
    ├── web/         # Web 应用
    │   └── package.json
    └── admin/       # 后台管理
        └── package.json

为什么用 Monorepo？

场景	传统方式	Monorepo
多个项目共享代码	需要发布 npm 包再引用	直接引用本地包，实时生效
修改一个库需要同时改多个项目	需要分别修改多个仓库	一个仓库内统一修改
统一代码规范和构建工具	每个仓库单独配置	根目录统一配置
查看某次修改影响了哪些项目	需要跨仓库搜索	一个仓库内搜索

什么时候用 Monorepo？

适合：

前端组件库 + 多个使用该组件库的项目
后端微服务（多个服务共享工具库）
全栈项目（前端 + 后端 + 共享类型定义）
工具库开发（一个仓库维护多个 npm 包）

不适合：

完全独立的项目（没有共享代码）
团队成员不熟悉 Monorepo
项目非常大（Git 仓库超过几个 GB）

npm workspaces 配置

npm 7+ 内置了 Monorepo 支持，通过 workspaces 字段配置：

json

{
  "name": "my-monorepo",
  "private": true,                    // 私有项目，不发布到 npm
  "workspaces": [
    "packages/*",                      // packages 目录下的所有子目录
    "apps/*"                           // apps 目录下的所有子目录
  ]
}

配置后，packages/ 和 apps/ 下的每个子目录都是一个独立的"工作空间"，有自己的 package.json。

常用命令

bash

# 安装所有工作空间的依赖（根目录执行一次即可，自动安装所有子项目的依赖）
npm install

# 在指定工作空间中执行命令
# -w 是 --workspace 的简写
npm run build -w packages/utils
npm run build --workspace=packages/utils

# 在所有工作空间中执行
# -ws 是 --workspaces 的简写
npm run build --workspaces
npm run build -ws

# 添加依赖到指定工作空间
npm install lodash -w packages/utils

# 添加公共依赖到根目录（-w . 表示根目录）
npm install -w . -D eslint

# 查看工作空间列表
npm query ':root > .workspace'

# 过滤执行（只执行有该脚本的工作空间，没有该脚本的跳过）
npm run build -ws --if-present

工作空间之间互相引用

在 Monorepo 中，一个包可以引用另一个包：

json

// apps/web/package.json
{
  "dependencies": {
    "@my-org/utils": "*",       // 引用本地的 utils 包（* 表示使用本地最新版本）
    "@my-org/components": "*"   // 引用本地的 components 包
  }
}

* 表示使用本地最新版本，npm 会自动创建软链接到 packages/utils，而不是从 npm 下载。

npm publish（发布包）

bash

# 登录 npm（首次发布需要登录）
npm login

# 检查将要发布的文件（预览模式，不实际发布）
npm pack --dry-run

# 发布包
npm publish

# 发布到指定 registry（公司私有仓库）
npm publish --registry https://npm.company.com/

# 发布 scoped 包（@xxx/yyy 格式的包默认私有，需加 --access public）
npm publish --access public

# 更新版本号
npm version patch    # 1.0.0 → 1.0.1（补丁版本，修复 bug）
npm version minor    # 1.0.0 → 1.1.0（次版本，新增功能）
npm version major    # 1.0.0 → 2.0.0（主版本，破坏性变更）

# 取消发布（72小时内可以取消，超过 72 小时无法取消）
npm unpublish <package>@<version>

package.json 常用字段

json

{
  "name": "my-project",                    // 包名（发布到 npm 时的名字）
  "version": "1.0.0",                      // 版本号（语义化版本）
  "description": "项目描述",                // 项目描述
  "main": "dist/index.js",                 // CommonJS 入口（require 时加载的文件）
  "module": "dist/index.mjs",              // ES Module 入口（import 时加载的文件）
  "types": "dist/index.d.ts",              // TypeScript 类型声明入口
  "exports": {                             // 现代入口配置（比 main/module 更灵活）
    ".": {
      "import": "./dist/index.mjs",        // ES Module 入口
      "require": "./dist/index.js",        // CommonJS 入口
      "types": "./dist/index.d.ts"         // TypeScript 类型入口
    },
    "./utils": "./dist/utils.js"           // 子路径导出
  },
  "files": ["dist"],                       // 发布时包含的文件（只发布 dist 目录）
  "sideEffects": false,                    // 是否有副作用（false 表示可安全 tree-shake）
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {                        // 生产环境依赖
    "vue": "^3.4.0"
  },
  "devDependencies": {                     // 开发环境依赖
    "vite": "^5.0.0"
  },
  "peerDependencies": {                    // 对等依赖（期望使用者安装）
    "vue": ">=3.0.0"
  },
  "engines": {                             // Node/npm 版本要求
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  },
  "browserslist": ["> 1%", "last 2 versions", "not dead"],  // 浏览器兼容目标
  "license": "MIT",                        // 开源协议
  "repository": {                          // 代码仓库地址
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "keywords": ["vue", "component"],        // 关键词（便于 npm 搜索）
  "author": "张三",                         // 作者
  "homepage": "https://example.com"        // 项目主页
}

关键字段说明

字段	说明	大白话解释
`main`	CommonJS 入口	用 `require('xxx')` 时加载的文件
`module`	ES Module 入口	用 `import xxx` 时加载的文件（打包工具专用）
`types`	TypeScript 类型声明	让 TypeScript 认识你的包，提供代码提示
`exports`	现代入口配置	更灵活的入口配置，可以为不同模块系统指定不同文件
`files`	发布时包含的文件	只发布指定的文件，避免把 src、test 等无关文件发布出去
`sideEffects`	是否有副作用	告诉打包工具哪些文件可以安全删除未使用的代码，帮助减小打包体积。设为 `false` 表示所有文件都没有副作用
`engines`	Node/npm 版本要求	告诉使用者你的包需要什么版本的 Node.js 才能运行
`browserslist`	浏览器兼容目标	告诉工具你的项目要兼容哪些浏览器，影响 CSS 前缀注入（Autoprefixer）和 JS 语法降级（Babel）的范围
`peerDependencies`	期望使用者安装的依赖	你的包「期望」使用者自己安装的依赖。比如你写了一个 Vue 组件库，Vue 就应该是 peerDependency，因为使用者的项目里已经有了

版本号规则

版本号格式：主版本.次版本.补丁版本（如 1.2.3）

符号	含义	示例	大白话解释
`^`	兼容版本	`^1.2.3` → `>=1.2.0 <2.0.0`	允许自动升级到兼容版本，保证不升级到有破坏性变更的大版本
`~`	近似版本	`~1.2.3` → `>=1.2.3 <1.3.0`	只允许补丁版本升级，更保守
`*`	任意版本	`*`	始终使用最新版本（不推荐，可能有破坏性变更）
`>=`	大于等于	`>=1.0.0`	使用 1.0.0 及以上版本
`1.2.3`	精确版本	`1.2.3`	只使用这个确切版本
`latest`	最新版本	`latest`	始终使用 npm 上的最新版本（不推荐）

与其他包管理器的命令对照表

功能	npm	yarn	pnpm	cnpm
初始化项目	`npm init`	`yarn init`	`pnpm init`	`cnpm init`
安装所有依赖	`npm install`	`yarn` / `yarn install`	`pnpm install`	`cnpm install`
安装指定包	`npm install <pkg>`	`yarn add <pkg>`	`pnpm add <pkg>`	`cnpm install <pkg>`
安装为 dev 依赖	`npm install -D <pkg>`	`yarn add -D <pkg>`	`pnpm add -D <pkg>`	`cnpm install -D <pkg>`
卸载包	`npm uninstall <pkg>`	`yarn remove <pkg>`	`pnpm remove <pkg>`	`cnpm uninstall <pkg>`
全局安装	`npm install -g <pkg>`	`yarn global add <pkg>`	`pnpm add -g <pkg>`	`cnpm install -g <pkg>`
全局卸载	`npm uninstall -g <pkg>`	`yarn global remove <pkg>`	`pnpm remove -g <pkg>`	`cnpm uninstall -g <pkg>`
运行脚本	`npm run <script>`	`yarn <script>`	`pnpm run <script>`	`cnpm run <script>`
更新依赖	`npm update`	`yarn upgrade`	`pnpm update`	`cnpm update`
查看依赖树	`npm ls`	`yarn list`	`pnpm list`	`cnpm ls`
清理缓存	`npm cache clean --force`	`yarn cache clean`	`pnpm store prune`	`cnpm cache clean --force`
CI/CD 安装	`npm ci`	`yarn --frozen-lockfile`	`pnpm install --frozen-lockfile`	`npm ci --registry=https://registry.npmmirror.com`

常见问题

EACCES 权限错误（全局安装）

bash

# 方案一：修改全局安装目录（推荐）
mkdir ~/.npm-global                    # 创建全局安装目录
npm config set prefix ~/.npm-global    # 设置全局安装目录
export PATH=~/.npm-global/bin:$PATH    # 将目录添加到 PATH 环境变量

# 方案二：使用 npx 代替全局安装（临时使用）
npx <package>

# 方案三：使用 Node 版本管理器（nvm），避免权限问题（推荐）
# nvm 安装的 Node.js 不需要 sudo 权限

安装速度慢

bash

# 使用淘宝镜像源（推荐国内用户）
npm config set registry https://registry.npmmirror.com

# 或使用 nrm 管理镜像源（可快速切换多个镜像源）
npm install -g nrm
nrm use taobao

package-lock.json 冲突

bash

# 方案一：删除重新安装（简单粗暴，推荐新手）
rm -rf node_modules package-lock.json
npm install

# 方案二：使用 Git 合并（保留自己的版本）
git checkout --theirs package-lock.json
npm install

# 方案三：使用 npm-merge-driver（自动合并，推荐团队使用）
npx npm-merge-driver install

node_modules 占用空间大

bash

# 查看 node_modules 大小
du -sh node_modules

# 清理并重新安装（使用 ci 确保版本一致）
rm -rf node_modules
npm ci

# 使用 npm cache verify 检查缓存（清理损坏的缓存）
npm cache verify

依赖版本不一致

bash

# 查看实际安装的版本
npm ls <package>

# 查看某个包被谁依赖（显示依赖链）
npm explain <package>

# 强制使用特定版本（在 package.json 中添加 overrides 字段）
{
  "overrides": {
    "lodash": "4.17.21"    // 强制所有依赖使用这个版本
  }
}

代理配置

bash

# 设置代理（公司内网或使用代理软件时需要配置）
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

# 删除代理
npm config delete proxy
npm config delete https-proxy

⚠️ 如果项目使用 yarn 或 pnpm，不要混用 npm，否则会导致依赖混乱。

npm 常用命令 ​

安装 & 初始化 ​

依赖管理 ​

四种依赖类型说明 ​

安装依赖 ​

升级 & 卸载 ​

查看依赖 ​

运行脚本 ​

创建自定义脚本 ​

脚本命名规范 ​

脚本编写技巧 ​

Vue 项目完整配置示例 ​

生命周期脚本 ​

内置生命周期 ​

依赖检查 ​

CI/CD 安装 ​

npm ci vs npm install ​

镜像源配置 ​

为什么需要配置镜像源？ ​

临时使用镜像源 ​

永久配置镜像源 ​

使用 nrm 管理镜像源（推荐） ​

.npmrc 文件配置镜像源 ​

lock 文件说明 ​

什么是 lock 文件？ ​

为什么需要 lock 文件？ ​

lock 文件的三个作用 ​

lock 文件必须提交到 Git ​

lock 文件冲突解决 ​

什么时候会更新 lock 文件？ ​

缓存管理 ​

缓存的作用 ​

什么时候需要清理缓存？ ​

配置管理 ​

.npmrc 文件 ​

scope 配置 ​

npx ​

npx vs 全局安装 ​

npm workspaces（Monorepo） ​

什么是 Monorepo？ ​

为什么用 Monorepo？ ​

什么时候用 Monorepo？ ​

npm workspaces 配置 ​

常用命令 ​

工作空间之间互相引用 ​

npm publish（发布包） ​

package.json 常用字段 ​

关键字段说明 ​

版本号规则 ​

与其他包管理器的命令对照表 ​

常见问题 ​

EACCES 权限错误（全局安装） ​

安装速度慢 ​

package-lock.json 冲突 ​

node_modules 占用空间大 ​

依赖版本不一致 ​

代理配置 ​

参考 ​

npm 常用命令

安装 & 初始化

依赖管理

四种依赖类型说明

安装依赖

升级 & 卸载

查看依赖

运行脚本

创建自定义脚本

脚本命名规范

脚本编写技巧

Vue 项目完整配置示例

生命周期脚本

内置生命周期

依赖检查

CI/CD 安装

npm ci vs npm install

镜像源配置

为什么需要配置镜像源？

临时使用镜像源

永久配置镜像源

使用 nrm 管理镜像源（推荐）

.npmrc 文件配置镜像源

lock 文件说明

什么是 lock 文件？

为什么需要 lock 文件？

lock 文件的三个作用

lock 文件必须提交到 Git

lock 文件冲突解决

什么时候会更新 lock 文件？

缓存管理

缓存的作用

什么时候需要清理缓存？

配置管理

.npmrc 文件

scope 配置

npx

npx vs 全局安装

npm workspaces（Monorepo）

什么是 Monorepo？

为什么用 Monorepo？

什么时候用 Monorepo？

npm workspaces 配置

常用命令

工作空间之间互相引用

npm publish（发布包）

package.json 常用字段

关键字段说明

版本号规则

与其他包管理器的命令对照表

常见问题

EACCES 权限错误（全局安装）

安装速度慢

package-lock.json 冲突

node_modules 占用空间大

依赖版本不一致

代理配置

参考