Appearance
Gemini CLI 支持在 GEMINI.md 中使用 @文件路径 语法将内容拆成多个小文件按需组合。Memory Import Processor 自动解析嵌套导入、检测循环引用、限制最大深度（默认 5 层），并对路径进行安全校验。出问题时可查看 /memory show 的导入树定位哪个文件未被加载。
Memory Import Processor（模块化导入）
当 GEMINI.md 文件变得很长时，可以用 @ 语法将内容分散到多个文件，再在主文件中按需引入。Memory Import Processor 负责在运行时将这些引用拼合成一份完整的上下文。
导入语法
在 GEMINI.md 中，每行以 @ 开头后接文件路径即为导入指令：
markdown
# 主 GEMINI.md
这是公共说明。
@./components/style-guide.md
@./components/testing-rules.md代码块内的
@不会被解析：import 处理器会识别代码块（code和反引号行内代码），跳过其中的@行，不会误触发导入。
支持的路径格式
相对路径
| 格式 | 含义 |
|---|---|
@./file.md | 当前目录下的文件 |
@../file.md | 上一级目录 |
@./sub/file.md | 子目录 |
绝对路径
| 格式 | 含义 |
|---|---|
@/absolute/path/to/file.md | 绝对路径（需在允许目录内） |
嵌套导入
被导入的文件本身也可以含有 @ 指令，形成树形结构：
markdown
# main.md
@./header.md
@./content.mdmarkdown
# header.md
@./shared/title.md处理后，main.md 中的 @./header.md 会展开为 header.md 全文（其中 @./shared/title.md 也已递归展开）。
/memory show 会以树形视图显示完整的加载层次，便于调试：
Memory Files
└ project: GEMINI.md
├ style-guide.md
│ └ shared/base-styles.md
└ testing-rules.md
└ shared/jest-config.md安全机制
循环导入检测
处理器维护一个"已访问文件集合"，遇到已处理的文件路径时自动跳过：
markdown
# file-a.md
@./file-b.md
# file-b.md
@./file-a.md ← 检测到循环，跳过此行，不会无限递归最大导入深度
默认最大嵌套深度为 5 层，超出后停止继续深入展开，防止意外构建过深的导入链。
路径安全校验（validateImportPath）
每条导入路径在解析前都经过 validateImportPath 检验：
- 路径必须位于允许目录列表（
allowedDirectories）内 - 禁止通过
../../../等手段逃逸至配置范围之外 - 不符合安全要求的路径会被静默跳过（或写入错误注释）
错误处理
| 错误类型 | 行为 |
|---|---|
| 文件不存在 | 在展开位置插入错误注释，不中断其余内容 |
| 权限不足 | 输出错误提示，跳过该导入 |
| 路径越界 | 安全校验失败，静默跳过 |
| 超过最大深度 | 停止递归，已加载内容正常保留 |
/memory 命令与导入树
bash
/memory show # 显示当前上下文全文（含所有已展开导入）
/memory reload # 强制重新扫描并重载所有 GEMINI.md
/memory add <文本> # 追加文本到 ~/.gemini/GEMINI.md/memory show 输出中，头部会有类似上面的树状结构，显示每个文件的导入来源链，是排查"内容没有被加载"最直接的方法。
实用示例：项目级拆分
以下展示一个典型的大型项目 GEMINI.md 拆分方案：
~/.gemini/GEMINI.md（全局）
markdown
# 全局偏好
@./preferences/code-style.md
@./preferences/commit-message.md项目根目录 GEMINI.md
markdown
# 项目：我的 TypeScript Monorepo
@./docs/architecture.md
@./docs/api-conventions.md
## 特殊说明
本项目使用 Bun 运行时，禁止 Node.js 特有 API。docs/architecture.md
markdown
## 架构概述
采用 Hexagonal Architecture，核心业务逻辑不依赖任何框架。
@./shared/domain-models.md这种分层结构的好处：
- 各模块说明独立维护，互不干扰
- 新成员可以按需阅读对应文件，不必理解全局
- 全局偏好与项目规范分离，工作区切换时自动适配
与 Claude Code /memory 机制对比
| 特性 | Gemini CLI @import | Claude Code CLAUDE.md |
|---|---|---|
| 导入语法 | @./file.md | 无内置导入，通过 /memory add 追加 |
| 结构 | 树形（可调试导入层次） | 平铺线性拼接 |
| 循环检测 | 内置自动检测 | — |
| 最大深度 | 默认 5 层 | — |
| 路径安全 | validateImportPath 检验 | — |
| 调试命令 | /memory show（含树视图） | /memory 命令集 |
最佳实践
- 文件名有意义：
style-guide.md、test-rules.md比part1.md更容易维护 - 保持浅层：建议不超过 3 层嵌套，5 层是上限不是目标
- 文档化结构：在主 GEMINI.md 顶部注释说明每个
@import的用途 - 相对路径优先：绝对路径在跨机器同步时容易失效
- 先验证再部署：新增导入后用
/memory show确认内容已正确展开
常见问题
Q: @ 导入后内容没有出现在 /memory show 里，怎么排查？
A: 按顺序检查：① 文件路径是否拼写正确，cat 确认文件存在；② 路径是否在允许目录内（validateImportPath 校验）；③ 是否超过了 5 层最大深度限制；④ 是否形成循环引用被跳过。运行 /memory show 查看树形输出，找到首个断开的节点。
Q: 可以在 @import 里使用环境变量或通配符吗？
A: 不支持。路径必须是字面字符串（相对或绝对），不支持 glob 模式（@./*.md）和变量展开（@$HOME/rules.md）。如需动态引入，需在外部脚本中生成主 GEMINI.md 再让 CLI 读取。
Q: 如果被导入的文件很大，会影响 Token 用量吗？
A: 会。所有展开后的内容都会作为系统上下文随每次请求发送，Token 用量与最终拼合文本的长度成正比。建议定期用 /memory show 检查上下文大小，删除不再需要的导入。