Claude Code 文件过滤完全指南：从 .claudeignore 到 permissions.deny

当你的 Home 目录有上百个文件夹时，Claude Code 会扫描所有内容，消耗大量 Token 并可能暴露敏感信息。本文深入讲解 Claude Code 的文件过滤机制，帮你构建安全高效的开发环境。

一、问题：没有文件过滤会怎样？

在 Home 目录下启动 Claude Code，执行 git status 后你可能看到这样的场景：

## .ssh/
## .gnupg/
## .config/
## .cache/
## node_modules/
## anaconda3/
## Library/
## Movies/
## Downloads/
... 上百个目录

没有文件过滤意味着：

问题	影响
Token 浪费	Claude 索引无关文件（缓存、日志、媒体），快速消耗上下文窗口
响应变慢	文件搜索和代码分析需要遍历大量无关目录
安全风险	`.ssh/`、`.env`、`.gnupg/` 等敏感文件可能被读取并出现在对话中
噪声干扰	搜索结果混入 `node_modules`、`build` 产物等无关内容

一个真实的案例：在 Home 目录工作时，一次简单的 Grep 搜索可能因为扫描 anaconda3/（数 GB）和 node_modules/ 而超时。

[图片上传失败...(image-50a94a-1774924282902)]

二、Claude Code 的文件过滤体系

Claude Code 提供了多层文件过滤机制，从被动到主动：

┌─────────────────────────────────────────┐
│  Layer 1: .gitignore（自动生效）          │
├─────────────────────────────────────────┤
│  Layer 2: .claudeignore（软过滤）         │
├─────────────────────────────────────────┤
│  Layer 3: permissions.deny（硬过滤）      │
├─────────────────────────────────────────┤
│  Layer 4: filesystem sandbox（系统级）    │
└─────────────────────────────────────────┘

[图片上传失败...(image-863efc-1774924282902)]

Layer 1：.gitignore — 默认防线

Claude Code 默认尊重 .gitignore，由 respectGitignore 设置控制（默认 true）。这意味着 .gitignore 中列出的文件不会出现在文件建议和搜索结果中。

局限性：.gitignore 只在 Git 仓库中生效。如果你在 Home 目录工作且它不是一个标准的项目仓库，.gitignore 的覆盖范围有限。

Layer 2：.claudeignore — 软过滤

.claudeignore 的语法与 .gitignore 完全一致，放在项目根目录或 Home 目录下。它影响 Claude Code 的文件发现和主动扫描行为。

# ~/.claudeignore
node_modules/
.cache/
*.log

关键理解：.claudeignore 是一个"软过滤"——它让 Claude 在主动探索时跳过这些文件，但不阻止直接读取。如果你明确要求 Claude 读取一个被忽略的文件，它仍然可以读到。

适用场景：减少噪声、节省 Token、提高搜索效率。

Layer 3：permissions.deny — 硬过滤（官方推荐）

这是 Claude Code 官方文档推荐的方式，配置在 settings.json 中：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

与 .claudeignore 的关键区别：permissions.deny 是硬过滤——匹配的文件不仅从发现中排除，读取操作也会被直接拒绝，即使你明确要求 Claude 去读。

配置文件位置及优先级（从高到低）：

范围	文件路径	是否共享
组织级	`managed-settings.json`	由管理员统一下发
项目本地	`.claude/settings.local.json`	否（应 gitignore）
项目共享	`.claude/settings.json`	是（提交到 Git）
用户全局	`~/.claude/settings.json`	否

合并规则：多个层级的 permissions.deny 数组会拼接去重，而非覆盖。

Layer 4：文件系统沙箱

Claude Code 内置的安全边界：

只能写入启动目录及其子目录
可以读取启动目录之外的文件（如系统库）
无法修改父目录中的文件

三、.claudeignore 实战配置

全局配置（~/.claudeignore）

适合在 Home 目录工作的开发者：

# ============ 运行时与包管理 ============
node_modules/
.npm/
.nvm/
.bun/
anaconda3/
.cache/
.continuum/

# ============ IDE 与编辑器 ============
.vscode/
.vscode-insiders/
.cursor/
.jetbrains/
.windsurf/
.trae/

# ============ 系统与应用数据 ============
Library/
.Trash/
.docker/
.kube/
.orbstack/
Movies/
Music/
Pictures/
Downloads/

