npm 使用详细指南（2026 最新版）
一、npm 概述
npm（Node Package Manager）是 Node.js 的默认包管理器，也是全球最大的 JavaScript 软件注册中心（Registry）。它由三部分组成：
- 网站（npmjs.com）：开发者查找、分享和管理包的主要平台；
- 命令行工具（CLI）：通过终端运行，实现包的下载、安装、发布等操作；
- 注册表（Registry）：存储海量 JavaScript 包的数据库，记录了每个包的版本、依赖等信息。
npm 的核心用途包括：依赖管理 （安装/卸载第三方库）、脚本运行 （通过 npm run 执行构建/测试等任务）、包发布 （将自己的代码分享到社区）、安全审计（检测依赖中的漏洞）等。
二、安装与配置
1. 安装 Node.js（含 npm）
npm 随 Node.js 一起安装，因此只需安装 Node.js 即可。推荐使用 nvm（Node Version Manager） 管理 Node.js 版本（支持 Windows、macOS、Linux），避免权限问题和多版本冲突。
- 安装 nvm：https://github.com/nvm-sh/nvm；
- 通过 nvm 安装 Node.js：
nvm install 20（安装 Node.js 20.x LTS 版本，自带 npm v10.8.2+）。
2. 验证安装
安装完成后，打开终端运行以下命令，确认 Node.js 和 npm 版本：
bash
node -v # 输出 Node.js 版本（如 v20.19.0）
npm -v # 输出 npm 版本（如 v11.7.0）若未显示版本，需检查 Node.js 安装路径是否添加到系统环境变量。
3. 配置国内镜像源（中国大陆用户）
npm 官方源（https://registry.npmjs.org/）在国内访问较慢，建议切换至国内镜像源：
- 淘宝镜像 （推荐）：
npm config set registry https://registry.npmmirror.com； - 华为云镜像 ：
npm config set registry https://repo.huaweicloud.com/repository/npm/； - 腾讯云镜像 ：
npm config set registry https://mirrors.cloud.tencent.com/npm/。
验证镜像源是否生效：npm config get registry（输出设置的镜像地址）。
三、基础命令
1. 初始化项目
使用 npm init 创建 package.json 文件（记录项目依赖、脚本等信息）：
bash
npm init # 交互式创建，需手动输入项目名称、版本、描述等；
npm init -y # 快速创建，使用默认值（推荐）。package.json 的核心字段：
name：项目名称（必填）；version：项目版本（必填，遵循语义化版本控制 SemVer）；dependencies：生产环境依赖（如react、lodash）；devDependencies：开发环境依赖（如typescript、webpack）。
2. 安装依赖
- 生产依赖 （项目运行时需要）：
npm install <包名>（简写npm i <包名>）；
例：npm install react（安装 React 到dependencies）。 - 开发依赖 （仅开发时需要）：
npm install <包名> --save-dev（简写npm i <包名> -D）；
例：npm install typescript -D（安装 TypeScript 到devDependencies）。 - 全局安装 （工具类包，如脚手架）：
npm install <包名> -g；
例：npm install @vue/cli -g（全局安装 Vue CLI）。 - 指定版本 ：
npm install <包名>@<版本号>；
例：npm install lodash@4.17.21（安装 Lodash 4.17.21 版本）。
3. 卸载依赖
- 生产依赖 ：
npm uninstall <包名>； - 开发依赖 ：
npm uninstall <包名> -D； - 全局依赖 ：
npm uninstall <包名> -g。
4. 运行脚本
package.json 中的 scripts 字段定义了可运行的脚本，通过 npm run <脚本名> 执行：
json
{
"scripts": {
"start": "node server.js", // 启动项目
"build": "webpack --mode production", // 打包项目
"test": "jest" // 运行测试
}
}常用脚本：
npm start：默认执行start脚本（可省略run）；npm run build：执行build脚本；npm test：执行test脚本（可省略run）。
5. 其他常用命令
npm list：显示当前项目的依赖树（加-g显示全局依赖）；npm outdated：检查过时的依赖包；npm update <包名>：更新指定依赖到最新兼容版本；npm cache clean --force：清除 npm 缓存（解决安装卡顿/报错）；npm root -g：显示全局node_modules目录路径。
四、依赖管理
1. 锁定依赖版本
package-lock.json 文件用于锁定依赖的精确版本，确保团队成员和 CI 环境安装的依赖一致。必须提交到 Git 仓库，避免不同机器安装版本差异导致的问题。
2. 精准安装（CI 环境推荐）
使用 npm ci 替代 npm install，它会严格按照 package-lock.json 安装依赖，速度更快且不修改 package-lock.json，适合持续集成（CI）环境。
3. 安全审计
定期运行 npm audit 扫描项目中的安全漏洞，并使用 npm audit fix 自动修复：
bash
npm audit # 检查漏洞
npm audit fix # 修复可自动解决的漏洞五、发布自己的包
1. 准备工作
- 注册 npm 账号：https://www.npmjs.com/signup；
- 登录 npm：
npm login（输入用户名、密码、邮箱）； - 确保包名未被占用（可通过
npm search <包名>检查）。
2. 创建包
-
新建文件夹，初始化项目：
npm init -y； -
编写代码（如
index.js）：javascriptmodule.exports = function add(a, b) { return a + b; };
3. 发布包
运行以下命令发布包：
bash
npm publish- 若包名包含作用域（如
@username/package），需使用--access public公开包：npm publish --access public； - 发布后，可在 npmjs.com 搜索到自己的包。
4. 更新版本
修改代码后，更新 package.json 中的 version 字段（遵循 SemVer 规则：主版本.次版本.补丁版本），然后重新发布：
bash
npm version patch # 升级补丁版本（如 1.0.0 → 1.0.1）
npm publish # 发布新版本六、高级技巧
1. 使用 .npmrc 配置文件
.npmrc 文件用于存储 npm 配置（如镜像源、代理等），优先级高于命令行参数。
- 全局配置（用户根目录）：
~/.npmrc（Windows 为C:\Users\<用户名>\.npmrc）； - 项目配置（项目根目录）：
.npmrc（仅对当前项目生效）。
例：设置淘宝镜像源到项目配置：
ini
registry=https://registry.npmmirror.com2. 全局配置管理
使用 npm config 命令管理配置：
- 设置配置：
npm config set <key> <value>（如npm config set registry https://registry.npmmirror.com）； - 获取配置：
npm config get <key>（如npm config get registry）； - 删除配置：
npm config delete <key>。
3. 离线模式与缓存
- 离线安装：使用
--offline参数，仅使用本地缓存安装依赖：npm install --offline； - 查看缓存：
npm cache ls； - 清理缓存：
npm cache clean --force（解决安装卡顿/报错）。
4. 本地包调试
使用 npm link 将本地包链接到全局，方便在其他项目中调试：
- 在本地包目录运行：
npm link（将包链接到全局node_modules）； - 在目标项目运行：
npm link <包名>（将全局链接的包关联到项目的node_modules）。
七、最佳实践
- 不要频繁全局安装 ：尽量将工具类包作为开发依赖（
-D），或使用npx临时运行（如npx create-react-app my-app）； - 保留
package-lock.json：确保团队协作和 CI 环境的依赖一致性； - 定期安全审计 ：使用
npm audit检查漏洞，及时修复； - 使用语义化版本控制 ：遵循 SemVer 规则（
MAJOR.MINOR.PATCH），避免随意升级主版本； - 使用 nvm 管理 Node.js 版本：避免权限问题和多版本冲突。
八、常见问题解决
1. 权限错误（EACCES）
- 原因：全局安装时，npm 默认目录没有写入权限（常见于 macOS/Linux）；
- 解决方法 ：
- 使用 nvm 安装 Node.js（推荐）；
- 修复 npm 默认目录权限：
sudo chown -R $USER:$GROUP ~/.npm； - 避免使用
sudo npm（会导致更多权限问题）。
2. 依赖冲突（ERESOLVE）
- 原因：不同包的依赖版本不兼容；
- 解决方法 ：
- 使用
npm install --legacy-peer-deps忽略 peer 依赖冲突（临时解决）； - 调整依赖版本，确保兼容性（如升级或降级冲突的包）。
- 使用
3. 找不到全局包
- 原因：全局安装路径未添加到系统环境变量；
- 解决方法 ：
- 查看全局安装路径：
npm root -g（如/usr/local/lib/node_modules）； - 将该路径添加到系统环境变量（如 macOS/Linux 的
~/.bash_profile或~/.zshrc）。
- 查看全局安装路径：
九、参考资源
- npm 官方文档：https://docs.npmjs.com；
- npm 官方网站：https://www.npmjs.com；
- nvm 官方文档：https://github.com/nvm-sh/nvm；
- 淘宝 npm 镜像：https://registry.npmmirror.com。
以上是 npm 的详细使用指南，覆盖了从基础到高级的所有核心内容。遵循这些步骤和最佳实践，可帮助你高效地管理项目依赖、发布包，并避免常见问题。如需更深入的信息，建议参考 npm 官方文档或社区资源。