---

title: NPM 学习指南：从入门到项目实践 date: 2026-08-10 tags:

• NPM
• Node.js
• JavaScript
• 前端开发 categories:
• 技术教程 description: 系统学习 NPM 的基础概念、常用命令、依赖管理、脚本配置、包发布以及常见问题处理。

---

NPM 学习指南：从入门到项目实践

NPM 是 JavaScript 和 Node.js 生态中最常用的包管理工具之一。它可以帮助开发者安装、更新和管理项目依赖，也可以运行项目脚本、配置镜像源以及发布自己的 JavaScript 包。

本文将介绍 NPM 的核心概念、常用命令和实际开发流程，适合作为入门教程和日常速查手册。

一、NPM 是什么

NPM 的全称是 Node Package Manager，通常会随着 Node.js 一起安装。

NPM 主要由以下几个部分组成：

1. NPM 网站：用于搜索和查看公开发布的软件包。
2. NPM Registry：用于存储和分发软件包的公共仓库。
3. NPM CLI：在命令行中使用的 npm 工具。

通过 NPM，我们可以快速安装别人编写的工具和库，例如：

• Vue
• React
• Express
• Axios
• TypeScript
• ESLint
• Vite

NPM 官方网站：

https://www.npmjs.com/

---

二、安装 Node.js 和 NPM

NPM 通常不需要单独安装。安装 Node.js 后，NPM 会一起安装到系统中。

Node.js 官方网站：

https://nodejs.org/

对于大多数开发者，建议安装 Node.js 的 LTS（长期支持）版本。

1. 查看 Node.js 版本

node -v

2. 查看 NPM 版本

npm -v

如果以上命令能够正常输出版本号，说明安装成功。

3. 更新 NPM

npm install -g npm@latest

更新完成后，再次查看版本：

npm -v

---

三、初始化 NPM 项目

进入项目目录后执行：

npm init

NPM 会依次询问项目名称、版本号、描述和入口文件等信息，最后生成 package.json 文件。

如果希望直接使用默认配置，可以执行：

npm init -y

生成的 package.json 大致如下：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

---

四、认识 package.json

package.json 是 Node.js 项目的核心配置文件，用来记录项目信息、依赖和脚本等内容。

常见字段

字段	作用
name	项目或软件包名称
version	当前版本号
description	项目说明
main	CommonJS 软件包入口文件
type	指定模块类型，例如 module
scripts	项目脚本命令
keywords	软件包关键词
author	作者信息
license	开源许可证
dependencies	生产环境依赖
devDependencies	开发环境依赖
peerDependencies	宿主项目应提供的依赖
engines	支持的 Node.js 或 NPM 版本
private	是否禁止发布到 NPM

一个更完整的示例：

{
  "name": "npm-demo",
  "version": "1.0.0",
  "description": "一个用于学习 NPM 的示例项目",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "test": "vitest"
  },
  "dependencies": {
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0",
    "vite": "^7.0.0",
    "vitest": "^3.0.0"
  },
  "engines": {
    "node": ">=20"
  },
  "private": true
}

应用项目如果不准备发布到 NPM，建议设置 "private": true，避免误操作发布。

---

五、安装项目依赖

1. 安装 package.json 中的全部依赖

npm install

也可以简写为：

npm i

执行后通常会生成：

• node_modules：存放实际安装的依赖。
• package-lock.json：记录依赖树和精确版本。

2. 安装生产依赖

npm install <包名>

例如：

npm install axios

安装后，依赖会被写入 dependencies：

{
  "dependencies": {
    "axios": "^1.7.0"
  }
}

3. 安装开发依赖

npm install <包名> --save-dev

可以简写为：

npm i <包名> -D

例如：

npm i eslint -D

开发依赖会被写入 devDependencies。

常见开发依赖包括：

• 打包工具
• 测试框架
• 代码检查工具
• 格式化工具
• TypeScript 编译器

4. 安装指定版本

npm install <包名>@<版本号>

例如：

npm install axios@1.7.2

5. 安装最新版本

npm install <包名>@latest

6. 全局安装软件包

npm install -g <包名>

例如：

npm install -g typescript

查看全局安装目录：

npm root -g

项目使用的库一般应该安装在项目内部。只有需要直接在命令行中使用的通用工具，才考虑全局安装。

---

六、dependencies 和 devDependencies 的区别

dependencies

