关键在于建立“版本—依赖树—锁文件—环境”四者联动的系统认知：npm ls揭示逻辑依赖树，package-lock.json是团队协作契约，^/~/exact符号对应不同风险策略，peerdependencies需严格匹配，多版本共存时优先dedupe或用overrides解决。
学 npm 依赖管理，关键不是背命令，而是建立“版本—依赖树—锁文件—环境”四者联动的系统认知。它不是独立技能，而是贯穿开发、CI、部署的稳定性基础。真正卡住人的，往往不是不会装包，而是本地能跑、线上报错，或者改了个小版本，项目突然白屏。
搞懂依赖树：别让 node_modules 成为黑箱
执行 npm ls 是最直接的破局动作。它输出的不是文件列表，而是一棵逻辑树：你的项目是根，每个包是节点，缩进代表依赖层级。重点关注三类标记：
- ├─ 表示该包由父级显式声明（出现在 package.json 的 dependencies 或 devDependencies 中）
- └─ 表示它是某个子依赖间接拉进来的（隐式依赖）
- extraneous 表示这个包被安装了，但没有任何地方声明或需要它——很可能是幽灵依赖或残留
遇到 “Cannot find module 'xxx'”，先运行 npm ls xxx。如果没输出，说明它根本没被正确安装；如果输出多个版本，就要查是谁带进来的，再判断是否该显式声明。
管住 lock 文件：它是团队协作的契约
package-lock.json 不是缓存，是精确记录每个包真实安装版本和完整哈希值的“契约文件”。它的失效是 CI 和生产环境出问题的头号原因。
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- 必须提交到 Git，不能加在 .gitignore 里
- 团队所有成员要用同一版 npm（建议统一为 v8.15+ 或 v9.x），不同大版本生成的 lock 格式不兼容
- CI 流程第一行加检查：git status --porcelain | grep "package-lock.json"，有未提交变更就中断构建
- 修复异常时，标准操作是：rm -rf node_modules package-lock.json && npm install
选对版本符号：^、~、exact 不是风格，是风险策略
语义化版本控制（semver）里的符号，本质是对你承担升级风险程度的声明：
- ^1.2.3：允许升级到 1.x.x 最新版（次版本和修订号都可变），适合工具链依赖（如 eslint），但需配合 npm outdated 定期人工确认
- ~1.2.3：只允许升级到 1.2.x（仅修订号可变），适合对稳定性要求高的基础库（如 axios）
- 1.2.3（无符号）：完全锁定，推荐在应用层核心依赖（如 react、vue）中启用 save-exact=true（写入 .npmrc）
peerDependencies 必须严格匹配，比如 React 组件库声明 "peerDependencies": {"react": "^18.0.0"}，而你项目用了 react@19，运行时可能静默失败，连错误堆栈都不给。
应对冲突与多版本共存：靠 dedupe 和 overrides，不是靠猜
当两个依赖分别要求 lodash@4.17.20 和 lodash@4.17.21，npm 会自动 dedupe 合并；但如果一个是 v4、一个是 v3，就会共存两份——这容易引发类型不一致或 patch 冲突。
- 先试 npm dedupe，让 npm 主动合并可兼容版本
- 若需强制统一，用 overrides（npm v8.3+ 支持）：
"overrides": { "lodash": "4.17.21" } - 长期解法是推动上游包升级依赖，或改用 pnpm（默认 strict-peer-dependencies）收口
