在 Git 项目根目录的 .gitignore 文件中添加 node_modules/ 规则，可阻止该文件夹被提交。若 node_modules 已被版本库追踪，需先执行 git rm -r `--cached` node_modules 清除缓存再提交。

命令速用版

以下命令适用于 Linux、macOS 及 Git Bash 环境，直接在项目根目录执行。

# 1. 将 node_modules 写入 .gitignore
echo "node_modules/" >> .gitignore

# 2. 若已追踪，从缓存移除（不删除本地文件）
git rm -r `--cached` node_modules

# 3. 提交更改
git commit -m "chore: ignore node_modules"

为什么会这样

node_modules 文件夹体积大且内容可由 package.json 重建，不应纳入版本控制。

Git 默认追踪所有未忽略的文件。node_modules 包含大量依赖代码，不同操作系统或架构下的二进制文件可能不同，提交会导致仓库体积膨胀且产生不必要的冲突。通过 .gitignore 告诉 Git 跳过该文件夹，能保持仓库轻量且聚焦于源代码。

分步处理

按顺序执行以下步骤，确保忽略规则生效且清理历史追踪记录。

步骤 1：检查当前状态

适用场景：不确定 node_modules 是否已被提交。

操作动作：运行 git status 查看输出。

验证结果：若 node_modules 出现在 "Changes to be committed" 或 "Untracked files" 中，说明需要处理。

风险边界：若显示在 "Changes to be committed"，说明已纳入版本库，必须清理缓存。

步骤 2：配置忽略规则

适用场景：所有项目。

操作动作：在项目根目录创建或编辑 .gitignore 文件，写入 node_modules/。

验证结果：cat .gitignore 确认内容包含 node_modules/。

风险边界：确保写在根目录的 .gitignore，而非子目录，除非只需忽略特定子目录。

步骤 3：清理已追踪文件

适用场景：步骤 1 中显示 node_modules 已被追踪。

操作动作：执行 git rm -r `--cached` node_modules。

验证结果：终端无报错，git status 不再显示 node_modules 为待提交变更。

风险边界：`--cached` 参数仅移除版本库索引，不会删除本地实际文件，放心使用。

步骤 4：提交更改

适用场景：完成上述配置后。

操作动作：执行 git add .gitignore 和 git commit。

验证结果：git log 可见提交记录。

风险边界：若团队协作，通知成员拉取更新后需重新运行 npm install。

怎么验证是否生效

执行 git status 命令，输出结果中不应出现 node_modules 文件夹的任何文件。

尝试修改 node_modules 内的任意文件，再次运行 git status，若该修改未显示，说明忽略规则已生效。若推送到远程仓库，检查远程仓库界面，确认不存在 node_modules 目录。

常见坑

1. 仅添加 .gitignore 未清理缓存

若 node_modules 已被提交过，仅修改 .gitignore 不会自动移除已追踪文件。必须执行 git rm -r `--cached` node_modules 才能停止追踪。

2. 全局忽略与局部忽略混淆

全局配置 git config `--global` core.excludesfile 适合个人习惯，但项目级 .gitignore 更适合团队协作，确保所有成员一致。

3. 误删本地文件

执行移除命令时务必带上 `--cached` 参数。若漏写，git rm -r node_modules 会直接删除本地依赖文件，需重新 npm install 恢复。

常见问题

node_modules 已经被提交了怎么办

先执行 git rm -r `--cached` node_modules 从版本库移除，再提交更改，历史记录中的文件不会自动消失但新提交不再包含。

为什么 .gitignore 写了没生效

通常是因为文件已被 Git 缓存追踪，需先清除缓存，或检查 .gitignore 文件路径是否在根目录。

可以在全局配置忽略 node_modules 吗

可以，使用 git config `--global` core.excludesfile 配置全局忽略文件，但建议优先使用项目级 .gitignore 以便团队协作。

参考来源

• Git SCM 官方文档：gitignore 文件格式说明，URL: https://git-scm.com/docs/gitignore
• GitHub 官方文档：Ignoring files 指南，URL: https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files