npm命令速查

init 交互式生成 package.json；-y 全部使用默认值。

npm init
npm init -y
npm init @vitejs/app myapp   # 用 init-script 脚手架
npm init vite@latest myapp -- --template react

i 是 install 缩写；默认写入 dependencies。

npm install
npm i                      # 按 package.json 安装全部
npm i axios
npm i react react-dom
npm i ./local-pkg.tgz      # 本地包
npm i github:user/repo     # git 仓库
npm i git+https://github.com/user/repo.git#v1.0.0

构建测试工具放 devDependencies；-g 装到全局（CLI 工具）。

npm i -D eslint vite typescript
npm i --save-dev prettier
npm i -g nodemon pm2
npm i react@18.2.0
npm i react@latest
npm i react@next
npm i --save-exact lodash   # 写死精确版本，不加 ^

optionalDependencies 安装失败不报错；从锁文件干净重建用 ci。

npm i -O fsevents          # 可选依赖（--save-optional）
npm i --force              # 强制，忽略冲突缓存
npm i --legacy-peer-deps   # 忽略 peer 依赖冲突（npm7+ 常见）
npm ci                     # CI 专用：按 lock 干净安装，不改 package.json
rm -rf node_modules package-lock.json && npm i

run 可省略于 start/test/stop/restart；传参加 --。

npm run dev
npm run build
npm run lint -- --fix
npm test
npm start
npm exec vite              # 等价 npx
npm run                    # 列出全部 scripts

outdated 检查新版本，update 按 semver 范围升级。

npm outdated
npm outdated -g --long
npm update                 # 更新到范围内最新（仍受 ^ ~ 限制）
npm update axios
npm i axios@latest         # 跨大版本升级（改 package.json）
npm i -g npm@latest        # 升级 npm 自己

会同步移除 package.json 中的记录。

npm uninstall axios
npm rm axios               # 别名
npm un axios
npm remove axios -D
npm uninstall -g nodemon
npm prune                  # 清理未在 package.json 中的多余包

验证发布前到底会包含哪些文件，产出 name-version.tgz。

npm pack
npm pack --dry-run
npm pack mylib-1.0.0.tgz  # 本地安装验证
# files 字段 / .npmignore 决定打包内容

扫描依赖中的已知漏洞；生产升级务必回归测试。

npm audit
npm audit --production
npm audit fix
npm audit fix --force     # 可能跨大版本，谨慎
npm audit --json > report.json

发布前注意 name 唯一、version 递增；私有源用 --registry。

npm whoami
npm login
npm publish
npm publish --access public      # 作用域包默认私有，需公开
npm version patch                # 自动升 0.0.x 并打 git tag
npm deprecate mylib@"<1.0.0" "有漏洞请升级"
npm unpublish mylib@1.0.0

调试待发布的本地库：库目录 link，项目目录 link 包名。

# 在组件库目录
cd mylib && npm link

# 在使用方项目目录
npm link mylib

# 解除
npm unlink mylib
# 或用文件依赖代替：npm i ../mylib

name+version 是必填字段，作为包的唯一标识。

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "示例项目",
  "type": "module",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "bin": { "mycli": "bin/cli.js" },
  "files": ["dist", "bin"],
  "author": "you",
  "license": "MIT",
  "private": true
}

scripts 中可直接调用 node_modules/.bin 里的命令，自动补 PATH。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext .js,.ts",
    "typecheck": "tsc --noEmit",
    "prepare": "husky install",
    "all": "npm run lint && npm run build"
  }
}

运行期用 dependencies，构建期 devDependencies，宿主提供 peerDependencies。

{
  "dependencies": {
    "axios": "^1.7.0",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "typescript": "~5.4.0"
  },
  "peerDependencies": {
    "react": ">=17.0.0"
  },
  "optionalDependencies": {},
  "bundledDependencies": []
}

engines 声明运行时版本；exports 定义包的子路径导出映射。

{
  "engines": { "node": ">=18.0.0", "npm": ">=9.0.0" },
  "browserslist": [
    "> 0.5%",
    "last 2 versions",
    "not dead"
  ],
  "exports": {
    ".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs" },
    "./utils": "./dist/utils.js"
  }
}

