npm依赖管理是贯穿开发全链路的稳定性工程，核心问题包括锁文件失效、版本漂移、依赖树冲突及工具链错配；典型表现如ERESOLVE报错、模块找不到等，根源多为package-lock.json未提交或npm版本不一致，修复需删除node_modules和lock文件后用统一npm版本重装。
npm 依赖管理不是“装完就跑”的操作，而是贯穿开发、测试、部署全链路的稳定性工程。真正出问题的时候，往往不是 npm 崩了，而是版本漂移、锁文件失效、依赖树冲突或工具链错配——这些都藏在看似平常的 npm install 背后。
一、典型翻车现场：为什么本地能跑，CI 和生产却报错？
常见表现：ERESOLVE unable to resolve dependency tree、Cannot find module 'xxx'、某中间件突然不生效。根源几乎总是同一类：package-lock.json 没提交、被误删，或团队成员用了不同 npm 版本（如 v6 vs v8+）导致锁文件格式不兼容。
- 验证方式：执行
npm ls <包名>查看实际安装的版本和路径，对比 package.json 声明与 lock 文件记录是否一致 - 修复动作：删除 node_modules 和 package-lock.json，再用 项目统一的 npm 版本 执行
npm install重建锁文件 - 预防措施：在 CI 流程开头加检查脚本，确保
git status --porcelain | grep "package-lock.json"为空，否则阻断构建
二、依赖冲突：两个组件都要 lodash，但一个要 v4，一个要 v3
这不是 bug，是 npm 扁平化策略下的必然现象。当无法统一版本时，npm 默认把高版本提升到顶层 node_modules，低版本保留在子依赖自己的 node_modules 里——这叫“多版本共存”，但容易引发隐性问题（比如类型定义不匹配、全局 monkey patch 冲突）。
- 优先尝试
npm dedupe让 npm 主动合并可兼容的版本 - 若必须隔离，用
overrides字段在 package.json 中强制指定某个子依赖的版本（npm v8.3+ 支持）：
"overrides": { "lodash": "4.17.21" } - 长期建议：推动上游包升级依赖，或用
resolutions（需搭配 yarn）/pnpm的 strict-peer-dependencies 模式收口
三、锁定策略调优：^、~、exact 到底怎么选？
语义化版本符号不是风格偏好，而是风险控制开关。^ 允许次版本升级（含新功能），~ 只允许修订号升级（仅修 bug），exact 则完全锁定。
- 应用层依赖（如 react、express）：推荐
save-exact=true（写入 .npmrc），避免小版本引入破坏性变更 - 工具链依赖（如 eslint、jest）：可用 ^，但务必配合
npm outdated定期人工确认升级影响 - peerDependencies（如 React 组件库）：必须显式声明且版本严格对齐，否则运行时可能白屏无报错
四、私有工具复用：别再复制粘贴 utils 文件夹了
当多个项目共享日志封装、API 请求拦截、配置加载器时，“复制即债务”。正确做法是把它变成一个独立 npm 包，哪怕只供内部使用。
- 结构示例：根目录下建
packages/logger，含自己的package.json和src/index.js - 发布方式三选一：
— 用npm publish --access=restricted发布为私有模块
— 推送到公司 Nexus 私有 registry（需配置 .npmrc 的 registry 地址）
— 开发阶段直接npm link或"@myorg/logger": "link:../packages/logger" - 关键收益：所有业务项目通过
import { log } from '@myorg/logger'消费，版本升级只需改一处，无需全量搜索替换