项目在生产环境运行时需要的依赖，应放在 dependencies 中。

例如：

npm install express
npm install axios

devDependencies

只在开发、构建或测试期间使用的依赖，应放在 devDependencies 中。

例如：

npm install vite -D
npm install eslint -D
npm install vitest -D

简单理解：

类型	使用阶段	常见软件包
dependencies	项目运行阶段	Express、Axios、React
devDependencies	开发和构建阶段	ESLint、Vite、Prettier、Vitest

不过，现代前端应用在部署时通常只上传构建后的静态文件，因此依赖分类还需要结合具体的构建和部署方式判断。

---

七、卸载依赖

1. 卸载项目依赖

npm uninstall <包名>

例如：

npm uninstall axios

也可以使用：

npm remove axios

执行后，NPM 会同时更新 package.json 和 package-lock.json。

2. 卸载全局依赖

npm uninstall -g <包名>

---

八、查看已安装的依赖

1. 查看当前项目的顶层依赖

npm list --depth=0

2. 查看指定软件包

npm list <包名>

例如：

npm list axios

3. 查看全局安装的软件包

npm list -g --depth=0

4. 查看软件包的公开信息

npm view <包名>

查看最新版本：

npm view <包名> version

查看全部版本：

npm view <包名> versions

例如：

npm view vite version
npm view vite versions

---

九、更新依赖

1. 检查过期依赖

npm outdated

输出中常见的字段包括：

字段	含义
Current	当前安装版本
Wanted	当前版本范围允许安装的最高版本
Latest	软件包的最新版本

2. 在现有版本范围内更新依赖

npm update

更新指定依赖：

npm update <包名>

3. 安装软件包的最新版本

npm install <包名>@latest

升级主版本之前，应先阅读软件包的更新日志和迁移指南，因为主版本可能包含不兼容修改。

---

十、语义化版本规则

NPM 软件包通常遵循语义化版本规范：

主版本.次版本.修订版本
Major.Minor.Patch

例如：

2.5.3

各部分含义：

• 2：主版本，通常包含不兼容修改。
• 5：次版本，通常表示向后兼容的新功能。
• 3：修订版本，通常表示向后兼容的问题修复。

常见版本范围

写法	含义
1.2.3	只允许安装 1.2.3
^1.2.3	通常允许更新次版本和修订版本，但不更新主版本
~1.2.3	通常只允许更新修订版本
>=1.2.3	安装 1.2.3 或更高版本
1.x	安装主版本为 1 的兼容版本
*	可以安装任意版本，不建议随意使用
latest	安装标记为 latest 的版本

例如：

{
  "dependencies": {
    "package-a": "1.2.3",
    "package-b": "^1.2.3",
    "package-c": "~1.2.3"
  }
}

当主版本为 0 时，^ 的允许范围会更加严格，因为 0.x 软件通常被视为尚未稳定。

---

十一、package-lock.json 的作用

package-lock.json 会记录完整依赖树以及解析得到的精确版本。

它的主要作用包括：

1. 让不同开发者安装到一致的依赖版本。
2. 提高依赖安装的可重复性。
3. 保存间接依赖的版本和下载信息。
4. 帮助 NPM 优化安装过程。

通常应该将 package-lock.json 提交到 Git 仓库：

git add package.json package-lock.json
git commit -m "chore: 更新项目依赖"

不建议将下面的目录提交到 Git：

node_modules/

可以在 .gitignore 中添加：

node_modules/

---

十二、npm install 和 npm ci 的区别

npm install

npm install

特点：

• 适合日常开发。
• 会根据 package.json 解析依赖。
• 必要时会更新 package-lock.json。
• 可以用于添加、删除和更新依赖。

npm ci

npm ci

特点：

• 需要项目中存在 package-lock.json。
• 严格按照锁文件安装依赖。
• 安装前会删除已有的 node_modules。
• 如果 package.json 和锁文件不一致，会直接报错。
• 通常更适合 CI/CD 和可重复构建。

简单选择：

场景	推荐命令
本地日常开发	npm install
添加新依赖	npm install <包名>
CI/CD 自动构建	npm ci
严格复现锁文件中的依赖	npm ci

---

十三、使用 scripts 运行项目命令

可以在 package.json 的 scripts 字段中定义项目命令：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "test": "vitest"
  }
}

运行脚本：

npm run dev
npm run build
npm run lint
npm run test

