npm：包管理与工程化入门

这一课你将能做到

1. 用 package.json 管理项目元数据、依赖和脚本
2. 安装、更新、删除第三方包，理解 dependencies 与 devDependencies 的区别
3. 配置 scripts 实现一键启动、构建、测试，用 npx 直接运行包

为什么要学

现代前端项目不是从零手写所有代码，而是站在巨人的肩膀上组装：React 做 UI、axios 发请求、dayjs 处理时间、Tailwind 写样式。npm（Node Package Manager）就是管理这些「积木」的工具。它负责下载包、管理版本、执行命令。

不会 npm，你就无法使用现代前端生态。npm install、npm run dev、npm run build 是每个前端工程师每天都要敲的命令。

先建立图像

一个典型的 npm 项目结构：

my-app/
├── node_modules/      ← 所有第三方包下载到这里（不提交 Git）
├── package.json       ← 项目说明书：名称、版本、依赖、脚本
├── package-lock.json  ← 精确锁定依赖版本（要提交 Git）
└── index.js

package.json 是项目的身份证和账本，node_modules 是仓库本身，package-lock.json 是账本副本，确保团队成员装的是同一版本。

跟着做

步骤 1：初始化项目

mkdir my-app && cd my-app

# 交互式初始化（一路回车用默认值）
npm init

# 或快速初始化（跳过提问）
npm init -y

生成 package.json：

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

步骤 2：安装依赖

# 安装运行依赖（生产环境需要）
npm install lodash

# 安装开发依赖（只有开发时需要，如测试框架、构建工具）
npm install --save-dev vitest

# 简写
npm i lodash
npm i -D vitest

# 安装指定版本
npm install lodash@4.17.21

安装后 package.json 自动更新：

{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "vitest": "^1.6.0"
  }
}

• dependencies：项目运行时必须存在，比如 React、axios
• devDependencies：开发工具，比如测试框架、打包器，部署时不需要

^4.17.21 是语义化版本：允许升级到 4.x.x 的最新版，但不允许 5.0.0。~ 只锁定前两位，4.17.x。

步骤 3：使用安装的包

新建 index.js：

const _ = require("lodash");

const users = [
    { name: "张三", age: 25 },
    { name: "李四", age: 30 },
    { name: "王五", age: 20 }
];

// lodash 按年龄排序
const sorted = _.sortBy(users, ["age"]);
console.log(sorted);

运行：

node index.js

输出按年龄排序后的数组。这就是 npm 的价值：一行代码引入别人写好的功能。

步骤 4：配置 scripts

修改 package.json 的 scripts 字段：

{
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "test": "vitest",
    "build": "echo 构建完成"
  }
}

然后直接用命令：

npm run dev    # 启动开发模式
npm test       # 运行测试
npm run build  # 构建

scripts 是项目命令的统一入口，新人拿到项目先看 package.json 的 scripts，就知道怎么启动和构建。

步骤 5：npx 直接运行包

有些包只需要执行一次，不需要长期安装到项目里。用 npx 临时下载并运行：

# 创建 React 项目（create-react-app 已不推荐，这里演示 npx 用法）
npx create-vite my-react-app --template react

# 运行一次性的代码检查
npx prettier --write .

npx 的好处：不污染全局环境，用完即走。

步骤 6：更新与删除

# 查看过期的包
npm outdated

# 更新到允许的最新版本（遵循 package.json 的版本范围）
npm update

# 删除包
npm uninstall lodash

# 全局安装（命令行工具才全局安装）
npm install -g nodemon

讲清楚要点

