NPM 安装完全指南：从入门到精通

第一部分基础入门篇第一章认识 NPM1.1 什么是 NPMNPMNode Package Manager是 Node.js 的默认包管理器。它不仅仅是人们常说的“依赖安装工具”更是世界上最大的开源软件注册表拥有超过数百万个包Package。核心功能安装与卸载轻松安装或移除项目所需的第三方代码。版本管理精确控制项目依赖的版本避免因版本更新导致的项目崩溃。脚本运行通过npm scripts自动化构建、测试、启动等任务。包发布将自己写的模块发布到 NPM 仓库供全世界开发者使用。1.2 安装 Node.js 和 NPMNPM 是随 Node.js 一起分发的因此安装 Node.js 是第一步。下载与安装访问 Node.js 官网下载 LTS长期支持版安装包根据操作系统指引进行安装。验证安装打开终端Terminal或命令提示符CMD输入以下命令检查版本号bashnode -v # 输出示例v18.17.0 npm -v # 输出示例9.6.7如果能看到版本号说明安装成功。第二章项目初始化与第一个包2.1 初始化项目npm init每个使用 NPM 管理的项目都需要一个package.json文件它是项目的“身份证”和配置清单。交互式创建bashnpm init根据提示输入项目名称、版本、描述、入口文件等信息。快速创建默认值bashnpm init -y或者bashnpm init --force这会直接生成一个包含默认配置的package.json文件。2.2 安装第一个包npm install本地安装将包下载到当前项目根目录下的node_modules文件夹中。bashnpm install lodash这会将 lodash 安装并自动记录到package.json的dependencies字段中。安装开发依赖有些包只在开发时使用如测试框架 Jest、代码格式化工具 Prettier不会在生产环境运行。bashnpm install --save-dev jest # 或简写 npm i -D jest这会将包记录到devDependencies字段。全局安装如果你需要的是一个命令行工具如create-react-app而不是项目代码依赖可以全局安装。bashnpm install -g create-react-app全局安装的包通常存放在系统的特定目录如/usr/local/lib/node_modules或C:\Users\用户名\AppData\Roaming\npm\node_modules不会在某个具体项目的node_modules中。第三章理解项目结构3.1node_modules这是存放所有已安装包的文件夹。由于体积巨大且可以通过package.json重建此文件夹永远不会被提交到 Git 仓库需要在.gitignore中忽略它。3.2package.json项目的核心配置文件。它包含了项目元数据名称、版本、作者等以及依赖列表。json{ name: my-project, version: 1.0.0, description: 一个示例项目, main: index.js, scripts: { test: echo \Error: no test specified\ exit 1 }, dependencies: { lodash: ^4.17.21 }, devDependencies: { jest: ^29.0.0 } }3.3package-lock.json这是一个自动生成的文件。它精确记录了node_modules中每一个包的来源、版本号以及依赖树结构。它的作用是锁定依赖确保团队中每个人以及 CI/CD 服务器安装的依赖版本完全一致。重要必须将此文件提交到 Git 仓库。第二部分核心概念与进阶操作篇第四章深入依赖管理4.1 语义化版本控制SemVerNPM 中的版本号遵循主版本号.次版本号.修订号的规则 主版本号当做了不兼容的 API 修改。次版本号当做了向下兼容的功能性新增。修订号当做了向下兼容的问题修正。在package.json中我们通常使用符号来指定可接受的版本范围符号示例含义^^1.2.3允许次版本号和修订号变更。只要主版本号是1最新版是1.x.x就可以即锁定最左边第一个非零版本。~~1.2.3只允许修订号变更。只要主次版本是1.2.x就可以。无1.2.3精确版本。必须安装1.2.3。******安装最新版本。1.2.3 2.0.0指定范围。4.2 安装特定版本bashnpm install lodash4.17.20 # 安装指定版本 npm install lodash^4.0.0 # 安装符合范围的最新版 npm install lodashlatest # 安装 latest 标签指向的版本4.3 依赖类型详解在package.json中依赖可以存放在不同的字段中dependencies生产依赖。项目运行必需的包如 React, Vue, Express。devDependencies开发依赖。开发过程中需要的工具如 Webpack, Babel, ESLint。peerDependencies对等依赖。通常用于开发插件或库时提示宿主环境需要安装哪些核心包。例如一个 Vue 插件需要宿主项目有 Vue 才能工作。optionalDependencies可选依赖。即使安装失败NPM 也认为整个安装过程是成功的。如果程序能优雅地处理缺失情况可以使用。bundledDependencies打包依赖。在发布包时会一起打包进去的依赖数组。第五章NPM Scripts 自动化scripts字段是package.json中最强大的功能之一它允许你定义和运行自定义脚本命令。5.1 基本用法json{ scripts: { start: node server.js, build: webpack --mode production, dev: webpack serve --mode development, lint: eslint src/ } }执行脚本bashnpm run dev npm run build # 对于 start 和 test 等常用命令可以省略 run npm start npm test5.2 脚本钩子HooksNPM 会自动执行带有特定前缀的脚本 pre钩子在指定命令之前运行。post钩子在指定命令之后运行。示例json{ scripts: { prebuild: rimraf dist, build: webpack --mode production, postbuild: echo 构建完成 } }运行npm run build时三个命令会依次执行。5.3 环境变量在 Script 中可以访问package.json中的字段作为环境变量。例如npm_package_version代表当前版本号。在 Script 中可以使用$npm_package_versionMac/Linux或%npm_package_version%Windows来获取版本号。第六章深入理解package-lock.json6.1 为什么需要 Lock 文件假设项目依赖lodash在package.json中写的是^4.17.20。当团队成员在不同时间运行npm install时开发者 A 今天安装lodash 最新版本是4.17.21。开发者 B 下个月安装lodash 发布了4.17.22包含一个小 bug 修复。由于^允许更新次版本两人安装的实际版本可能不同导致“在我电脑上是好的”问题。package-lock.json就是为了解决这个问题。它锁定了当时安装的确切版本和整个依赖树。6.2npm install与npm cinpm install如果有package-lock.json会对比package.json。如果 lock 中的版本满足package.json的范围则使用 lock 中的版本如果不满足会更新 lock 文件。会检查并安装可能缺失的包。npm ci专为 CI持续集成环境设计。必须存在package-lock.json否则会报错。严格根据 lock 文件安装不会修改 lock 文件。会删除现有的node_modules文件夹然后重新安装确保绝对的干净和确定性。速度通常比npm install快。结论本地开发用npm installCI/CD 流水线上永远用npm ci。第七章NPM 配置与镜像7.1 NPM 配置文件.npmrcNPM 的行为可以通过配置文件进行修改。配置层级从高到低为项目级项目根目录下的.npmrc。用户级~/.npmrc用户主目录下。全局级$PREFIX/etc/npmrc。内置NPM 自带的配置。查看当前配置bashnpm config list7.2 配置镜像源Registry在中国大陆直接连接 NPM 官方源https://registry.npmjs.org/通常速度很慢可以切换至淘宝镜像源。临时使用bashnpm install lodash --registryhttps://registry.npmmirror.com永久设置bashnpm config set registry https://registry.npmmirror.com使用工具管理可以使用nrm(NPM Registry Manager) 轻松切换源。bashnpm install -g nrm npx nrm ls # 列出所有源 npx nrm use taobao # 使用淘宝源 npx nrm use npm # 切回官方源第三部分高级技巧与工程化篇第八章高级安装与调试8.1 安装非 Registry 包NPM 不仅能从 Registry 安装还能从多种来源安装从 Git 仓库安装bash# 直接从 GitHub 主分支安装 npm install github:username/repo # 或指定 commit id 或 tag npm install githttps://github.com/username/repo.git#v1.0.0 npm install gitssh://gitgithub.com:username/repo.git#develop从本地文件系统安装bash# 安装本地压缩包 npm install ./path/to/package.tgz # 创建符号链接到本地包用于调试 npm link ../my-local-package安装别名包允许在同一项目中安装同一个包的不同版本或给长名字包起别名。bashnpm install jquery2npm:jquery2 npm install jquery3npm:jquery3 npm install my-reactnpm:react8.2 排查依赖问题npm explain当你想知道为什么某个包会被安装或者是谁依赖了它时bashnpm explain lodash # 输出lodash4.17.21 # 作用devDependencies中的项目依赖了它 # 也有来自 webpack - babel 的间接依赖8.3 本地调试npm link当你在开发一个库比如my-ui-lib并想在另一个本地项目比如my-app中实时测试修改时npm link非常有用。在库项目my-ui-lib中bashcd my-ui-lib npm link这会在全局node_modules中创建一个指向my-ui-lib的符号链接。在应用项目my-app中bashcd my-app npm link my-ui-lib这会在my-app的node_modules中创建一个指向全局链接的符号链接。修改my-ui-lib的代码my-app中会立即生效需支持热更新。解除链接bashcd my-app npm unlink --no-save my-ui-lib cd ../my-ui-lib npm unlink第九章安全与维护9.1 安全审计npm audit随着项目依赖增多安全问题不容忽视。检查漏洞bashnpm audit自动修复bashnpm audit fix它会尝试自动更新到兼容的、修复了漏洞的版本。如果不行可以用npm audit fix --force强制升级可能需要手动测试破坏性变更。9.2 检查过期依赖npm outdated查看哪些包有新版本发布bashnpm outdated它会列出当前版本Current、想要版本Wanted符合package.json范围的最新版和最新版本Latest。9.3 更新依赖小版本更新bashnpm update lodash这会在满足package.json范围的前提下更新到最新版并更新package-lock.json。大版本更新需要手动安装bashnpm install lodashlatest第十章发布自己的 NPM 包10.1 准备工作注册账号在 npmjs.com 注册。登录在终端登录。bashnpm login输入用户名、密码和邮箱。10.2 创建并发布创建项目bashmkdir my-awesome-lib cd my-awesome-lib npm init -y编写代码例如index.jsjavascriptmodule.exports function() { console.log(Hello from my awesome lib!); };添加.npmignore类似于.gitignore用于指定哪些文件不发布。如果不写NPM 会使用.gitignore的规则。发布bashnpm publish10.3 管理版本发布新版本前必须更新版本号。bashnpm version patch # 1.0.0 - 1.0.1 (修复 bug) npm version minor # 1.0.1 - 1.1.0 (新增功能) npm version major # 1.1.0 - 2.0.0 (破坏性变更) npm publish10.4 作用域包与私有包作用域包格式为username/package-name。默认是公开的。bashnpm init --scopeusername npm publish --access public私有包需要付费账户发布时指定访问权限。bashnpm publish --access restricted第十一章NPM 生态系统与替代工具11.1 NPM 与 Yarn 对比Yarn 是 Facebook 推出的另一款包管理器与 NPM 类似但有自己的特点特性NPMYarn锁文件package-lock.jsonyarn.lock安装速度较慢现 v7 有改进较快并行安装Workspaces支持v7原生支持良好命令npm installyarn add11.2 新兴工具pnpm核心原理使用内容可寻址存储。如果你有 10 个项目都依赖同一个版本的lodashpnpm只在全局存储一份然后通过硬链接的方式引入项目。这极大地节省了磁盘空间并且安装速度飞快。11.3 极速工具Bun特点Bun 不仅仅是一个包管理器还是一个 JavaScript 运行时类似于 Node.js、打包器、测试运行器。它由 Zig 语言编写启动速度和安装速度都非常快。第四部分最佳实践与排错指南第十二章工程化最佳实践12.1 依赖管理精确控制对于核心依赖建议使用精确版本--save-exact或认真对待^和~的选择。bashnpm install react --save-exact最小化依赖引入一个包前思考能否用几行代码自己实现依赖越多安全风险和安装体积越大。定期维护养成习惯每月或每季度运行一次npm outdated和npm audit保持项目健康。12.2 Lock 文件策略务必提交package-lock.json必须提交到 Git。这是团队协作和生产环境构建稳定性的基石。解决冲突当package-lock.json在合并分支时发生冲突最简单的方法是重新生成bash# 接受所有更改然后重新安装 git checkout --ours package.json # 或者 --theirs npm install12.3 环境隔离避免全局安装尽量不要全局安装项目依赖。团队中如果有人忘记全局安装某个工具项目就会运行失败。项目依赖都应写在devDependencies中并通过npx运行。npx会先查找项目node_modules中的命令找不到再去全局找。例如npx webpack --version会优先使用项目中的 webpack。第十三章常见错误与解决方案13.1 安装慢或卡住原因访问官方源网络不稳定。解决切换淘宝镜像源 。bashnpm config set registry https://registry.npmmirror.com13.2 权限错误EACCES原因在 Linux/Mac 上试图用普通用户权限全局安装包。解决推荐使用 Node 版本管理器如nvm重装 Node它会将全局路径设在用户目录下。不推荐使用sudo npm install -g package可能带来安全问题。手动修改 npm 全局目录权限。13.3 依赖版本冲突ERESOLVE原因项目中不同包依赖了同一个包但版本不兼容。NPM v7 对peerDependencies的检查更严格会报错。解决使用--legacy-peer-deps命令降级到 v6 的处理方式忽略对等依赖冲突作为临时方案。更根本的解决分析依赖树npm explain package手动安装一个能兼容的版本或升级/降级相关依赖。13.4 幽灵依赖Phantom Dependency原因你引用了package.json中没有声明的包但它存在于node_modules中因为它是其他包依赖的。当那个包升级去掉了该依赖时你的代码就会报错。解决使用包管理器的最新特性如 pnpm 的严格模式。使用工具如dependency-cruiser检查项目中是否有未声明的依赖。第十四章总结NPM 已经从一个简单的包安装器演变成了现代 JavaScript 开发的核心基础设施。掌握 NPM 不仅仅是记住npm install而是理解其依赖解析算法、版本控制哲学以及它在工程化流程中的定位。