npm依赖管理是围绕package.json、node_modules和package-lock.json协同运作的工程实践：init声明结构，install按用途分dependencies/devDependencies，ci保障CI环境确定性，list/explain辅助精准排错。
npm 依赖管理不是“装完就跑”，而是围绕 package.json、node_modules 和 package-lock.json 三者协同运作的一套工程实践。掌握它，关键在于理解每个命令背后的意图和影响范围，而不是死记参数。
初始化项目要明确语义
运行 npm init -y 生成的 package.json 是整个依赖体系的起点。它不只是记录名字和版本，更是你对项目结构的声明：
- 入口字段（main、types、exports） 决定别人能否正确引入你的包；
-
engines 字段（如
"node": ">=18.0.0"）能提前拦截不兼容环境，避免 CI 上报错； - 首次安装生产依赖前，建议先手动补全
private: true，防止误发私有项目到公共 registry。
安装依赖必须区分用途和作用域
一个包该进 dependencies 还是 devDependencies，不能凭感觉。核心判断标准是：它是否参与最终构建产物的执行逻辑？
- 进
dependencies：React、Express、Axios —— 代码里require()或import了，上线必须存在； - 进
devDependencies：Vite、ESLint、Jest —— 只在本地开发、打包、测试时起作用，部署时可被忽略； - 绝对不要用
npm install -g安装项目所需库，比如npm install -g typescript后在脚本里调tsc，这会导致不同机器行为不一致；应改用npx tsc或写入devDependencies后通过npx调用。
还原与更新依赖要守住确定性
团队协作中，“我本地能跑”但“CI 报错”的根源，90% 出在依赖还原方式不对：
-
npm install（无参数）：严格按package-lock.json安装，不升级、不修改 lock 文件，适合日常拉代码后同步环境； -
npm ci：CI/CD 环境首选，跳过解析阶段，直接读 lock 文件安装，更快更干净，且会校验package.json和 lock 是否一致，不一致直接失败； -
npm update：只升级符合当前版本范围（如^1.2.0）的最新兼容版，不会跨主版本；若需强制升级某包到最新主版本，用npm install 包名@latest并确认是否破坏兼容性。
排查依赖问题要从锁文件和树结构入手
遇到 “找不到模块”、“版本冲突”、“重复打包” 时，别急着重装 node_modules：
- 先看
package-lock.json：搜索报错包名，确认它实际解析出的版本、路径、以及被谁引入； - 再查依赖树：
npm list 包名查具体版本和层级，npm list --depth=0看一级依赖，npm list --all | grep 包名快速定位嵌套位置； - 发现多个版本共存？可能是子依赖指定了不兼容的范围，用
npm explain 包名（npm v8.15+）直接显示冲突原因和推荐修复方案。
