Appearance
Gemini CLI 的文件管理能力是日常开发的核心：用 @文件路径 直接把文件内容注入 AI 上下文，支持多文件、整个目录；让 AI 自动找到你不知道路径的文件；通过 diff 预览再确认的方式安全修改代码；用 .geminiignore 把 .env、私有数据等敏感文件隔离在 AI 视野之外。本页是文件操作的完整指南。
文件管理
Gemini CLI 让你可以把文件和整个代码库的内容注入 AI 的对话上下文，精准指导 AI 理解和修改你的项目。
前置条件
- Gemini CLI 已安装并完成认证，参见 安装指南
- 有一个项目目录可以操作（推荐 git 仓库）
用 @ 注入文件内容
指定单个文件
知道文件路径时，用 @ 符号强制 AI 立即读取并注入文件内容：
@src/components/UserProfile.tsx 解释这个组件如何处理用户数据。同时引用多个文件
复杂功能通常涉及多个文件，可以链式引用：
@src/components/UserProfile.tsx @src/types/User.ts 将组件重构为使用最新的 User 接口。引用整个目录
大范围问题或重构时，可以引用整个目录（注意大目录会消耗更多 Token）：
@src/utils/ 检查这些工具函数中是否有已废弃的 API 用法。探索陌生代码库
不知道文件在哪里？让 AI 帮你找：
场景：找到组件定义
你知道有一个 UserProfile 组件，但不知道它在哪里：
找到定义 UserProfile 组件的文件。AI 使用 glob 或 list_directory 工具搜索项目结构，返回具体路径（如 src/components/UserProfile.tsx），你可以在下一个 Prompt 中直接用 @ 引用它。
也可以搜索文件列表：
列出根目录下所有的 TypeScript 配置文件。修改代码
给了 AI 上下文之后，可以让它做具体修改：
更新 @src/components/UserProfile.tsx，当 user 数据为 null 时显示 loading spinner。AI 使用 replace 工具提出针对性的代码改动（不是无差别覆写整个文件）。
创建新文件
也可以让 AI 创建全新的文件或目录结构：
创建一个新文件 @src/components/LoadingSpinner.tsx，用 Tailwind CSS 实现简单的 spinner。AI 使用 write_file 工具从头生成文件。
审查并确认修改
Gemini CLI 以安全优先。在修改任何文件前，它都会展示一个统一格式的 diff：
diff
- if (!user) return null;
+ if (!user) return <LoadingSpinner />;- 红色行（-）：将被删除的代码
- 绿色行（+）：将被添加的代码
按 y 确认并写入磁盘，按 n 取消并重新描述需求。
验证修改结果
修改完成后验证一下：
运行 UserProfile 组件的测试。AI 用 run_shell_command 执行你的测试工具（如 npm test 或 jest），确保改动没有破坏已有功能。
控制 AI 的可见范围
.gitignore 自动生效
Gemini CLI 默认遵守 .gitignore，不会读取或搜索 node_modules、构建产物或其他被忽略的路径。
.geminiignore：更精细的控制
想把某些文件对 AI 隐藏，但又不想加进 .gitignore（比如 .env、本地数据库备份），可以创建 .geminiignore 文件：
text
.env
local-db-dump.sql
private-notes.md这些文件 AI 既不会读取也不会搜索，但 git 仍然可以追踪它们。
下一步
- 了解如何持久化 AI 的项目知识：内存管理教程
- 结合 Shell 命令自动运行测试：Shell 命令教程
- 查阅文件系统工具的高级参数（权限、编码等）
常见问题
Q: @ 引用和直接告诉 AI "读取这个文件"有什么区别？
A: @路径 是强制立即注入——AI 会在你的 Prompt 被处理前先读取文件。直接描述（"请读取 src/foo.ts"）让 AI 自己决定何时读取，可能在对话深入后才执行。对于需要精确上下文的操作，推荐用 @。
Q: 引用大型目录会有问题吗？
A: 大目录（如 @src/）会消耗大量 Token，可能超出上下文窗口限制。建议指向更具体的子目录，或先用 find 命令让 AI 找到相关文件，再精准 @ 引用。
Q: .geminiignore 和 .gitignore 的格式一样吗？
A: 是的，.geminiignore 使用与 .gitignore 相同的 glob 语法，放在项目根目录下即可生效。