Claude Code文件过滤深度对比：.claudeignore vs permissions.deny

想象一下，当你习惯性地在 Home 目录下启动 Claude Code，然后执行 git status——结果屏幕上刷刷刷列出了一长串目录：.ssh/、.gnupg/、.config/、.cache/、node_modules/、anaconda3/…… 一眼望不到头，上百个文件夹扑面而来。这不仅是视觉上的冲击，更是实实在在的效率灾难。没有文件过滤机制，Claude Code 会无差别地扫描所有内容，包括那些根本不需要关注的缓存、日志和媒体文件。后果是什么？

首先是 Token 的惊人浪费。Claude 的上下文窗口是有限的，大量无关内容被灌入，真正有用的代码反而被挤占。其次，响应速度断崖式下跌——因为文件搜索和代码分析需要遍历海量无关目录。更致命的是安全风险：.ssh/、.env、.gnupg/ 这些敏感文件可能就这样暴露在对话中，成为信息泄露的隐患。最后，搜索结果里掺杂着 node_modules 和 build 产物，噪声干扰让工作效率大打折扣。一个真实的教训是：在 Home 目录下做一次简单的 Grep 搜索，可能因为扫描 anaconda3/（动辄数 GB）和 node_modules/ 而直接超时。

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

这种场景并非危言耸听。当 Claude Code 启动时，如果没有任何过滤机制，它会尝试了解整个工作目录树。坦白说，这种情况下的表现基本可以概括为：效率低下、响应迟缓、充满隐患。好在，Claude Code 提供了一套相当完整的分层过滤体系，从被动约束到主动防御，层层递进。

二、Claude Code 的文件过滤体系

这套体系从源头到终端，分为四个层级，清晰地解决了不同维度的问题。

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

Layer 1：.gitignore — 默认防线

Claude Code 默认会尊重 .gitignore 规则，这由 respectGitignore 设置控制（默认是 true）。也就是说，只要你的项目配置了 .gitignore，里面列出的文件就不会出现在文件建议和搜索结果中。这是最基础的过滤，但有一个明显软肋：它只对 Git 仓库生效。如果你在 Home 目录工作，而这个目录本身不是标准项目仓库，那么 .gitignore 的覆盖范围基本等于零。

Layer 2：.claudeignore — 软过滤

这是更主动的手段。.claudeignore 的语法与 .gitignore 完全一致，可以放在项目根目录或 Home 目录下。它的作用是影响 Claude Code 的文件发现和主动扫描行为。举个例子，如果你在 ~/.claudeignore 中配置：

node_modules/
.cache/
*.log

Claude 在主动探索时就会跳过这些目录。但必须理解的是，这是一个**软过滤**——它只阻止 Claude 主动扫描，并不阻止直接读取。如果你明确说“帮我读一下这个文件”，它还是可以读到。适用场景很简单：减少噪声、节省 Token、提高搜索效率。

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

这是官方文档强烈推荐的方式。配置在 settings.json 中，写法如下：

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

permissions.deny 是真正的硬过滤：匹配的文件不仅从发现中排除，读取操作也会被直接拒绝。哪怕你明确要求 Claude 去读，它也读不到。与 .claudeignore 相比，这层防护更加彻底，是保护敏感数据的最后一道闸门。

配置文件的位置和优先级也很有讲究。从高到低分别是：组织级（managed-settings.json，由管理员下发）、项目本地（.claude/settings.local.json，不应提交到 Git）、项目共享（.claude/settings.json，可提交到 Git）、用户全局（~/.claude/settings.json）。多个层级的 permissions.deny 数组会拼接去重，而不是简单的覆盖。

Layer 4：文件系统沙箱

这是 Claude Code 内置的最后一道安全边界：它只能写入启动目录及其子目录，可以读取启动目录之外的文件（比如系统库），但无法修改父目录中的文件。这算是一种兜底保护，确保即使前面的策略失效，也不会造成系统级的破坏。

三、.claudeignore 实战配置

全局配置（~/.claudeignore）

如果你习惯在 Home 目录工作，一个全局 .claudeignore 能极大改善体验：

# ============ 运行时与包管理 ============
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 无法阻止直接读取。对于真正敏感的文件——比如 .env、.env.*、.ssh/**、.gnupg/**、**/credentials*、**/secret*——必须使用 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 没必要去读取压缩后的代码。

六、配置前后对比

七、总结

Claude Code 的文件过滤并不是单一机制，而是一个分层体系。每个层次各司其职：

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

对于绝大多数开发者来说，.claudeignore + permissions.deny 双管齐下是最实用也最稳妥的组合。前者让 Claude 更快更省，后者让 Claude 更安全。从今天开始，花几分钟配置好这层防护，你会发现工作效率和安全性都会上一个台阶。

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