---
title: ".geminiignore"
description: ".geminiignore 的用途：排除敏感文件、大文件、构建产物、本地数据库和不希望 Gemini CLI 读取的项目内容。"
verifiedAt: "2026-05-09"
---

`.geminiignore` 用来告诉 Gemini CLI 哪些文件不要读取或搜索。官方 file management tutorial 说明：Gemini CLI 默认尊重 `.gitignore`，但你可以用 `.geminiignore` 排除不适合暴露给 AI 的文件。

> [!WARNING]
> `.geminiignore` 是上下文过滤，不是安全沙箱。不要因为写了 ignore，就把密钥、客户数据或本地数据库留在 AI 可操作目录里。

## 工作机制

`.geminiignore` 的语法基本沿用 `.gitignore`：

- 空行和 `#` 注释会被忽略。
- 支持 `*`、`?`、`[]` 等 glob。
- 结尾 `/` 只匹配目录。
- 开头 `/` 表示相对 `.geminiignore` 所在目录锚定。
- `!` 可以取消排除。

被排除的路径会从支持该机制的 Gemini CLI 工具里过滤掉，例如 `@` 文件引用、文件读取和搜索。但它不会替你改变 Git、磁盘权限或第三方服务访问能力。修改 `.geminiignore` 后需要重启当前 Gemini CLI 会话才会生效。

官方配置里还有两个容易被忽略的开关：`context.fileFiltering.respectGitIgnore` 和 `context.fileFiltering.respectGeminiIgnore`。如果你发现 `@` 引用、`read_many_files` 或搜索结果和预期不一致，先检查这两个开关是否被用户级、项目级或系统级 settings 覆盖。

`@<path>` 文件引用是最常见的触发点。它会通过多文件读取工具把文件或目录加入上下文，并按 Git-aware 过滤规则处理。也就是说，`.geminiignore` 不是孤立生效，而是和 `.gitignore`、settings 里的 fileFiltering、工具参数一起决定最终能看到哪些文件。

## 推荐模板

```text
.env
.env.*
*.pem
*.key
*.p12
*.sqlite
*.db
*.log
local-db-dump.sql
private-notes.md
coverage/
dist/
build/
node_modules/
```

## 适合排除

- `.env`、凭据、token、私钥。
- 本地数据库 dump。
- 私人笔记。
- 大型构建产物。
- 生成文件。
- 版权敏感或不该进入上下文的素材。

不建议盲目排除所有 Markdown。很多项目规则、README、设计文档都在 Markdown 里；如果全排除，Gemini CLI 会缺少项目上下文。需要排除文档时，优先排除具体路径，例如 `/private-notes/`，而不是 `*.md`。

monorepo 里要特别小心根目录规则。根 `.geminiignore` 写得过宽，会同时影响多个 package；如果只有某个子项目有敏感 fixture 或私有导出文件，优先在子目录放更窄的规则，或者用锚定路径限制影响范围。

## 和 .gitignore 的区别

| 文件 | 目的 |
| --- | --- |
| `.gitignore` | 不进入 Git |
| `.geminiignore` | 不进入 Gemini CLI 上下文 |

有些文件可以进 Git，但不该让 AI 读；这时用 `.geminiignore`。

| 文件类型 | `.gitignore` | `.geminiignore` |
| --- | --- | --- |
| `.env.local` | 应该排除 | 应该排除 |
| `node_modules/` | 应该排除 | 应该排除 |
| `README.md` | 不应排除 | 通常不应排除 |
| 已提交的测试 fixture | 不应排除 | 视是否含敏感数据 |
| 内部客户案例 | 可能已进 Git | 通常应排除 |

## 常见误区

- 以为 `.geminiignore` 等于安全沙箱。它只是上下文过滤，不是访问控制。
- 修改后不重启会话，然后以为规则无效。
- 只写 `.gitignore`，忘了仓库里仍可能有已跟踪的敏感样例、客户数据或内部文档。
- 在 monorepo 根目录写得过宽，导致子项目的说明文档、schema、测试样例也被排除。
- 把 `.geminiignore` 当作补救手段，而不是先从仓库里移除不该存在的敏感文件。

## 验收方式

重启 Gemini CLI 后，用 `@` 引用一个被排除文件，确认它不会被加入上下文。再让 Gemini CLI 搜索一个只存在于被排除目录里的字符串，确认搜索结果不返回该文件。最后保留一条允许项测试 `!README.md` 这类反向规则是否符合预期。

如果项目开启了多入口规则文件，还要检查 `context.fileName` 指向的文件没有被 ignore 误伤。规则文件、README、schema、测试说明通常是 agent 正确工作的基础，不应该被宽泛规则排除。

## 接下来去哪

<Cards>
  <Card title="Custom commands" description="上下文边界清楚后，继续把重复操作做成项目命令。" href="/docs/gemini-cli/official/02-context-config/24-custom-commands" />
  <Card title="文件管理" description="回看 @ 文件引用、目录上下文和 ignore 的日常用法。" href="/docs/gemini-cli/official/01-cli-workflow/13-file-management" />
  <Card title="Sandbox" description="需要真正限制文件系统和命令执行时，继续看 sandbox。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方来源

- [Gemini CLI .geminiignore](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-ignore.md)
