Appearance
.kiroignore 是 Kiro 提供的文件屏蔽机制，采用与 .gitignore 完全相同的语法，用于阻止 AI Agent 读取指定文件。适用场景包括：屏蔽 .env 等凭证文件、排除构建产物以减少 AI 上下文干扰、满足团队合规要求。支持项目级配置和全局配置两种模式，可与 .gitignore 同时启用。
Kiro IDE .kiroignore：保护敏感文件不进入 AI 上下文
.kiroignore 文件用于告诉 Kiro 的 AI Agent：哪些文件不应该被读取。无论是 API 密钥、数据库凭证，还是你不希望发送给外部服务的私密内容，都可以通过这个机制排除在外。
为什么需要 .kiroignore
| 场景 | 说明 |
|---|---|
| 安全 | 防止含有凭证、API Key 等敏感数据的文件被 AI 读取 |
| 隐私 | 将机密信息排除在 AI 交互上下文之外 |
| 合规 | 确保不向外部服务传输不该共享的文件内容 |
| 聚焦 | 排除构建产物和大型数据文件，让 AI 上下文更精准 |
项目级配置
在项目根目录（或任意子目录）创建 .kiroignore 文件，按需添加屏蔽规则：
# 凭证与密钥
.env
.env.*
!.env.example
*.pem
*.key
# 私有目录
secrets/
private/创建文件后，还需要在设置中启用它：
- 打开 Settings（Mac：
Cmd+,，Windows/Linux：Ctrl+,） - 搜索 Agent Ignore Files（设置项：
kiroAgent.agentIgnoreFiles） - 将
.kiroignore添加到数组中
完成后，Kiro 会自动跳过所有匹配规则的文件。
设置选项说明
kiroAgent.agentIgnoreFiles 接受文件名数组，常见用法：
- 同时启用多种忽略文件：
[".gitignore", ".kiroignore"] - 设为
[]可禁用所有项目级 ignore 文件
子目录 ignore 文件
与 .gitignore 一样，可以在子目录中放置 .kiroignore 来覆盖或扩展父目录的规则。子目录内的规则对该目录下的文件优先生效。
全局 ignore 文件
以下全局 ignore 文件无需额外配置，Kiro 会自动识别：
~/.kiro/settings/kiroignore— 作用于所有项目的全局规则- Git 的全局 ignore 文件（通过
core.excludesfile配置）— 仅在 Git 仓库中生效
全局文件适合存放你希望在所有项目中都排除的模式，比如操作系统生成的临时文件、个人工具配置等。
语法规则
.kiroignore 使用标准 gitignore 语法：
| 模式 | 效果 |
|---|---|
file.txt | 忽略指定文件 |
*.log | 按扩展名忽略 |
folder/ | 忽略整个目录 |
**/temp | 忽略任意子目录中的 temp |
!keep.txt | 不忽略（取反规则） |
配置示例
保护 API Key 和密钥文件
# 各环境配置文件
.env
.env.local
.env.production
# 保留模板文件可访问
!.env.example
# 证书和密钥文件
*.pem
*.key
*.p12
credentials/排除构建产物和数据文件
# 构建输出
dist/
build/
.next/
# 数据文件
*.sql
*.dump
data/exports/团队合规场景
# 客户数据目录
customer-data/
pii/
# 内部审计文档
compliance/internal/
audit-reports/最佳实践
- 用注释说明原因：注明为什么忽略某类文件，方便团队成员理解
- 验证规则生效：让 Kiro 读取一个被忽略的文件，它会提示访问被拦截
- 定期审查模式：项目结构变化后，回顾 ignore 规则是否还适用
- 与团队对齐全局规则：统一全局 ignore 配置，确保跨 workspace 行为一致
常见问题
Q：.kiroignore 和 .gitignore 的区别是什么？
A：.gitignore 控制哪些文件不提交到 Git 仓库；.kiroignore 控制哪些文件不被 Kiro AI Agent 读取。两者语法相同，但作用层面不同，可以同时配置。如果你在 kiroAgent.agentIgnoreFiles 中加入 .gitignore，Kiro 也会遵守 .gitignore 中的规则。
Q：.kiroignore 能阻止 Kiro 索引文件内容吗？
A：是的，.kiroignore 中列出的文件不会被 Agent 读取，也不会出现在 AI 的上下文中。但 Kiro 的 Codebase Indexing 功能是否受此影响，建议查阅最新版文档确认。
Q：如果既有全局 ignore，又有项目级 ignore，规则如何合并？
A：两者同时生效，取并集。全局规则覆盖所有项目，项目级规则只对当前项目有效。子目录中的 ignore 文件对该子目录优先生效，可以用取反规则（!）显式解除父级忽略。