npm 依赖管理机制完全解析（超详细版）

本指南将从底层原理到实战细节，完全剖析 npm 如何处理项目依赖。你将理解 package.json 版本约束、依赖树构建、锁文件机制、peerDependencies 演进、依赖覆盖、去重优化等内容，并通过大量示例加深理解。

---

目录

1. 为什么需要依赖管理
2. [依赖类型与 package.json](#依赖类型与 package.json "#2-%E4%BE%9D%E8%B5%96%E7%B1%BB%E5%9E%8B%E4%B8%8E-packagejson")
3. 语义化版本（Semver）完全指南
4. 依赖解析与依赖树
5. [版本锁定：package-lock.json 深度解析](#版本锁定：package-lock.json 深度解析 "#5-%E7%89%88%E6%9C%AC%E9%94%81%E5%AE%9Apackage-lockjson-%E6%B7%B1%E5%BA%A6%E8%A7%A3%E6%9E%90")
6. [npm install 安装过程详解](#npm install 安装过程详解 "#6-npm-install-%E5%AE%89%E8%A3%85%E8%BF%87%E7%A8%8B%E8%AF%A6%E8%A7%A3")
7. [依赖冲突与 Peer Dependencies](#依赖冲突与 Peer Dependencies "#7-%E4%BE%9D%E8%B5%96%E5%86%B2%E7%AA%81%E4%B8%8E-peer-dependencies")
8. 依赖覆盖与替换：overrides
9. [依赖去重：npm dedupe 原理与实践](#依赖去重：npm dedupe 原理与实践 "#9-%E4%BE%9D%E8%B5%96%E5%8E%BB%E9%87%8Dnpm-dedupe-%E5%8E%9F%E7%90%86%E4%B8%8E%E5%AE%9E%E8%B7%B5")
10. 依赖更新策略
11. 依赖审查与调试
12. [工作区（Workspaces）管理 Monorepo](#工作区（Workspaces）管理 Monorepo "#12-%E5%B7%A5%E4%BD%9C%E5%8C%BAworkspaces-%E7%AE%A1%E7%90%86-monorepo")
13. 安装选项与高级技巧
14. 离线缓存机制
15. 镜像源与私有包
16. 总结与最佳实践

---

1. 为什么需要依赖管理

在现代 JavaScript 开发中，一个项目通常会依赖数十甚至数百个第三方包。每个包可能又依赖其他包（传递依赖）。依赖管理需要解决：

• 版本兼容性：不同包要求的版本范围可能冲突。
• 重复安装：同一个包被多个依赖引用时，需要决定是复用还是多份。
• 可重现构建：团队成员和生产环境必须得到完全相同的依赖树。

npm 通过 package.json + 版本范围 + package-lock.json + 扁平的 node_modules 来解决这些问题。

---

2. 依赖类型与 package.json

package.json 中定义了五种依赖类型，它们决定了依赖在何种环境下被安装和使用。

2.1 dependencies -- 生产依赖

项目运行时必需的依赖，例如 express、react。

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "~4.17.21"
  }
}

安装命令：

npm install express        # 默认保存到 dependencies
npm install lodash --save-prod   # 显式指定

2.2 devDependencies -- 开发依赖

仅在开发、测试、构建时需要，例如 jest、webpack、eslint。

{
  "devDependencies": {
    "jest": "^29.0.0",
    "nodemon": "^2.0.0"
  }
}

安装命令：

npm install jest --save-dev   # 或 -D

生产环境跳过：

npm install --only=production
# 或 npm ci --only=production

2.3 peerDependencies -- 对等依赖

用于插件或库，要求宿主项目提供某个依赖。例如 react 插件要求宿主已安装 react。

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

• npm v7+ 默认会自动安装 peer 依赖（如果宿主缺失）。
• npm v3~v6 只会警告，不会安装。

示例 ：编写一个 React Hook 库 my-hooks

{
  "name": "my-hooks",
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

当其他项目运行 npm install my-hooks 时，如果没有安装 react，npm v7+ 会自动安装 react。

2.4 optionalDependencies -- 可选依赖

如果某个依赖安装失败（如平台不支持），npm 会忽略错误，继续安装过程。常用于 fsevents（macOS 专用）。

{
  "optionalDependencies": {
    "fsevents": "^2.3.2"
  }
}

安装：与普通依赖相同，但失败不报错。

npm install fsevents --save-optional   # -O

检查可选依赖是否可用：

try {
  require('fsevents');
} catch (err) {
  // 可选依赖未安装或失败
}

2.5 bundledDependencies -- 打包依赖

发布包时，将依赖的代码一并打包进最终的 tarball。用户安装时无需再从网络下载这些依赖。

{
  "bundledDependencies": ["my-private-dep"]
}

注意 ：bundledDependencies 中的包必须同时出现在 dependencies 或 devDependencies 中。

---

3. 语义化版本（Semver）完全指南

npm 使用 Semver 2.0.0 规范：MAJOR.MINOR.PATCH

变化类型	说明	例子
PATCH	向下兼容的 bug 修复	1.0.0 → 1.0.1
MINOR	向下兼容的新功能	1.0.0 → 1.1.0
MAJOR	不向下兼容的 API 变更	1.0.0 → 2.0.0

3.1 版本范围符号

在 package.json 中声明依赖时，可以指定一个范围，npm 会在范围内选择最高版本安装。

| 符号 | 含义 | 示例 | 允许安装的范围 |
|-----------------------------|------------------------------|-----------------------|--------------------------------------------------------------------------|------------|---|------------|-----------|
| 无符号 | 精确版本（极少用） | "lodash": "4.17.21" | 只有 4.17.21 |
| ^ | 兼容的 major 版本（不修改最左边非零数字） | ^1.2.3 | >=1.2.3 <2.0.0 ^0.2.3 → >=0.2.3 <0.3.0 ^0.0.3 → >=0.0.3 <0.0.4 |
| ~ | 允许 patch 版本更新 | ~1.2.3 | >=1.2.3 <1.3.0 ~1.2 → >=1.2.0 <1.3.0 ~1 → >=1.0.0 <2.0.0 |
| > / < / >= / <= | 比较符 | ">=1.2.3 <2.0.0" | 1.2.3 到 2.0.0 之前 |
| - | 范围 | 1.2.3 - 2.3.4 | >=1.2.3 <=2.3.4 |
| **` | | `** | 或 | `"^1.0.0 | | ^2.0.0"` | 1.x 或 2.x |
| 通配符 x / * | 任意版本 | 1.2.x | 1.2.0, 1.2.1, ... * 表示所有版本 |
| 预发布标签 | -alpha, -beta | ^1.0.0-beta | 包含预发布版本，但只有明确带标记才会匹配 |

3.2 实际案例

{
  "dependencies": {
    "a": "^1.0.0",        // 接受 1.0.0, 1.2.3, 但不接受 2.0.0
    "b": "~2.3.0",        // 接受 2.3.0, 2.3.5, 但不接受 2.4.0
    "c": ">=3.0.0 <4.0.0",// 接受 3.x 任一版本
    "d": "4.5.x",         // 接受 4.5.0, 4.5.1, ...
    "e": "5.*",           // 接受 5.0.0 及以上直到 6.0.0 前
    "f": "*",             // 接受任何版本（非常危险，不推荐）
    "g": "1.2.3 - 2.3.4", // 接受 1.2.3 到 2.3.4 之间的版本
    "h": "^1.2.3-beta.0"  // 接受 >=1.2.3-beta.0 <2.0.0，包括预发布
  }
}

3.3 锁定精确版本（不推荐手动）

# 安装时生成精确版本（无前缀）
npm install lodash --save-exact
npm install lodash -E

3.4 npm config 设置默认版本前缀

# 全局设置保存时的前缀为 ~ 而不是 ^
npm config set save-prefix "~"

# 恢复
npm config set save-prefix "^"

---

4. 依赖解析与依赖树

4.1 npm v2 的嵌套结构（已废弃）

每个依赖都有自己的 node_modules，形成深层树。例如：

node_modules/
├─ A@1.0.0
│  └─ node_modules/
│     └─ C@2.0.0
└─ B@1.0.0
   └─ node_modules/
      └─ C@2.0.0    # C 被重复安装两次

问题：磁盘空间浪费，路径过长（Windows 报错）。

4.2 npm v3+ 的扁平化策略

npm 会尽可能将所有依赖提升到顶层 node_modules，只有当版本冲突时才嵌套安装。

原则：

• 遍历所有依赖，尝试把每个包放在顶层。
• 如果同一个包的不同版本被需要，只有一个版本可占顶层，其他版本嵌套在需要它的父包下。

示例 ： 项目依赖 A@1.0.0 和 B@1.0.0，而 A 依赖 C@1.0.0，B 依赖 C@2.0.0。

node_modules/
├─ A@1.0.0
├─ B@1.0.0
├─ C@1.0.0          # 提升到顶层（最先遇到的版本）
└─ node_modules/
   └─ B/            # B 需要 C@2.0.0，但顶层已是 1.0.0，冲突
      └─ node_modules/
         └─ C@2.0.0 # 嵌套安装

决定哪个版本在顶层？

取决于安装顺序。项目使用的版本范围解析后，第一个被遍历到的版本占据顶层。但 package-lock.json 会锁定最终树结构。

4.3 使用 npm list 查看依赖树

# 显示完整树
npm list

# 只显示直接依赖
npm list --depth=0

# 查看某个包的解析结果
npm list lodash

输出示例：

my-app@1.0.0
├─┬ express@4.18.2
│ └── accepts@1.3.8
├── lodash@4.17.21
└─┬ webpack@5.88.0
  └─┬ webpack-cli@5.1.0
    └── commander@10.0.0

4.4 确定性安装与 package-lock.json

由于扁平化依赖树的构建依赖于安装顺序，不同环境可能得到不同的树结构。package-lock.json 锁定了整个依赖树的确切版本和结构，保证每次安装一致。

---

5. 版本锁定：package-lock.json 深度解析

5.1 作用和结构

package-lock.json 记录了：

• 每个依赖包的精确版本。
• 依赖的下载地址（resolved）。
• 包的完整性哈希（integrity，用于校验）。
• 依赖树结构（requires 字段描述模块关系）。

示例片段：

{
  "name": "my-app",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "node_modules/express": {
      "version": "4.18.2",
      "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
      "integrity": "sha512-...",
      "dependencies": {
        "accepts": "~1.3.8",
        "body-parser": "1.20.1"
      }
    },
    "node_modules/accepts": {
      "version": "1.3.8",
      "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz",
      "integrity": "sha512-...",
      "peerDependencies": {}
    }
  }
}

5.2 何时生成/更新

• 首次运行 npm install 时生成。
• 每次添加/更新/删除依赖时，package-lock.json 会自动更新。
• 手动运行 npm install <pkg> 也会更新。

5.3 npm ci 与 package-lock.json 的关系

npm ci 强制使用 lock 文件，如果 lock 文件与 package.json 版本需求冲突，会报错退出。它适合 CI 环境。

# CI 中确保安装完全一致
npm ci

5.4 npm shrinkwrap 与 package-lock.json 的区别

• npm shrinkwrap 生成 npm-shrinkwrap.json，与 package-lock.json 结构相同。
• 发布包时，npm-shrinkwrap.json 会被包含在 tarball 中，而 package-lock.json 不会被发布（除非根项目）。
• 当两者同时存在，npm-shrinkwrap.json 优先级更高。

# 生成 shrinkwrap
npm shrinkwrap

5.5 最佳实践

• 将 package-lock.json 提交到版本库（Git），确保团队成员和生产环境一致。
• 永远不要手动编辑 lock 文件。
• 如果发生冲突，删除 node_modules 和 package-lock.json 后重新 npm install。

---

6. npm install 安装过程详解

当运行 npm install（无参数）时，npm 执行以下步骤：

步骤 1：读取 package.json 和 lock 文件

• 如果存在 package-lock.json（或 npm-shrinkwrap.json），读取并校验是否与 package.json 的版本范围兼容。
• 若不兼容或 lock 文件不存在，进入依赖解析阶段。

步骤 2：构建依赖树

• 从项目直接依赖开始，递归解析每个包的版本范围。
• 使用仲裁算法 确定每个包的最佳版本：
  • 符合版本范围的最新版。
  • 考虑现有 node_modules 中的包（为了去重）。
• 生成一个理想的依赖树（逻辑树），尚未写入磁盘。

步骤 3：去重与扁平化

• 将逻辑树尽可能扁平化到顶层 node_modules。
• 当版本冲突时，将非主版本嵌套安装到冲突包的父目录下。

步骤 4：下载缺失的包

• 检查本地缓存（~/.npm）中是否有目标 tarball。
• 如果没有，从 registry 下载，并存入缓存。
• 计算完整性哈希，与 lock 文件对比（如果存在）。

步骤 5：提取到 node_modules

• 将 tarball 解压到 node_modules 对应的位置。
• 如果包包含preinstall、install 或 postinstall 脚本，运行它们。

步骤 6：更新 package-lock.json

• 将精确的依赖树和版本信息写入 lock 文件。

示例：详细调试输出

# 查看安装细节
npm install --verbose

# 模拟安装（不实际写入）
npm install --dry-run

特殊安装模式

# 全局安装（包链接到 PATH）
npm install -g nodemon

# 从 git 仓库安装
npm install git+https://github.com/expressjs/express.git

# 从本地 tarball 安装
npm install ./my-package-1.0.0.tgz

# 从本地目录安装（类似 npm link）
npm install ../my-local-lib

---

7. 依赖冲突与 Peer Dependencies

7.1 Peer Dependencies 的历史与问题

在 npm v3~v6 中，peerDependencies 不会自动安装，只会产生警告。例如：

npm WARN my-plugin@1.0.0 requires a peer of react@^17.0.0 but none is installed.

这要求用户手动安装匹配的 React 版本。但如果用户安装了 React 18，而插件只兼容 17，就可能出现运行时错误。

7.2 npm v7+ 的自动安装

从 npm v7 开始，默认行为变为：

• 如果宿主项目缺少 peer 依赖，npm 会自动安装该 peer 依赖。
• 如果已安装的 peer 依赖版本与插件要求的范围不兼容，npm 会报错，阻止安装。

示例：

// my-hooks/package.json
{
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

在宿主项目安装：

npm install my-hooks
# 如果宿主没有 react，npm 会自动安装 react@18.x
# 如果宿主有 react@17，会报错：peer dependency conflict

7.3 冲突解决选项

当出现 peer 依赖冲突时，可以选择：

选项 1：使用 --legacy-peer-deps（恢复旧行为）

npm install --legacy-peer-deps

忽略 peer 冲突，只警告，继续安装。可能导致运行时错误。

选项 2：使用 --force

npm install --force

强制覆盖冲突，极不推荐。

选项 3：手动调整版本

修改 package.json 中的依赖版本以匹配 peer 要求，然后重新安装。

7.4 peerDependenciesMeta 字段

可以标记 peer 依赖为可选：

{
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  }
}

如果宿主没有安装 React，npm 不会报错。

7.5 实际案例分析

场景：创建一个 Vue 3 插件

{
  "name": "vue-plugin",
  "peerDependencies": {
    "vue": "^3.2.0"
  }
}

宿主项目使用 Vue 2：

# 运行安装
npm install vue-plugin
# 报错：vue-plugin@1.0.0 requires vue@^3.2.0 but vue@2.7.0 is present.

解决方案：

1. 升级宿主项目的 Vue 到 3.x，或
2. 使用 --legacy-peer-deps 强制安装（不推荐），或
3. 找兼容 Vue 2 的插件版本。

---

8. 依赖覆盖与替换：overrides

npm 8.3+ 引入 overrides 字段，允许在不修改依赖包代码的情况下，强制覆盖传递依赖的版本。

8.1 基本语法

在 package.json 中：

{
  "overrides": {
    "lodash": "4.17.21",
    "react": {
      "react": "$react"
    },
    "webpack": "^5.0.0",
    "nested-package": {
      "sub-dep": "2.0.0"
    }
  }
}

• 可以覆盖任何深度的依赖。
• 使用 "$" 前缀引用父级版本（避免循环覆盖）。

8.2 使用场景

场景 1：修复间接依赖的安全漏洞

假设 old-package 依赖 lodash@4.17.20（有漏洞），但你不想升级 old-package。

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

运行 npm install 后，项目中无论哪里出现的 lodash 都会被强制设为 4.17.21（只要版本范围兼容，否则报错）。

场景 2：统一依赖版本，避免重复安装

多个包依赖不同版本的 react，你想强制所有用 18.2.0。

{
  "overrides": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

场景 3：覆盖特定路径的依赖

{
  "overrides": {
    "package-a": {
      "sub-package": "2.0.0"
    }
  }
}

只覆盖 package-a 中依赖的 sub-package，不影响其他地方的 sub-package。

8.3 注意事项

• overrides 只影响当前项目，不影响依赖包本身的代码。
• 如果覆盖的版本不满足原始依赖声明的版本范围（例如原始要求 ^2.0.0，你覆盖为 3.0.0），npm 会报错。必须确保覆盖版本在范围内。
• overrides 应在项目根 package.json 使用，子包中无效。

8.4 与 Yarn resolutions 的类比

Yarn 用户熟悉 resolutions，npm 的 overrides 功能类似。

// yarn
{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

---

9. 依赖去重：npm dedupe 原理与实践

即使 npm 已经做了扁平化，但随着后续安装新包，依赖树可能产生冗余 ------同一个包被安装在多个地方（不同版本或相同版本但未提升）。npm dedupe 可重新整理，将兼容的包尽量提升到顶层。

9.1 原理

• 扫描整个依赖树。
• 对于每个包，检查是否存在同一版本的其他实例可以共享。
• 移动子依赖中的包到顶层 node_modules（如果版本允许）。
• 删除冗余的嵌套副本。

9.2 示例

安装前的树：

node_modules/
├─ A@1.0.0
├─ B@1.0.0
└─ C/                # C 是中间包
   └─ node_modules/
      └─ lodash@4.17.21

顶层没有 lodash。但 A 和 B 都依赖 lodash@4.17.21，因此 lodash 可以被提升。

运行：

npm dedupe

结果：

node_modules/
├─ A@1.0.0
├─ B@1.0.0
├─ lodash@4.17.21   # 提升到顶层
└─ C/
   └─ node_modules/   # 空的（lodash 移除）

9.3 何时使用

• 在大量安装和删除依赖后，怀疑 node_modules 体积过大。
• 从旧版 npm 升级项目后，运行一次 npm dedupe 优化。

9.4 与 npm update 的区别

• npm update 升级版本，可能引入新版本。
• npm dedupe 不改变版本，只整理结构，减少重复。

---

10. 依赖更新策略

10.1 安全更新：npm update

只更新到符合 package.json 中版本范围的最新版（不突破 major）。

npm update            # 更新所有依赖
npm update express    # 只更新 express
npm update --depth=1  # 只更新直接依赖

10.2 检查可以升级的包：npm outdated

npm outdated

输出示例：

Package    Current  Wanted  Latest  Location
lodash     4.17.20  4.17.21 4.17.21 my-project
express    4.17.1   4.18.2  4.18.2  my-project
webpack    5.75.0   5.88.0  5.88.0  my-project

10.3 跨 major 版本升级

npm update 不会自动升级到 major 版本。你需要手动修改 package.json 中的版本范围，然后运行 npm install。

# 手动编辑 package.json，将 "express": "^4.17.1" 改为 "^5.0.0"
npm install

或者使用第三方工具 npm-check-updates（ncu）：

npx npm-check-updates -u   # 升级 package.json 中所有版本到 latest
npm install

10.4 锁定 major 版本的策略

• 生产项目 ：应使用 ^ 或 ~ 锁定 major/minor，定期升级并测试。
• 库 ：建议使用 ^，但也要考虑兼容性。

10.5 自动修复漏洞更新

npm audit fix            # 只升级到兼容版本（不突破 major）
npm audit fix --force    # 强制升级到最新（可能破坏兼容性）

---

11. 依赖审查与调试

11.1 查看依赖树：npm ls

npm ls                      # 全部
npm ls --depth=0            # 顶层
npm ls --parseable          # 可解析路径
npm ls --json               # JSON 输出
npm ls --production         # 只看生产依赖
npm ls --dev                # 只看开发依赖

11.2 解释为什么安装了某个包：npm why

npm why lodash

输出：

lodash@4.17.21
node_modules/lodash
  lodash@"^4.17.21" from the root project
  peer lodash@"^4.0.0" from eslint-plugin-lodash@7.4.0
  node_modules/eslint-plugin-lodash
    dev eslint-plugin-lodash@"^7.4.0" from the root project

清晰展示依赖路径。

11.3 安全审计：npm audit

npm audit --json > audit.json

11.4 检查未使用的依赖：depcheck（第三方）

npx depcheck

列出未在代码中引用的依赖和缺失的依赖。

11.5 查看全局安装的包

npm list -g --depth=0

---

12. 工作区（Workspaces）管理 Monorepo

npm 7+ 支持原生 workspaces，用于管理多包仓库（monorepo）。

12.1 配置工作区

在根目录的 package.json 中：

{
  "workspaces": [
    "packages/*",
    "apps/client",
    "apps/server"
  ]
}

12.2 常用命令

# 在所有工作区安装依赖
npm install

# 为特定工作区添加依赖
npm install lodash --workspace=packages/shared

# 在所有工作区执行脚本
npm run test --workspaces

# 在某个工作区执行脚本
npm run build --workspace=apps/client

# 查看工作区结构
npm list --workspaces

12.3 依赖提升

npm 会将工作区之间共用的依赖提升到根 node_modules，减少重复。

示例目录结构：

my-monorepo/
├─ package.json (根，定义 workspaces)
├─ packages/
│  ├─ shared/
│  │  └─ package.json
│  └─ ui/
│     └─ package.json

根 package.json 可以包含 dependencies，会被所有工作区共享。

12.4 工作区版本链接

当一个工作区依赖另一个工作区时，npm 会自动使用软链接指向本地包。

// packages/ui/package.json
{
  "dependencies": {
    "shared": "1.0.0"   // 会链接到 packages/shared
  }
}

---

13. 安装选项与高级技巧

13.1 --save-exact (-E)

安装精确版本，不加前缀。

npm install lodash -E   # package.json: "lodash": "4.17.21"

13.2 --save-prefix 配合配置

设置默认前缀（在 .npmrc 中）：

npm config set save-prefix "~"
npm install express    # "express": "~4.18.2"

13.3 --dry-run

模拟安装，显示将要添加或修改的内容，但不实际写入磁盘。

npm install express --dry-run

13.4 --global-style

强制使用非扁平化结构（模仿 npm v2 风格），每个依赖都有自己的 node_modules。

npm install --global-style

极少使用，但有助于理解历史。

13.5 --legacy-bundling

更早版本的打包策略，已基本废弃。

13.6 --install-links

控制是否使用符号链接代替复制（对于 file: 协议）。默认符号链接。

13.7 --prefer-dedupe

在安装时尽量去重，类似运行 npm dedupe 的行为。

npm install --prefer-dedupe

---

14. 离线缓存机制

14.1 缓存目录

默认位置：

• Windows: %AppData%\npm-cache
• macOS/Linux: ~/.npm

查看：

npm config get cache

缓存结构：

~/.npm/
  _cacache/             # 内容可寻址缓存
    content-v2/         # 实际 tarball 文件
    index-v5/           # 索引文件
  _logs/                # 调试日志

14.2 离线安装选项

# 优先从缓存读取，如果缓存不存在则从网络下载
npm install --prefer-offline

# 完全离线，如果缓存缺失则失败（适用于 CI 容器构建）
npm install --offline

# 强制使用网络，忽略缓存
npm install --no-cache

14.3 管理缓存

# 验证缓存完整性
npm cache verify

# 强制清空缓存（极少需要，除非损坏）
npm cache clean --force

14.4 利用缓存加速 CI

在 CI 中缓存 ~/.npm 目录（例如 GitHub Actions）：

- name: Cache npm
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}

---

15. 镜像源与私有包

15.1 更换镜像源

# 淘宝镜像（中国用户）
npm config set registry https://registry.npmmirror.com

# 官方源（恢复）
npm config set registry https://registry.npmjs.org/

# 临时使用
npm install express --registry=https://registry.npmmirror.com

15.2 配置作用域（scope）注册表

对于私有包，通常使用作用域（@mycompany/package）并指定专用 registry。

# 设置 @mycompany 作用域的注册表
npm config set @mycompany:registry https://npm.pkg.github.com/

# 或者直接在 .npmrc 中
echo "@mycompany:registry=https://npm.pkg.github.com/" >> .npmrc

15.3 私有包身份认证

# 登录 GitHub Package Registry
npm login --registry=https://npm.pkg.github.com/ --scope=@mycompany

或者在 .npmrc 中写入 token：

//npm.pkg.github.com/:_authToken=ghp_xxxxxx
@mycompany:registry=https://npm.pkg.github.com/

15.4 发布私有包

在 package.json 中设置：

{
  "name": "@mycompany/secret-lib",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/",
    "access": "restricted"
  }
}

---

16. 总结与最佳实践

16.1 核心原则

1. 始终提交 package-lock.json 到版本库。
2. 使用 npm ci 而非 npm install 在 CI 和生产环境。
3. 理解版本范围语义 ，避免使用 * 或过于宽泛的范围。
4. 定期运行 npm audit fix 修复安全漏洞。
5. 使用 overrides 谨慎覆盖依赖，并添加注释说明原因。
6. 在 monorepo 中充分利用 workspaces。
7. 保持 npm 版本最新 ：npm install -g npm@latest。

16.2 故障排查清单

• 依赖安装失败 → 检查网络、镜像源、代理。
• 版本冲突 → 尝试 --legacy-peer-deps，但最好升级依赖。
• 依赖重复 → 运行 npm dedupe。
• 锁定文件不一致 → 删除 node_modules 和 package-lock.json，重新 npm install。
• 缓存问题 → npm cache verify。

16.3 常用命令速查

目的	命令
安装依赖	npm i
根据 lock 安装	npm ci
添加生产依赖	npm i lodash
添加开发依赖	npm i -D jest
更新符合范围的包	npm update
列出过期包	npm outdated
查看依赖树	npm ls --depth=0
为什么有这个包	npm why lodash
安全审计修复	npm audit fix
去重	npm dedupe
强制覆盖版本	overrides 字段
模拟安装	npm i --dry-run

---

通过全面理解 npm 依赖管理机制，你不仅能够解决日常开发中的依赖问题，更能设计出稳定、高效的项目结构。不断实践，你将深刻掌握每一处细节。🚀