8. npm 使用入门

本节目标：npm 安装、依赖管理、语义化版本、常用命令与 npx 的用法。

npm 是 Node.js 的默认包管理器，安装 Node.js 时就会自动装上。它的全名是 Node Package Manager，但干的活远不止「装包」这么简单——管理依赖版本、运行脚本、审计安全漏洞，这些全是它的职责范围。

截至 2026 年，npm 仓库里的包已经超过 250 万个。可以这么说，你想做的事，大概率有人已经把轮子造好放在那里了。

确认安装与基本命令

打开终端，先检查版本：

npm -v

v24 LTS 配套的 npm 版本通常是 10.x。如果版本太老，可以自升级：

npm install -g npm@latest

接下来这些命令，是你日常最频繁接触的：

npm init -y              # 快速初始化 package.json
npm install <包名>        # 安装依赖
npm uninstall <包名>      # 卸载依赖
npm update <包名>         # 更新依赖
npm outdated             # 查看哪些包有新版本
npm audit                # 安全检查

本地安装 vs 全局安装

装包分两种姿势，很多人刚开始会搞混。

本地安装（默认）：

npm install lodash

包被下载到当前项目的 node_modules 目录，并在 package.json 的 dependencies 里登记。这是生产依赖的标准做法。

全局安装：

npm install -g nodemon

包装到系统级目录，命令行里直接可用。适合装 CLI 工具，比如 nodemon、typescript、http-server。

Warning

全局安装容易遇到权限问题。macOS/Linux 上别急着加 sudo，先用 npx（下面会讲）或配置 npm 的全局目录到用户空间。Windows 上相对省心，但也别全局乱装，否则系统里会有一堆你不知道从哪来的命令。

依赖类型：别什么都往 dependencies 里塞

package.json 里有三种常见的依赖字段，含义完全不同：

字段	用途	安装命令
`dependencies`	项目运行必需的包	`npm install <pkg>`
`devDependencies`	开发、测试、构建时才需要的包	`npm install -D <pkg>`
`optionalDependencies`	有了更好，没有也能跑的包	`npm install -O <pkg>`

{
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "nodemon": "^3.0.0",
    "eslint": "^9.0.0"
  }
}

生产环境部署时，执行 npm install --production 只会装 dependencies，devDependencies 会被跳过。所以千万别把 express 这种运行必备包装到 devDependencies 里，否则上线就炸。

Tip

还有一个 peerDependencies，常见于插件类包。它表示「我的包需要宿主项目也安装某个依赖，但我不自己带」。比如一个 React 组件库会把 react 放在 peerDependencies 里，由使用它的项目决定 React 版本。

package-lock.json：版本锁定的保险

每次安装或更新依赖，npm 都会生成（或更新）package-lock.json。这个文件记录了依赖树的精确版本和下载地址。

它的作用很简单：确保所有人安装的依赖完全一致。你把代码提交到 Git，package-lock.json 也要一起提交。同事克隆下来执行 npm install，得到的 node_modules 和你本地一模一样。

Note

如果你手动改了 package.json 里的版本号，但没有重新运行 npm install，package-lock.json 不会自动同步。建议改完版本后跑一次 npm install，让 lock 文件保持最新。

npm scripts：把命令存起来

package.json 里的 scripts 字段，是 npm 最被低估的功能之一。它能把长命令缩短成几个字：

{
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js",
    "test": "node --test",
    "lint": "eslint ."
  }
}

运行方式：

npm run dev      # 执行 nodemon app.js
npm start        # 特殊脚本，可省略 run
npm test         # 同上

scripts 里还能写 pre 和 post 钩子。比如 npm run build 之前自动先执行 prebuild：

{
  "scripts": {
    "prebuild": "npm run lint",
    "build": "node build.js",
    "postbuild": "echo '构建完成'"
  }
}

执行 npm run build，实际顺序是：prebuild → build → postbuild。这个机制在自动化流程里非常实用。

npx：不用全局安装的魔法

npx 从 npm 5.2.0 开始内置，它的作用是「临时执行 npm 包，用完即走」。

举个例子，你想用 create-next-app 初始化项目，传统做法：

npm install -g create-next-app   # 全局安装
create-next-app my-app           # 使用

用 npx 就一句话：

npx create-next-app my-app

npx 会先把包下载到临时目录，执行完清理掉。既不用污染全局环境，又永远用的是最新版本。

更妙的是，npx 会优先找当前项目 node_modules/.bin 里的本地命令。假设你项目里装了 eslint：

npx eslint .     # 直接用项目本地版本，不用全局装

这比记 ./node_modules/.bin/eslint . 这种长路径舒服多了。

Tip

有些包第一次运行 npx 会提示确认安装，加 --yes 可以自动同意：npx --yes create-next-app my-app。

安全审计：npm audit

npm 仓库虽大，但也混入了不少有漏洞的包。npm 内置了审计功能：

npm audit           # 查看漏洞报告
npm audit fix       # 自动修复能修的（升级小版本）
npm audit fix --force   # 强制修复，可能涉及主版本升级，谨慎使用

我建议每次拉取新代码、更新依赖后，顺手跑一遍 npm audit。安全问题不解决，迟早会变成线上故障。

npm ci：CI/CD 环境的首选

在持续集成/持续部署环境里，用 npm install 有个隐患：它可能会根据 package.json 的版本范围（如 ^1.2.0）安装更新的包，导致构建结果和本地不一致。

npm ci 是专门为自动化环境设计的：

严格依照 package-lock.json 安装，忽略 package.json 里的版本范围。
如果 package-lock.json 和 package.json 不一致，直接报错退出。
先删除现有 node_modules，再干净安装，速度通常比 npm install 更快。

npm ci

GitHub Actions、GitLab CI、Jenkins 里都用它，这是团队项目的标准做法。

实战：从 0 搭建一个项目

走一遍完整流程，把刚才学的串起来：

# 1. 创建项目目录
mkdir my-project && cd my-project

# 2. 初始化 package.json
npm init -y

# 3. 安装生产依赖
npm install express

# 4. 安装开发依赖
npm install -D nodemon

# 5. 添加脚本

编辑 package.json：

{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "nodemon": "^3.0.0"
  }
}

// app.js
import express from 'express';
const app = express();

app.get('/', (req, res) => {
  res.send('Hello npm!');
});

app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});

运行：

npm run dev

打开浏览器访问 http://localhost:3000，看到 Hello npm! 就说明一切正常。