npm 从入门到精通（二）：再理解，彻底搞懂 package.json、node_modules 和 package-lock

npm 系列文章总规《npm 从入门到精通》系列系列目录npm 从入门到精通一先会用30 分钟掌握 npm 最常用命令npm 从入门到精通二再理解彻底搞懂 package.json、node_modules 和 package-locknpm 从入门到精通三再进阶掌握版本管理、脚本系统与包发布npm 从入门到精通四再工程化面向团队协作的 npm 最佳实践第二篇npm 从入门到精通二再理解彻底搞懂 package.json、node_modules 和 package-lock很多人会用 npm但对 npm 的理解停留在npm installnpm run dev缺啥装啥这没问题但一旦项目变复杂就会开始遇到各种疑问为什么安装完会出现node_modules为什么还会多一个package-lock.json为什么团队协作中有人强调“不要删 lock 文件”dependencies和devDependencies到底有什么区别这篇文章的目标就是把这些底层概念彻底讲清楚。一、npm 项目的核心结构一个最典型的 npm 项目通常包含这些内容my-project/ ├─ node_modules/ ├─ package.json ├─ package-lock.json └─ src/这里最关键的是三个文件/目录package.jsonpackage-lock.jsonnode_modules它们构成了 npm 项目的基本运行机制。二、package.json 到底是什么package.json是 npm 项目的核心配置文件。它主要负责描述项目是谁项目版本是多少入口文件是什么有哪些脚本命令依赖了哪些包例如{name:my-app,version:1.0.0,scripts:{dev:vite,build:vite build},dependencies:{react:^19.0.0},devDependencies:{vite:^7.0.0}}你可以把它理解成项目的身份证项目的依赖清单项目的命令入口三、dependencies 和 devDependencies 的区别这是必须搞懂的基础。dependencies运行项目时必须依赖的包例如reactvueexpressaxios这些属于应用运行的“正式成员”。devDependencies只在开发阶段需要的包例如vitewebpackeslinttypescriptjest这些属于“开发辅助工具”。最简单的判断方法项目运行时要用dependencies只是开发、构建、测试时用devDependencies下面这张表更直观类型作用示例dependencies项目运行依赖react、axios、expressdevDependencies开发阶段依赖vite、eslint、typescript四、node_modules 是什么node_modules是 npm 安装依赖后的实际存放目录。当你执行npminstallnpm 会根据package.json和package-lock.json把需要的依赖下载到node_modules。它的特点体积通常很大层级结构复杂可以删除后重新安装一般不提交到 Git所以团队项目中通常会在.gitignore中写node_modules/为什么不提交因为目录太大可通过配置文件重新安装不同系统下内容可能不同五、package-lock.json 到底有什么用这是很多人容易忽略但又非常重要的文件。它记录的是实际安装的依赖精确版本每个依赖的依赖依赖树结构下载来源与校验信息为什么需要它因为package.json通常写的是版本范围比如react:^19.0.0这表示允许安装19.x.x范围内的更新版本。但“到底安装了哪个具体版本”就由package-lock.json记录。它的价值保证团队安装结果一致保证 CI 环境安装结果一致降低“我这里能跑你那里不行”的概率一句话package.json决定想要什么package-lock.json记录实际装了什么。六、为什么不能随便删 package-lock.json有些新手喜欢遇事就删 lock 文件这种做法偶尔能“暂时好使”但不是长期正确习惯。随便删除的风险团队依赖树不一致某些包被升级后出现兼容问题CI / 线上构建结果变化调试难度上升什么时候可以删以下场景可以考虑删除后重装依赖树严重混乱lock 文件损坏版本冲突难以修复需要彻底重建依赖环境一般操作是rm-rfnode_modules package-lock.jsonnpminstall但这属于“修复手段”不应该变成日常习惯。七、npm install 做了什么当你执行npminstallnpm 并不是单纯“下载包”它实际会做这些事读取package.json读取package-lock.json解析依赖树下载缺失依赖放入node_modules更新 lock 文件必要时所以npm install的本质是根据配置文件构建出项目依赖环境。八、npm ci 和 npm install 的区别这个点非常重要尤其到了团队协作和 CI/CD 阶段。npm install适合本地开发特点是更灵活可能会更新 lock 文件会根据 package.json 处理依赖npm ci适合自动化环境特点是严格按照package-lock.json安装更快更稳定如果 lock 文件和 package.json 不一致会报错结论本地开发常用npm install持续集成优先npm ci九、为什么别人项目拉下来就能安装因为 npm 项目的依赖信息已经被写进package.jsonpackage-lock.json只要你把代码拉下来再执行npminstall就能重建依赖环境。这也是 npm 工程化的核心价值之一不需要把所有依赖文件传来传去只需要传“依赖描述”。十、这篇要真正记住什么如果你只想抓住最核心的点记住这几个1.package.json记录项目信息、脚本、依赖声明2.node_modules依赖实际安装目录3.package-lock.json记录依赖精确版本和依赖树4. 不提交node_modules但通常要提交package-lock.json5.dependencies和devDependencies要分清总结npm 真正重要的不只是命令而是它背后的依赖管理逻辑。你现在需要建立的认知是package.json是依赖声明package-lock.json是依赖锁定node_modules是依赖落地结果理解了这三者关系后面学版本管理、脚本系统、包发布时就不会一头雾水。下一篇我们进入第三层npm 版本号怎么管理scripts 怎么玩自己的包又该怎么发布