npm 与 npx 包管理速查表

🚀 基础命令与帮助 >>

npm -v | 查看 npm 版本
npm --help | 显示帮助总览
npm -l | 显示所有命令的用法概览
npm <command> -h | 查看某个命令的快速帮助
npm help <term> | 在浏览器中搜索帮助文档
npm help npm | 打开更完整的 npm 总览文档
npm config list | 查看当前配置
npm config get registry | 查看当前 registry 地址
npm prefix -g | 查看全局安装路径
npm doctor | 检查常见环境问题

常用环境信息

npm version          # 显示 npm / node / v8 等版本
npm config list -l  # 显示完整配置
npm root -g         # 全局 node_modules 目录

先熟悉版本、帮助与配置查询，再结合下面各模块学习高频命令的实际用法。

🧾 命令索引与功能分组 >>

安装与依赖管理： install, install-ci-test, install-test, ci, update, outdated, uninstall, cache, shrinkwrap, find-dupes
脚本与执行： run, test, start, stop, restart, exec, completion
发布与版本： publish, version, dist-tag, deprecate, undeprecate, unpublish, pack, sbom
账号与权限： login, logout, whoami, adduser, access, owner, team, org, token, profile
信息查询与文档： view, search, docs, repo, bugs, explain, explore, edit, pkg, query
配置与诊断： config, get, set, root, prefix, doctor, ping, fund, audit
列表与别名工具： ls, ll, root, prefix, repo
帮助与元信息： help, help-search, access, org, team

使用建议

1. 在本页按模块浏览核心命令示例
2. 遇到不熟悉的命令名，先在本卡片中找到所属功能分组
3. 再用 `npm help <command>` 或点击上方链接查看官方详细文档

将官方 help 中的命令列表按功能拆成多个小模块，方便快速反查命令家族，而不是一大块难以消化的纯文本索引。

📦 依赖安装与卸载 >>

npm install | 按 package.json 安装全部依赖
npm install <pkg> | 安装到 dependencies
npm install <pkg> -D | 安装到 devDependencies
npm install -g <pkg> | 全局安装 CLI 工具
npm uninstall <pkg> | 卸载依赖
npm install <pkg>@<version> | 安装指定版本
npm install <pkg>@latest | 安装最新稳定版

锁定与重装依赖

# 严格按照 package-lock.json 安装
npm ci

# 清理并重新安装
rm -rf node_modules package-lock.json
npm install

区分本地/全局、生产/开发依赖，注意 use npm ci 保证可重复构建。

🛠️ 依赖更新与安全审计 >>

npm outdated | 列出可更新依赖
npm update | 按 semver 范围更新依赖
npm update <pkg> | 更新指定依赖
npm audit | 扫描已知安全漏洞
npm audit fix | 自动更新可修复漏洞
npm audit fix --force | 允许破坏性更新

常见升级策略

# 仅修补 BUG / Patch
# package.json 中使用 ~1.2.3

# 兼容小版本的新特性
# package.json 中使用 ^1.2.3

# 全量升级并手动测试
npm outdated
npm update

结合 semver 范围与 audit 报告，控制更新节奏与风险。

🔍 依赖树与包信息查询 >>

npm list | 查看当前项目依赖树
npm list --depth=0 | 仅显示顶层依赖
npm list <pkg> | 查看指定包在依赖树中的位置
npm view <pkg> version | 查看最新稳定版本号
npm view <pkg> versions --json | 获取所有已发布版本
npm view <pkg> dist-tags | 查看 latest/next 等 dist-tag
npm search <keywords> | 在 registry 中搜索包（交互式输出）

调试依赖版本与 peerDependencies

npm list react                 # 查看项目中 React 的安装情况
npm list react --depth=0      # 只看顶层是否直接依赖 React

npm view react version        # 最新稳定版本
npm view react@18 peerDependencies

npm search eslint prettier    # 按关键字搜索相关包

使用 list 检查本地依赖树，配合 view/search 查询远程元数据，快速定位版本与依赖关系问题。