# ============ 构建缓存 ============
.gradle/
.m2/
.gem/
.rvm/
.cocoapods/

# ============ 敏感信息（建议配合 permissions.deny） ============
.ssh/
.gnupg/
.config/

# ============ 历史记录 ============
.bash_history
.zsh_history
.python_history

项目级配置（项目根目录/.claudeignore）

# 构建产物
dist/
build/
.next/
out/

# 依赖
node_modules/

# 测试覆盖率
coverage/
.nyc_output/

# 生成文件
*.generated.ts
prisma/generated/

# 大型数据文件
data/*.csv
data/*.sql
fixtures/large/

四、最佳实践：分层防御策略

单靠一种机制不够，推荐组合使用：

1. 效率层：.claudeignore 过滤噪声

把不需要 Claude 索引的大目录放进 .claudeignore，这是最简单有效的 Token 节省手段。

2. 安全层：permissions.deny 保护敏感文件

.claudeignore 无法阻止直接读取。对于真正的敏感文件，必须使用 permissions.deny：

// ~/.claude/settings.json（全局生效）
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.ssh/**)",
      "Read(./.gnupg/**)",
      "Read(./**/credentials*)",
      "Read(./**/secret*)"
    ]
  }
}

3. 团队层：共享项目设置

将团队通用规则放入 .claude/settings.json 并提交到 Git：

// .claude/settings.json（团队共享）
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

个人偏好放入 .claude/settings.local.json（已被 gitignore）。

五、开发技巧

技巧 1：按项目类型定制 .claudeignore

前端项目重点排除：

node_modules/
dist/
.next/
storybook-static/
coverage/

Python 项目重点排除：

__pycache__/
*.pyc
.venv/
venv/
*.egg-info/
.tox/

Monorepo 只保留当前工作的包：

# 排除不相关的子项目
packages/legacy-app/
packages/deprecated-service/
apps/internal-tool/

技巧 2：临时排除大文件

在探索陌生项目时，先查看哪些目录最大：

du -sh */ .* 2>/dev/null | sort -rh | head -20

然后把前几个大目录加入 .claudeignore，立刻提升响应速度。

技巧 3：用 permissions.deny 做"只读防护墙"

对于生产配置目录，阻止写入但允许读取：

{
  "permissions": {
    "deny": [
      "Edit(./infrastructure/**)",
      "Write(./infrastructure/**)"
    ]
  }
}

这样 Claude 可以参考基础设施配置来回答问题，但不会意外修改它。

技巧 4：调试文件过滤是否生效

用以下方式验证：

# 在 Claude Code 中尝试搜索被忽略的文件
> 搜索 .ssh 目录下的文件

# 如果 .claudeignore 生效，搜索结果中不会出现这些文件
# 如果 permissions.deny 生效，直接读取会被拒绝

技巧 5：生成文件和锁文件的处理

package-lock.json、pnpm-lock.yaml 等锁文件通常很大但偶尔需要 Claude 分析依赖问题。不建议加入 .claudeignore。

而 generated/、*.min.js 等真正的生成文件可以安全忽略——Claude 无需读取压缩后的代码。

六、配置前后对比

指标	未配置	配置后
文件搜索速度	可能超时（扫描数 GB 缓存）	秒级返回
单次搜索 Token 消耗	高（包含无关结果）	低（精准匹配）
敏感文件暴露风险	.ssh、.env 可被读取	permissions.deny 硬拦截
上下文窗口利用率	被噪声稀释	聚焦于实际工作文件
团队协作一致性	每人各自配置	.claude/settings.json 统一规则

七、总结

Claude Code 的文件过滤不是单一机制，而是一个分层体系：

.claudeignore 解决效率问题——减少噪声，节省 Token
permissions.deny 解决安全问题——硬性拦截敏感文件读取
.gitignore 提供基础覆盖——自动生效，无需额外配置
文件系统沙箱 提供兜底保护——限制写入范围

对于大多数开发者，.claudeignore + permissions.deny 双管齐下是最实用的组合。前者让 Claude 更快更省，后者让 Claude 更安全。

本文基于 Claude Code 2026 年 3 月的文档和实践整理。配置细节可能随版本更新变化，请以官方文档为准。

2026.03.31 08:55
沪 · 赵巷

📌 声明：本文由 AI 辅助完成

Claude Code 文件过滤完全指南：从 .claudeignore 到 permissions.deny