1. package.json 是项目的中枢：名称、版本、入口、依赖、脚本都在这里面。团队协作时，新人 npm install 就能还原整个环境。
2. dependencies 和 devDependencies 要分清楚：线上运行需要的放前者，开发工具放后者。放错了会导致生产环境缺包或包体积过大。
3. package-lock.json 必须提交：它记录每个包的确切版本和依赖树，确保你和同事、线上服务器装的是一模一样的代码。
4. node_modules 不提交 Git：里面可能有几十万个文件，提交会让仓库爆炸。package.json + package-lock.json 就能完整还原。
5. 语义化版本号 主版本.次版本.修订号：主版本不兼容更新，次版本向下兼容新增功能，修订号向下兼容 bug 修复。^ 锁定主版本，~ 锁定次版本。

你可能会懵的地方

• 为什么 npm install 后 node_modules 那么大？ 因为包会依赖其他包，依赖的依赖又依赖更多包，形成依赖树。node_modules 是所有依赖的平铺安装，几万文件很正常。

• npm install 和 npm ci 的区别？ npm install 可能根据 package.json 的语义化版本升级依赖；npm ci 严格按 package-lock.json 安装，速度快且可复现，CI/CD 环境推荐用 npm ci。

• 为什么要用 --save-dev？ 告诉 npm 这是开发工具。部署时执行 npm install --production 只装 dependencies，不装 devDependencies，减小体积。

• 包版本冲突怎么办？ 两个包依赖同一库的不同版本时，npm 会尝试自动解决（装两个版本嵌套）。如果出问题，用 npm ls 包名 查看依赖树，手动调整版本。

• registry 是什么？ npm 的包仓库服务器。默认是 https://registry.npmjs.org。国内网络慢可以切换镜像源：npm config set registry https://registry.npmmirror.com。

错法对照

错法	问题	正解
把 node_modules 提交到 Git	仓库臃肿，clone 极慢	加入 .gitignore
全局安装所有工具	版本冲突，换电脑就失效	项目依赖本地装，命令行工具才全局装
修改 package.json 版本号后手动删 node_modules	效率低	npm install 会自动更新
版本号写 latest	不可复现，随时可能坏	写具体版本或语义化范围
在 dependencies 里放测试框架	生产环境装了不需要的包	移到 devDependencies
删除 node_modules 后无法启动	忘记重新安装	npm install 一键还原
用 npm install 在 CI 环境	可能装到不同版本	CI 用 npm ci

卡点急救

1. npm install 卡住或失败：换镜像源：npm config set registry https://registry.npmmirror.com；或删除 node_modules 和 package-lock.json 后重装。
2. 版本冲突报错：npm ls 查看冲突位置，手动在 package.json 里统一版本号，然后 npm install。
3. 脚本命令找不到：检查 package.json 的 scripts 里是否定义了该命令；注意 npm run xxx 和 npm xxx 的区别（start/test 可省略 run）。
4. npx 提示 command not found：Node.js 版本太旧，升级到 LTS 版本（18+）。

面试常问

• dependencies 和 devDependencies 的区别？ 前者是生产环境必需的运行时依赖；后者是开发、测试、构建阶段的工具。部署时 npm install --production 只装前者，减小体积和攻击面。

• package-lock.json 的作用？ 锁定所有依赖（包括间接依赖）的精确版本，确保任何环境 npm install 后得到完全一致的 node_modules。必须提交到 Git。

• npm install 的流程？

  1. 读取 package.json 和 package-lock.json；2) 解析依赖树；3) 下载到缓存；4) 解压到 node_modules；5) 生成/更新 lock 文件。

• 怎么发布一个自己的 npm 包？ npm login 登录 → 确保 package.json 的 name 唯一 → npm publish。加 --access public 发布公开包。

自测三问

1. npm install lodash 和 npm install --save-dev vitest 会把包写到 package.json 的哪个字段？
2. 为什么 package-lock.json 必须提交到 Git，而 node_modules 不能提交？
3. npm run build 执行的是 package.json 里的什么配置？

小结一句话

npm 是前端工程的供应链：package.json 管清单、node_modules 管库存、scripts 管流水线——三条命令就能把别人的代码变成你的生产力。

延伸

• npm 官方文档
• 下一课：React——用组件化思维构建用户界面。