📜 npm scripts 与生命周期 >>

npm run <script> | 运行 package.json 中的脚本
npm test | 等价于 npm run test
npm start | 等价于 npm run start
npm run lint -- --fix | 给脚本透传参数
npm run | 列出所有脚本
npm set-script <name> <cmd> | 命令行新增脚本

脚本与生命周期示例

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint src --fix",

    "prepublishOnly": "npm test",
    "postinstall": "node scripts/postinstall.js"
  }
}

统一通过 npm run 管理任务，结合生命周期脚本自动化构建与发布前检查。

⚡ npx 临时执行 CLI 工具 >>

npx <pkg> | 直接执行本地或远程包
npx <pkg>@latest | 始终使用包最新版本
npx --yes <pkg> | 自动确认安装提示
npx --no-install <pkg> | 只使用已有安装，不触发下载
npx -p <pkg> <cmd> | 以临时依赖方式执行命令

脚手架与一次性命令

# 创建新项目
npx create-vite@latest my-app
npx create-next-app@latest my-app

# 一次性代码检查
npx eslint . --ext .js,.ts

# 指定 node 选项
NODE_OPTIONS=\"--max_old_space_size=4096\" npx jest

npx 适合一次性脚手架与工具，不污染全局环境，同时复用本地缓存。

🌐 registry 与缓存管理 >>

npm config get registry | 查看当前源
npm config set registry <url> | 设置新源
npm config delete registry | 恢复默认 registry
npm cache verify | 检查缓存完整性
npm cache clean --force | 清理本地缓存

.npmrc 配置示例

# 用户级 ~/.npmrc
registry=https://registry.npmjs.org/
audit=true
save-prefix=^

# 项目级 .npmrc
legacy-peer-deps=false
engine-strict=true

通过 .npmrc 统一管理 registry、审计与安装策略，缓存异常时适度清理。

🚢 发布与版本管理 >>

npm login | 登录 npm registry
npm whoami | 查看当前登录用户
npm version <major|minor|patch> | 自动更新版本号与 tag
npm publish | 发布包到 registry
npm publish --tag next | 发布到自定义标签
npm dist-tag add pkg@1.2.3 next | 手动添加 dist-tag
npm unpublish pkg@1.2.3 | 撤回指定版本（需谨慎）

发布流程示例

# 1. 确认工作区干净
git status

# 2. 运行测试与构建
npm test
npm run build

# 3. 更新版本并打 tag
npm version patch

# 4. 发布到 npm
npm publish

以 npm version 管理版本与 Git tag，配合 dist-tag 控制灰度与稳定通道。

🧰 高级管理：link / pack / prune >>

npm link | 将本地包以全局形式链接，或在项目中链接调试本地包
npm pack | 生成当前包的发布 tarball
npm prune | 移除 node_modules 中多余/未声明的依赖
npm dedupe | 去重依赖树，尽量合并相同版本
npm rebuild | 重新编译原生模块（如 node-gyp）

本地调试与清理示例

# 在本地同时开发库与应用
cd my-lib
npm link                  # 将 my-lib 链接为全局包

cd ../my-app
npm link my-lib          # 在应用中使用本地 my-lib

# 清理与去重
npm prune
npm dedupe

这些高级命令常用于本地包调试、生成离线包与清理/整理依赖树，在大型项目和库开发中尤为常见。

🏗️ Workspaces 多包管理 >>

\"workspaces\" 字段 | 在 package.json 中声明子包
npm install -w <ws> | 在指定 workspace 安装依赖
npm run <script> -w <ws> | 在单个 workspace 运行脚本
npm run <script> --workspaces | 在所有 workspace 执行脚本
npm exec -w <ws> <cmd> | 在指定 workspace 执行命令

根 package.json 示例

{
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "build": "npm run build --workspaces",
    "test": "npm run test --workspaces"
  }
}

Workspaces 适合多包仓库，统一管理依赖与脚本，减少重复安装。