Git gitignore 添加规则无效的解决办法

如果在项目一开始的时候，没有添加 .gitignore 文件，文件就会被跟踪，此时，再向 .gitignore 中添加内容就无法让 git 忽略，发现没有效果。

可以使用如下方式，让 git 重新对文件进行跟踪

git rm -rf --cached .
git add .

跑完记得提交，否则 index 的改动只停在暂存区：

git commit -m "chore: 应用新的 .gitignore 规则"

为什么 .gitignore 对已跟踪文件无效

这是 .gitignore 最核心的一条语义：它只影响「未跟踪文件」是否被 git add 和 git status 看到，对已经进入 index 的文件完全没有作用。

原因在于 git 的工作模型：一个文件一旦被 git add 过，它就在 index 里有了条目，git 每次都会拿工作区的它和 index 里的记录比对，报告改动。.gitignore 只在「扫描工作区发现新文件」这一步起作用，index 里已有的条目根本不走这个流程。

所以 git rm --cached 才是解法——它把条目从 index 里删掉，文件回到「未跟踪」状态，这时 .gitignore 才开始管它。

--cached 这个参数必须有。不加的话 git rm 会同时删掉工作区的实际文件，git rm -rf . 是把项目文件全删了，这是完全不同的后果。

只处理特定文件，别动整个仓库

原文那个「清空整个 index 再全量重加」的做法确实有效，但动静太大：所有文件的 mtime 元数据被重写，git status 可能一次性显示上千个文件的变化，还容易把当前正在改的东西混进这次提交。

只有一两个文件要忽略的话，精确处理就够了：

# 单个文件
git rm --cached .env.local

# 整个目录（-r 递归）
git rm -r --cached node_modules
git rm -r --cached dist

# 只从 index 移除但保留文件（--cached 已经保证这点，再确认一遍）
ls .env.local    # 文件还在

git commit -m "chore: 停止跟踪本地配置文件"

有个更轻的替代方案，Git 2.25+ 的：

# 只从 index 移除，不产生「删除」的 diff 记录（适合大批量）
git rm -r --cached . --quiet && git add .

先确认是不是别的原因

在动 index 之前，最好先确认规则本身写对了。git 自带的调试命令能直接告诉你某个文件为什么被忽略/没被忽略：

# 查某个文件命中了哪条规则（输出：文件名 : 行号 : 规则）
git check-ignore -v node_modules/vue/package.json
# .gitignore:3:node_modules/    node_modules/vue/package.json

# 没有输出说明没有任何规则匹配它
git check-ignore -v src/a.ts

# 列出所有被忽略的文件
git status --ignored

git check-ignore -v 是排查这类问题的第一站。它能区分三种情况：规则没写对（无输出）、规则写对了但文件已被跟踪（无输出但 git status 有它）、被别的 ignore 文件匹配了（输出的文件名不是 .gitignore）。

规则写法里的坑

目录必须带斜杠或者写对层级。 node_modules 和 node_modules/ 都能忽略目录，但前者也会忽略同名的文件。习惯上目录加尾斜杠更明确。

开头的斜杠决定是否只匹配根目录：

# 匹配任意层级的 dist 目录
dist/

# 只匹配仓库根的 dist
/dist/

# 匹配任意层级的 build 目录下的所有内容
**/build/

已忽略目录里的文件无法用 ! 反选出来。 这是最反直觉的一条：

# 不生效！目录整体被排除了，git 压根不会进去扫描
node_modules/
!node_modules/some-pkg/

# 正确写法：先放行目录本身，再排除其中内容
node_modules/*
!node_modules/some-pkg/

原因是 git 为了性能，遇到被忽略的目录会直接跳过整棵子树，不会进去逐个文件判断，所以里面的 ! 规则永远没机会被求值。

后面的规则覆盖前面的。 .gitignore 是按顺序匹配、最后一条命中的生效。所以 ! 反选规则必须写在对应的忽略规则之后。

注释和空行： # 开头是注释，想忽略真的以 # 开头的文件要转义成 \#。行尾空格会被忽略，除非用 \ 转义。

除了 .gitignore 还有几处会生效

git check-ignore -v 输出的文件名不是 .gitignore 时，就是这几个地方之一：

# 全局忽略，对所有仓库生效，适合放 .DS_Store、编辑器目录
git config --global core.excludesfile ~/.gitignore_global

# 仓库本地忽略，不提交进版本库，适合个人的临时文件
.git/info/exclude

# 子目录里的 .gitignore（作用域限于该目录及其子目录）
src/.gitignore

.git/info/exclude 很实用但常被忽略。个人的调试脚本、临时笔记不该出现在团队共享的 .gitignore 里（那是项目级约定），放这里正好——只对你的这个克隆生效，也不会污染仓库。

我的 ~/.gitignore_global 里固定放这些：

.DS_Store
Thumbs.db
*.swp
.idea/
.vscode/
*.log

已提交的敏感文件要额外处理

git rm --cached 只是让 git 今后不再跟踪，历史提交里的内容一个字节都没变。如果误提交的是 .env、私钥、token 这类敏感信息，光这一步远远不够——任何人 git log -p 都还能翻出来。

正确的处理顺序是：

立刻作废那个凭据（去平台重置密钥/token）。这一步最重要，也是唯一真正有效的。
从 index 移除并加进 .gitignore。
需要清理历史的话用 git filter-repo（官方推荐，替代已废弃的 filter-branch）：

pip install git-filter-repo
git filter-repo --invert-paths --path .env

改写历史会让所有提交的 SHA 变化，已推送的仓库需要强推，所有协作者都得重新克隆。所以第 1 步永远优先——凭据一旦泄露就该当作已泄露处理，清历史只是善后。

让新项目一开始就配好

避免这个问题最省事的办法是建仓库时就把 .gitignore 准备好。GitHub 维护了一套按语言分类的模板：

# 用 gh 直接拉 Node 模板
gh api /gitignore/templates/Node --jq .source > .gitignore

# 或者用 npx
npx gitignore node

Node 项目的最小必需项：

node_modules/
dist/
.env
.env.local
*.log
.DS_Store
.cache/
coverage/