17370845950

npm 是 JavaScript 项目的依赖管理工具，通过 package.json 声明契约、package-lock.json 锁定精确版本，需用命令安装依赖而非手动修改文件，且必须提交 lock 文件以确保环境一致。

npm 是 JavaScript 项目的包管理器，不是“Node.js 的插件市场”，也不是“下载 JS 库的网站”——它是你本地项目依赖的声明、安装、执行和版本控制工具。没它，require('lodash') 会直接报 Error: Cannot find module 'lodash'。

npm init 之后发生了什么？

运行 npm init（或 npm init -y 跳过交互）会在当前目录生成 package.json。这个文件不是“配置文件”，而是你项目的**依赖契约**：它明确记录了哪些包、什么版本、在什么场景下被需要。

• dependencies：生产环境必需的包，比如 react、axios
• devDependencies：仅开发时用的包，比如 eslint、vite
• peerDependencies：第三方库声明“我期望宿主项目提供什么”，比如 react-dom 对 react 的要求

别手动改 package.json 里的依赖字段——用命令写入才同步更新 node_modules 和锁文件。

install 命令怎么选？

装包不是只有 npm install xxx 一种写法。不同参数决定包进哪个字段、是否全局、是否精确锁定版本：

• npm install lodash → 加入 dependencies，按 ^ 规则允许补丁/次版本升级
• npm install eslint --save-dev 或 npm install eslint -D → 加入 devDependencies
• npm install react@18.2.0 → 精确安装指定版本，package.json 中写死 "react": "18.2.0"
• npm install --no-save some-tool → 只下载到 node_modules，不写入 package.json（极少用，容易失控）

注意：npm install 不带参数时，是根据 package.json 和 package-lock.json 复原整个 node_modules 结构——不是“升级所有包”，这点常被误解。

为什么必须提交 package-lock.json？

package-lock.json 是 npm 自动生成的“依赖快照”。它锁定每个包的完整解析路径、确切版本、校验和（integrity hash）。没有它：

• 团队成员 npm install 得到的可能是不同子依赖树（比如 lodash v4.17.21 vs v4.17.22）
• CI 构建可能因某天上游包发布破坏性更新而突然失败
• npm ci（CI 环境专用安装）根本无法运行，因为它只认 package-lock.json，不读 package.json

所以：永远把 package-lock.json 提交到 Git；不要 .gitignore 它；不要手动编辑它。

常见依赖问题与应对

实际开发中，几个高频症状背后往往有明确归因：

• Cannot find module 'xxx'：检查 node_modules/xxx 是否存在；确认包是否装在 devDependencies 却在生产代码里 require 了
• 同一包多个版本共存（node_modules/lodash 下还嵌套着 node_modules/lodash/some-deep）：这是 npm 的扁平化策略失效，通常由不兼容的 peerDependencies 引起，可用 npm ls lodash 查路径
• 安装卡住 / 报 TLS 错误：优先换 registry：npm config set registry https://registry.npmjs.org/（国内可设为 https://registry.npmmirror.com）

最易被忽略的是：删除 node_modules 后，必须重新运行 npm install，不能靠复制别人目录——因为 package-lock.json 和本地 node_modules 的哈希必须严格匹配，否则后续 npm audit 或 npm update 都可能出错。