不清理 'node_modules'（提交 1GB 依赖到 Git）

不清理 'node_modules'（提交 1GB 依赖到 Git）

前端开发中，node_modules 是一个让人又爱又恨的目录。它包含了项目所需的所有依赖，但体积庞大且频繁变化。有人图省事，直接将整个 node_modules 提交到 Git，结果仓库膨胀到 1GB 以上。这种做法看似方便，实则后患无穷。

为什么不能提交 node_modules 到 Git

体积爆炸性增长

现代前端项目的依赖数量动辄上千，node_modules 轻松突破几百 MB。例如，一个基于 React 的项目：

$ du -sh node_modules
256M

如果团队每人提交一次，仓库体积会呈指数级增长。Git 本身不适合管理二进制文件或大量小文件，克隆和推送速度会急剧下降。

依赖版本冲突

node_modules 里可能包含平台特异性依赖（如 node-sass）。你在 macOS 编译的二进制文件，其他人在 Windows 拉取后可能无法运行：

Error: Node Sass does not yet support your current environment

破坏依赖锁机制

package-lock.json 或 yarn.lock 已经精确锁定了依赖树。提交 node_modules 会导致：

1. lock 文件与实际安装的依赖不一致
2. 不同环境下的 node_modules 结构差异引发隐蔽 bug

正确的依赖管理姿势

使用 .gitignore 排除

第一原则是在 .gitignore 中添加：

# .gitignore
node_modules/

利用锁文件保证一致性

安装依赖时始终使用：

npm install --package-lock-only  # 或 yarn --pure-lockfile

这样会严格根据 lock 文件还原依赖树。

处理必须提交的依赖

极少数情况下需要提交依赖（如离线环境），应该：

1. 只提交必要的直接依赖
2. 使用 npm pack 生成 tarball：

npm pack lodash
# 生成 lodash-4.17.21.tgz

如何挽救已提交的 node_modules

从 Git 历史中彻底删除

使用 git filter-branch 清除历史记录：

git filter-branch --force --index-filter \
  "git rm -rf --cached --ignore-unmatch node_modules" \
  --prune-empty --tag-name-filter cat -- --all

清理仓库体积

强制推送后执行垃圾回收：

git reflog expire --expire=now --all
git gc --prune=now --aggressive

依赖优化的进阶技巧

使用 pnpm 替代 npm/yarn

pnpm 通过硬链接共享依赖，节省磁盘空间：

pnpm install  # 依赖存储在全局 store

按需安装生产依赖

npm ci --only=production 可以跳过 devDependencies：

// package.json
{
  "devDependencies": {
    "eslint": "^8.0.0"  // 不会安装到生产环境
  }
}

动态加载第三方库

现代打包工具支持按需加载：

// 动态导入 lodash 的 debounce
import('lodash/debounce').then(({ default: debounce }) => {
  debounce(() => console.log('Hi'), 500)
});

当 node_modules 遇到 Docker

容器化部署时更要注意：

# 错误做法：复制整个 node_modules
COPY . /app

# 正确做法：分阶段构建
FROM node:16 AS builder
COPY package*.json .
RUN npm ci
COPY . .
RUN npm run build

FROM nginx
COPY --from=builder /app/dist /usr/share/nginx/html

那些年我们踩过的坑

• 案例 1：某项目将 node_modules 提交后，GitLab CI 因超时失败。清理后构建时间从 15 分钟降至 2 分钟。
• 案例 2：团队成员误操作导致 node_modules/.bin 中的可执行文件被覆盖，引发不可预知的构建错误。
• 案例 3：安全扫描工具对提交的依赖发出 50+ 漏洞警告，实际生产环境使用的是已修复版本。