---
title: "文件系统工具"
description: "Gemini CLI 文件系统工具的使用边界：读取、搜索、写入、替换、diff 确认、.geminiignore 和敏感文件排除。"
verifiedAt: "2026-05-09"
---

文件系统工具让 Gemini CLI 能看到真实项目。它可以读取、搜索、写入和替换文件，但写操作必须更谨慎。

> [!WARNING]
> 文件系统工具的风险取决于当前目录。进入 repo 根目录、home 目录、下载目录，工具能看到的范围完全不同。

所有文件系统工具都运行在 `rootDirectory` 之内，也就是当前工作目录或 workspace root。这个边界很重要：你进入哪个目录，Gemini CLI 看到的项目范围就从哪里开始。

## 常见能力

- 列目录。
- 搜索文件。
- 读取文件。
- 写新文件。
- 替换局部内容。
- 展示 diff。

## 工具分工

- `list_directory`：列出某个目录下的文件和子目录，适合第一次探索项目。
- `read_file`：读取指定文件，支持 offset 和 limit，适合读取长文件的一部分。
- `glob`：按 pattern 找文件，默认尊重常见忽略规则，适合不知道具体路径时先定位。
- `grep_search`：按正则搜索文本，适合查符号、配置项、错误信息。
- `write_file`：创建或覆盖文件，属于写操作，必须确认。
- `replace`：精确替换文件中的一段文本，默认要求只匹配一次，适合小范围补丁。

官方工具名在不同 UI 和实现层里可能显示为 `read_file`、`write_file`、`glob`、`search_file_content`、`replace`、`list_directory`。写教程时建议同时写“用户看到的动作”和“官方工具名”，否则读者排查日志、policy 或 MCP 输出时会对不上。

几个细节要特别说明：`write_file` 会在确认前展示 diff；`replace` 需要 `old_string` 足够唯一，必要时用 `expected_replacements` 控制替换次数；`read_file` 可读取文本指定行段，图片和 PDF 会按工具能力转成可处理内容，其他二进制类型可能被跳过或截断。

## 推荐顺序

真实项目里不要先写文件。更稳的顺序是：先 `list_directory` 看结构，再用 `glob` / `grep_search` 定位目标，再 `read_file` 读取相关上下文，最后才考虑 `replace` 或 `write_file`。

`replace` 比整文件覆盖更适合维护型修改，因为它要求提供明确旧文本和新文本。批量替换前要让 Gemini CLI 说明会匹配几处，避免误改相似片段。

| 动作 | 风险 | 推荐控制 |
| --- | --- | --- |
| `list_directory` / `glob` | 暴露目录结构 | 在正确项目目录启动 |
| `grep_search` | 暴露匹配内容 | 先配置 `.geminiignore` |
| `read_file` | 读取敏感文件 | 限定具体路径和范围 |
| `replace` | 误改相似文本 | 要求唯一匹配和 diff |
| `write_file` | 覆盖或新增文件 | 先说明路径、内容和原因 |

## 安全做法

1. 第一次只读。
2. 修改前要求它说明影响文件。
3. 每次只授权小范围改动。
4. 看 diff。
5. 跑测试。
6. 敏感文件放进 `.geminiignore`。

## 不该读取的文件

```text
.env
*.pem
*.key
local-db-dump.sql
customer-data/
```

## 多文件读取边界

批量读取不是简单传一个目录。官方 `read_many_files` 要求使用文件路径或 glob pattern，例如 `docs/*.md`、`src/**/*.ts`；只传目录路径通常得不到你以为的完整内容。读取图片、PDF、音频、视频这类文件时，最好显式写文件名或扩展名。

默认排除规则会过滤 `node_modules`、`.git` 和常见二进制文件；`respect_git_ignore` 默认会尊重 `.gitignore`。如果教程要让读者复现“读取整个项目上下文”，必须写清 include/exclude pattern，不能只说“让 Gemini 读项目目录”。

## 验收方式

文件系统工具的验收不只看“模型说改好了”。至少要看 diff、确认写入文件属于本次任务范围，并运行对应检查命令。多 agent 并发时，每批写入前后都要检查 `git status --short <目标目录>`，防止覆盖别人正在改的文件。

## 接下来去哪

<Cards>
  <Card title="Shell 工具" description="文件读写之后，继续看如何安全执行测试和脚本。" href="/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title=".geminiignore" description="敏感文件和生成文件要先从上下文中过滤掉。" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="Sandbox" description="需要真正限制文件系统访问时，继续看 sandbox。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方来源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