其中部分特殊脚本可以省略 run：

npm start
npm test
npm stop
npm restart

查看项目中可用的脚本：

npm run

脚本参数

向脚本传递额外参数时，需要使用 --：

npm run test -- --watch

前置和后置脚本

NPM 支持 pre 和 post 前缀：

{
  "scripts": {
    "prebuild": "npm run lint",
    "build": "vite build",
    "postbuild": "node scripts/report.js"
  }
}

执行下面的命令时：

npm run build

NPM 会按照以下顺序运行：

prebuild → build → postbuild

---

十四、使用 npx 运行软件包

npx 可以运行项目依赖提供的命令，而不需要手动寻找 node_modules/.bin 目录。

例如，在项目安装了 ESLint 后：

npx eslint .

创建 Vite 项目：

npm create vite@latest

运行指定版本的软件包：

npx typescript@latest --version

npx 常见用途：

1. 运行当前项目中的命令行工具。
2. 临时获取并运行某个软件包。
3. 避免安装不常用的全局工具。

运行不熟悉的软件包之前，应确认包名、维护者和来源，避免执行恶意代码。

---

十五、配置 NPM 镜像源

1. 查看当前 Registry

npm config get registry

NPM 官方 Registry：

https://registry.npmjs.org/

2. 设置 Registry

npm config set registry <地址>

切换回官方源：

npm config set registry https://registry.npmjs.org/

3. 临时指定 Registry

npm install <包名> --registry=<地址>

4. 删除自定义 Registry 配置

npm config delete registry

5. 查看全部 NPM 配置

npm config list

发布软件包之前，需要确认 Registry 指向准备发布的平台。

---

十六、认识 .npmrc 配置文件

.npmrc 用来保存 NPM 配置。

项目级 .npmrc 示例：

registry=https://registry.npmjs.org/
save-exact=true
engine-strict=true

常见配置：

配置	作用
registry	设置软件包仓库地址
save-exact	安装依赖时保存精确版本
engine-strict	严格检查 Node.js 版本要求
legacy-peer-deps	使用旧方式处理 peer dependencies
strict-ssl	是否严格验证 SSL 证书

不要将访问令牌直接写入并提交到公开仓库。包含敏感信息的用户配置应妥善保管。

---

十七、NPM 缓存管理

1. 查看缓存目录

npm config get cache

2. 验证缓存完整性

npm cache verify

3. 强制清理缓存

npm cache clean --force

通常不需要主动清理缓存。遇到明确的缓存损坏问题时，优先运行：

npm cache verify

---

十八、依赖安全检查

1. 检查已知安全问题

npm audit

2. 自动修复兼容范围内的问题

npm audit fix

3. 强制进行可能包含破坏性升级的修复

npm audit fix --force

--force 可能升级到不兼容的主版本。执行前应提交当前代码，并在执行后运行完整测试。

4. 仅生成生产依赖报告

npm audit --omit=dev

发现安全警告后，建议：

1. 确认问题来自直接依赖还是间接依赖。
2. 查看漏洞的实际影响范围。
3. 阅读软件包的升级说明。
4. 更新后运行测试和构建命令。
5. 不要为了消除提示而盲目强制升级。

---

十九、清理和重新安装依赖

当依赖目录损坏或安装状态异常时，可以删除 node_modules 后重新安装。

macOS 或 Linux：

rm -rf node_modules
npm install

Windows PowerShell：

Remove-Item node_modules -Recurse -Force
npm install

如果希望严格按照锁文件重新安装：

npm ci

是否删除 package-lock.json 需要谨慎判断。锁文件能够保证版本一致，通常不应把删除锁文件作为第一种解决方式。

---

二十、Peer Dependencies 是什么

peerDependencies 表示当前软件包需要由使用者的项目提供某个依赖。

例如，一个 React 组件库可能这样配置：

{
  "peerDependencies": {
    "react": ">=18",
    "react-dom": ">=18"
  }
}

这表示组件库需要 React，但通常不希望在组件库内部再安装一份独立的 React。

peerDependencies 常见于：

• UI 组件库
• 插件系统
• ESLint 插件
• Webpack、Vite 等工具的插件
• 依赖特定框架运行的软件包

如果出现 peer dependency 冲突，应优先检查各个软件包要求的版本范围，而不是直接长期依赖 --force 或 --legacy-peer-deps。

---

