---
title: "文件管理"
description: "Gemini CLI 文件管理：@ 文件引用、目录上下文、查找文件、修改文件、创建文件、diff 确认和 .geminiignore。"
verifiedAt: "2026-05-09"
---

Gemini CLI 可以自己探索项目，也可以通过 `@` 显式读取你指定的文件或目录。文件管理是它从“聊天”变成“agent”的关键能力，也是最容易越界的地方：读错文件会误判，改错文件会制造无关 diff。

> [!IMPORTANT]
> **先只读，再修改**：第一次接入项目时，先让它解释文件结构；确认读对以后，再授权编辑。

## 1. 显式读取文件

单文件示例：`@src/components/UserProfile.tsx 解释这个组件如何处理用户数据。`

多个文件可以一起给：

`@src/components/UserProfile.tsx @src/types/User.ts 检查这两个文件的类型关系。`

目录也可以给：

`@src/utils/ 检查这些工具函数是否还有 deprecated API。`

显式引用适合你已经知道路径的情况。它的优势是范围明确；缺点是你可能漏掉相关文件。因此复杂问题可以先让 Gemini CLI 读结构，再由你确认要引用哪些文件。

## 2. 让它自己找文件

不知道路径时，不要乱猜：

可以直接问：`Find the file that defines the UserProfile component.`

Gemini CLI 会用目录列表、glob 等工具探索项目结构，再返回可能路径。

## 3. 修改和创建文件

修改文件：

`Update @src/components/UserProfile.tsx to show a loading spinner if user data is null.`

创建文件：

`Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.`

修改前它会展示 unified diff。你要看清楚再确认。

> [!WARNING]
> **不要一次授权整个目录重写**：让它修改多个文件前，先要求输出文件清单、每个文件为什么要改、预期验证命令。没有清单的大范围改动，不适合直接确认。

## 4. .geminiignore

Gemini CLI 默认尊重 `.gitignore`。如果有些文件不想暴露给 AI，但不适合放进 `.gitignore`，可以用 `.geminiignore`：

常见排除项包括 `.env`、`local-db-dump.sql`、`private-notes.md`。

`.geminiignore` 适合排除本地敏感材料、临时数据、数据库 dump、客户资料和私有笔记。它不应该代替凭据管理；真正的密钥仍然不能放在项目目录里等工具来“忽略”。

## 5. 工具分工

显式 `@file` 适合你已经知道路径的情况。路径不确定时，让 Gemini CLI 先列目录、搜索名称或搜索内容；读单个文件和批量读上下文是两种不同动作；修改优先做精确替换，只有新建文件或整体重写时才适合完整写入。

```mermaid
flowchart TD
    Task["文件任务"] --> Known{"知道路径?"}
    Known -->|是| At["@file 精确引用"]
    Known -->|否| Search["先搜索文件和目录"]
    At --> Read["只读解释"]
    Search --> Read
    Read --> Plan["修改计划"]
    Plan --> Edit["限定文件编辑"]
    Edit --> Diff["看 unified diff"]
    Diff --> Test["跑最小验证"]

    style Read fill:#dcfce7,stroke:#22c55e
    style Edit fill:#fef3c7,stroke:#f59e0b
    style Diff fill:#dbeafe,stroke:#3b82f6
```

## 6. 安全顺序

1. 只读解释目录。
2. 指定单文件解释。
3. 让它提出修改计划。
4. 只授权一个小文件修改。
5. 看 diff。
6. 跑测试。

## 7. 验收方式

编辑文件前，要求 Gemini CLI 先说清它准备读哪些文件和为什么读。编辑后检查 unified diff、运行项目测试或最小验证命令。涉及 `.geminiignore` 的项目，再验证被排除文件不会通过 `@` 或搜索进入上下文。

## 8. 接下来去哪

<Cards>
  <Card title="Shell 命令" description="文件能读写以后，继续看如何让 Gemini CLI 安全运行测试和脚本。" href="/docs/gemini-cli/official/01-cli-workflow/14-shell-commands" />
  <Card title="GEMINI.md" description="反复出现的项目规则不要每次 prompt 复制，继续沉淀到上下文文件。" href="/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="gemini ignore" description="继续看哪些文件应该排除在 AI 上下文之外。" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
</Cards>

## 官方来源

- [Gemini CLI file management tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/file-management.md)
- [Gemini CLI file system tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/file-system.md)