主版本.次版本.修订号：破坏性变更 / 新功能 / 修复。

1.4.2
│ │ └─ patch：bug 修复，向后兼容
│ └─── minor：新增功能，向后兼容
└───── major：破坏性变更

0.x.y：初始开发阶段，minor 升级也可能不兼容
预发布：1.0.0-beta.1 / 2.0.0-rc.1 / 3.0.0-alpha.2
加 build：1.0.0+20261004

npm i 默认写 ^；锁版本可 save-exact 或统一改 ~。

^1.2.3   # >=1.2.3 <2.0.0（可升 minor/patch；0.x 时只升 patch）
~1.2.3   # >=1.2.3 <1.3.0（只升 patch）
1.2.3    # 精确版本
>=1.2.0 <2.0.0
1.x      # >=1.0.0 <2.0.0
* 或 ""  # 任意版本
latest   # 标签，指向当前最新稳定版

latest/beta/next 等标签让用户按渠道安装，不必记版本号。

npm view react versions --json
npm view react dist-tags
npm dist-tag ls mylib
npm dist-tag add mylib@2.0.0-beta.1 beta
npm dist-tag rm mylib beta
npm i typescript@beta
npm i typescript@5.4.5

优先找本地 node_modules/.bin，找不到临时下载到缓存执行。

npx eslint .
npx tsc --init
npx create-vite@latest myapp
npx http-server ./dist -p 8080
npx --no-install prettier .   # 只用本地已安装，没有就报错
npx -p cowsay cowsay "hi"     # 指定包再执行其中命令

npm exec 是 npx 的底层命令，可精确指定执行的包版本。

npm exec -- prettier --write .
npm exec --package=yo@4 -- yo --version
npx npm@10 -v               # 临时用指定版本的 npm
npx -y degit user/repo      # -y/--yes 跳过安装确认

三者功能对应；pnpm 用硬链接节省磁盘，workspace 体验更好。

npm install          yarn            pnpm install
npm i axios          yarn add axios  pnpm add axios
npm i -D eslint      yarn add -D eslint   pnpm add -D eslint
npm i -g nodemon     yarn global add nodemon  pnpm add -g nodemon
npm uninstall axios  yarn remove axios  pnpm remove axios
npm update           yarn upgrade    pnpm update
npm run dev          yarn dev        pnpm dev
npm ci               yarn install --frozen-lockfile  pnpm install --frozen-lockfile

npm 扁平 node_modules；pnpm 内容寻址 + 符号链接，严格隔离幽灵依赖。

npm:   package-lock.json + 扁平 node_modules
yarn:  yarn.lock (v1) / .yarn/cache (v2+)
pnpm:  pnpm-lock.yaml + node_modules/.pnpm 硬链接存储

# pnpm 幽灵依赖示例：
# 没在 package.json 声明的包，npm 可能能 require 到，pnpm 直接报错，更严格

多包仓库用 workspaces 互相引用本地包。

// package.json (npm/yarn)
{
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

pnpm add shared-utils --filter web   # 只给 web 包加依赖
pnpm -r run build                    # 递归执行所有包

项目根目录的 .npmrc 随仓库共享；用户级在 ~/.npmrc。

registry=https://registry.npmmirror.com
save-exact=false
save-prefix=^
engine-strict=true
legacy-peer-deps=true
fund=false
audit=false
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
strict-ssl=true
cafile=/path/to/cert.pem
proxy=http://127.0.0.1:7890
https-proxy=http://127.0.0.1:7890

@scope 单独指向私有 registry，公共包仍走官方源。

@mycompany:registry=https://npm.mycompany.com/
//npm.mycompany.com/:_authToken=${NPM_TOKEN}

# 安装私有包
npm i @mycompany/ui@1.2.0

# 临时使用
npm i pkg --registry=https://registry.npmmirror.com

查看/设置/删除配置项；ls -l 显示来源文件。

npm config list
npm config list -l              # 全部默认值与来源
npm config get registry
npm config set registry https://registry.npmmirror.com
npm config delete registry
npm config set save-exact true
npm config get cache
npm cache clean --force
npm root -g                     # 全局安装路径