二十一、Optional Dependencies 是什么

optionalDependencies 表示可选依赖。即使这些依赖安装失败，NPM 也可以继续完成安装。

{
  "optionalDependencies": {
    "some-optional-package": "^1.0.0"
  }
}

可选依赖适合用于：

• 特定操作系统才需要的功能。
• 有依赖时启用、无依赖时跳过的增强功能。
• 不影响项目核心功能的扩展模块。

项目代码需要正确处理可选依赖不存在的情况。

---

二十二、查看依赖关系和来源

1. 查看依赖树

npm list

依赖较多时，可以限制层级：

npm list --depth=1

2. 查看某个依赖为什么被安装

npm explain <包名>

例如：

npm explain lodash

这对于排查间接依赖和安全警告非常有帮助。

3. 查找重复依赖

npm dedupe

npm dedupe 会尝试优化依赖树，将兼容的重复依赖提升到更高层级。

---

二十三、创建一个简单的 Node.js 项目

第一步：创建项目目录

mkdir npm-demo
cd npm-demo

第二步：初始化项目

npm init -y

第三步：安装 Express

npm install express

第四步：修改 package.json

{
  "name": "npm-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "private": true
}

第五步：创建 index.js

import express from 'express'

const app = express()
const port = 3000

app.get('/', (request, response) => {
  response.send('Hello NPM!')
})

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`)
})

第六步：启动项目

npm run dev

打开浏览器访问：

http://localhost:3000

---

二十四、发布自己的 NPM 包

1. 准备 package.json

用于发布的软件包至少需要正确设置名称和版本号：

{
  "name": "your-package-name",
  "version": "1.0.0",
  "description": "软件包说明",
  "main": "index.js",
  "files": [
    "index.js",
    "dist"
  ],
  "keywords": [
    "example"
  ],
  "license": "MIT"
}

软件包名称必须符合 NPM 命名规则，并且不能与公共仓库中已有的软件包重名。

2. 登录 NPM

npm login

根据提示完成身份验证。

3. 查看当前登录用户

npm whoami

4. 检查即将发布的文件

npm pack --dry-run

该命令可以查看哪些文件会被包含在软件包中，但不会真正发布。

5. 发布软件包

npm publish

对于公开的 scoped package，通常需要：

npm publish --access public

6. 更新版本号

修订版本：

npm version patch

次版本：

npm version minor

主版本：

npm version major

这些命令通常会修改 package.json 和 package-lock.json，并创建相应的 Git 提交和标签。

7. 发布新版本

npm publish

已经发布的同一个版本号不能再次发布。修改内容后，需要先更新版本号。

---

二十五、控制软件包发布内容

发布前应避免将测试文件、临时文件和敏感配置包含在软件包中。

使用 files 字段

推荐在 package.json 中明确列出需要发布的内容：

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

使用 .npmignore

也可以创建 .npmignore：

src/
tests/
coverage/
.env
*.log

发布之前再次检查：

npm pack --dry-run

不要发布以下内容：

• 密码和访问令牌
• .env 环境变量文件
• 私钥和证书
• 内部服务器地址
• 不应公开的源代码或业务数据

---

二十六、NPM Workspaces 基础

Workspaces 可以在一个仓库中管理多个相关的软件包，常用于 Monorepo 项目。

项目结构示例：

my-monorepo/
├── package.json
└── packages/
    ├── app/
    │   └── package.json
    └── utils/
        └── package.json

根目录 package.json：

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ]
}

为指定 workspace 安装依赖：

npm install axios --workspace=app

在指定 workspace 中运行脚本：

npm run build --workspace=app

在所有 workspace 中运行脚本：

npm run test --workspaces

查看 workspace 信息：

npm query .workspace

---

二十七、常见问题处理

1. 提示 npm 不是内部或外部命令

可能原因：

• 尚未安装 Node.js。
• Node.js 安装目录没有添加到系统环境变量。
• 安装完成后终端没有重新打开。

先执行：

node -v
npm -v

如果两个命令都无法使用，可以重新安装 Node.js，并确认安装目录已经加入 PATH。

2. 安装依赖时速度较慢

可以检查网络状态和当前 Registry：

npm config get registry

必要时切换到可访问的镜像源，但应确保镜像来源可信且同步及时。

3. 出现 EACCES 权限错误

不建议简单地长期使用管理员权限运行所有 NPM 命令。可以：

1. 检查目标目录权限。
2. 使用 Node.js 版本管理工具。
3. 调整全局软件包安装目录。
4. 尽量使用项目本地依赖和 npx。

4. 出现 ERESOLVE 依赖冲突

先查看错误信息，确认哪些软件包要求了不兼容的版本。

可使用：

npm explain <包名>
npm list <包名>

临时兼容旧项目时可能会看到：

npm install --legacy-peer-deps

但更好的长期解决方式是升级或调整冲突的软件包版本。

5. package.json 和 package-lock.json 不一致

在日常开发环境中执行：

npm install

NPM 会重新解析依赖并更新锁文件。

在 CI 环境中，npm ci 会因为不一致而失败，这可以帮助及时发现未提交的锁文件变化。

6. 安装后项目仍无法运行

可以依次检查：

node -v
npm -v
npm list --depth=0
npm run
npm run build

同时确认：

• Node.js 版本是否符合 engines 要求。
• 环境变量是否配置完整。
• 是否在正确的项目目录中运行命令。
• 安装过程中是否出现错误或警告。

---

二十八、NPM 使用建议

1. 将 package-lock.json 提交到 Git，保证团队依赖版本一致。
2. 不要提交 node_modules，依赖应通过 NPM 重新安装。
3. 应用项目设置 "private": true，防止误发布。
4. 区分生产依赖和开发依赖，保持配置清晰。
5. 定期运行 npm outdated 和 npm audit，关注依赖更新与安全问题。
6. 升级主版本前阅读更新日志，避免不兼容修改影响项目。
7. CI/CD 环境优先使用 npm ci，提高构建一致性。
8. 优先使用项目本地依赖，减少不同开发环境之间的版本差异。
9. 不要把访问令牌提交到 Git，敏感信息应使用环境变量或安全的密钥管理系统。
10. 安装陌生软件包前进行检查，关注包名、维护者、下载量、发布时间和源代码仓库。

---

二十九、常用命令速查表

命令	作用
npm -v	查看 NPM 版本
npm init	交互式初始化项目
npm init -y	使用默认配置初始化项目
npm install	安装项目全部依赖
npm ci	严格按照锁文件安装依赖
npm install <包名>	安装生产依赖
npm install <包名> -D	安装开发依赖
npm install -g <包名>	全局安装软件包
npm uninstall <包名>	卸载依赖
npm update	更新版本范围内的依赖
npm outdated	检查过期依赖
npm list --depth=0	查看顶层依赖
npm view <包名>	查看软件包信息
npm explain <包名>	查看软件包被安装的原因
npm run <脚本>	运行 package.json 脚本
npm run	查看可用脚本
npm audit	检查已知依赖漏洞
npm audit fix	修复兼容范围内的漏洞
npm cache verify	检查缓存完整性
npm config list	查看 NPM 配置
npm config get registry	查看当前 Registry
npm login	登录 NPM 账户
npm whoami	查看当前登录用户
npm pack --dry-run	预览软件包发布内容
npm publish	发布软件包
npm version patch	更新修订版本号
npx <命令>	运行软件包提供的命令

---

三十、推荐学习路线

第一阶段：掌握基础操作

重点学习：

npm init -y
npm install
npm install <包名>
npm uninstall <包名>
npm run <脚本>

第二阶段：理解项目配置

重点理解：

• package.json
• package-lock.json
• node_modules
• dependencies
• devDependencies
• 语义化版本

第三阶段：掌握项目维护

重点学习：

npm outdated
npm update
npm audit
npm explain
npm ci

第四阶段：学习包开发与发布

重点学习：

• 软件包入口和导出配置
• files 和 .npmignore
• npm pack --dry-run
• 语义化版本管理
• npm publish
• NPM Workspaces

---

总结

NPM 不只是一个依赖安装工具，它还承担着项目初始化、版本管理、脚本执行、安全检查和软件包发布等工作。

日常开发中最常用的命令包括：

npm init -y
npm install
npm install <包名>
npm install <包名> -D
npm uninstall <包名>
npm run dev
npm run build
npm outdated
npm audit
npm ci

学习 NPM 的关键并不是记住所有命令，而是理解 package.json、package-lock.json 和 node_modules 之间的关系，并学会正确管理依赖版本。掌握这些基础后，无论是开发前端项目、Node.js 服务，还是发布自己的软件包，都会更加轻松。