npm 从入门到精通（四）：再工程化，面向团队协作的 npm 最佳实践npm 系列文章总规划《npm 从入门到精通》系

npm 系列文章总规划

《npm 从入门到精通》系列

系列目录

npm 从入门到精通（一）：先会用，30 分钟掌握 npm 最常用命令
npm 从入门到精通（二）：再理解，彻底搞懂 package.json、node_modules 和 package-lock
npm 从入门到精通（三）：再进阶，掌握版本管理、脚本系统与包发布
npm 从入门到精通（四）：再工程化，面向团队协作的 npm 最佳实践

第四篇：npm 从入门到精通（四）：再工程化，面向团队协作的 npm 最佳实践

前面三篇解决的是：

你怎么用 npm
你怎么理解 npm
你怎么把 npm 用到更深入

而这一篇关注的是：
当项目变大、团队变多、流程变复杂时，npm 应该如何工程化地使用。

这也是“会用 npm”和“真正用好 npm”的分水岭。

一、工程化阶段关注的是什么

到了团队协作阶段，npm 不只是本地装几个包那么简单。

你会开始关心：

团队安装结果是否一致
CI/CD 构建是否稳定
依赖是否安全
脚本是否统一
仓库是否整洁
发布流程是否可控

所以工程化的核心，不是多学命令，而是建立规范。

二、一定要提交 package-lock.json

这是最重要的实践之一。

为什么要提交

因为它可以保证：

团队成员安装结果尽量一致
测试环境和生产环境更接近
CI 构建更可重复

如果不提交会怎样

每个人装到的依赖版本可能不同
某些 bug 无法稳定复现
CI 和本地表现不一致

结论

对于大多数应用项目：

提交 package-lock.json 是推荐做法。

三、不要提交 node_modules

通常 .gitignore 应该包含：

node_modules/
dist/
build/
.env

为什么

因为：

node_modules 体积大
不同机器环境可能不同
可以通过 npm 重新安装
提交后仓库会非常臃肿

这条规则几乎可以当作常识。

四、本地开发用 npm install，CI 用 npm ci

这是非常经典的分工方式。

本地开发

npm install

适合：

增加依赖
调整依赖
本地开发

CI/CD

npm ci

适合：

自动化构建
干净环境安装
追求稳定一致的安装结果

为什么 `npm ci` 更适合 CI

更快
更稳定
严格使用 lock 文件
不会随意改 lock 文件

五、统一 scripts，降低团队沟通成本

好的项目不会让团队成员自己记各种命令。
而是统一在 package.json 中提供标准入口。

例如：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

这样所有人都知道：

本地开发：npm run dev
构建项目：npm run build
测试项目：npm run test
代码检查：npm run lint

脚本命名越统一，协作越顺畅。

六、定期做依赖安全审计

npm 生态很大，依赖风险也是现实存在的。

常用命令

npm audit

自动修复一部分问题：

npm audit fix

但要注意

不要无脑执行所有修复。
因为安全修复可能会顺带升级版本，带来兼容性问题。

正确姿势是：

先审计
看影响范围
评估升级风险
再决定是否修复

七、控制依赖数量，不要“见包就装”

一个成熟项目不只是看功能做得快不快，也看依赖治理是否健康。

为什么要克制依赖数量

每多一个依赖，就多一层：

安全风险
升级成本
包体积
学习成本
维护负担

建议

在安装新包前先问自己：

这个功能是否真的需要第三方包？
当前项目里是否已有同类能力？
这个包是否活跃维护？
体积是否太大？
是否值得引入长期维护成本？

别把项目写成“依赖市场批发现场”。

八、遇到依赖异常时的标准处理流程

当项目出现奇怪的依赖问题时，不要上来就乱删乱装。
建议按标准步骤排查。

常见流程

1. 删除安装结果

rm -rf node_modules

2. 必要时删除 lock 文件

rm package-lock.json

3. 清缓存

npm cache clean --force

4. 重新安装

npm install

注意

删除 package-lock.json 不是第一选择，而是修复特殊问题时的手段。

九、npm 配置与镜像源要统一

团队中一个常见问题是：

有人用官方源
有人用镜像源
有人改了全局配置自己都忘了

这会导致很多奇怪问题。

查看当前源

npm config get registry

设置源

npm config set registry https://registry.npmjs.org/

建议

团队最好明确：

是否统一使用官方源
是否允许镜像
是否有公司私有 registry

这样能减少环境差异。

十、发布前检查与团队规范

如果团队会发布 npm 包，建议建立发布规范。

至少包含这些检查项

版本号是否正确
changelog 是否更新
敏感文件是否排除
构建产物是否正确
main / types / exports 是否配置正常
是否通过测试

常见发布流程

本地测试通过
更新版本号
构建产物
发布 npm
打标签
记录变更日志

这时 npm 已经进入真正的“软件供应链”范畴。

十一、团队协作中最推荐的 npm 习惯

这部分适合直接作为团队规范。

十二、这一篇的真正核心

工程化阶段最重要的，不是某个命令，而是下面这套思维：

1. 依赖需要可重复

不能每个人装出来都不一样。

2. 命令需要可标准化

不能每个开发者自己记一套口令。

3. 安装结果需要可追踪

不能出了问题不知道版本怎么变的。

4. 安全需要可治理

不能装了一堆包却完全不审计。

5. 发布需要可控制

不能“本地一把梭，线上听天命”。

总结

如果说前面三篇是在教你“怎么使用 npm”，那么这一篇讲的是：

如何让 npm 服务于团队协作、自动化构建和长期维护。

到了这个阶段，你对 npm 的理解已经不再只是：

安装一个包
跑一个命令

而是开始把 npm 当作：

依赖治理工具
脚本执行中枢
团队工程规范的一部分

这时，“npm 从入门到精通”这条线，基本就走通了。

npm 从入门到精通（四）：再工程化，面向团队协作的 npm 最佳实践