.claudeignore 是 Claude Code 最被低估的配置文件之一。它做的事情只有一件：告诉 Claude Code 哪些文件和目录不需要放进上下文。但这件事做好了，对效率和质量的提升非常明显。
为什么需要 .claudeignore？
问题：Claude Code 在分析代码库时，会读取文件并把内容放进上下文窗口。每个文件都消耗上下文，不管它对当前任务是否有用。
后果：
- 成本增加：读了大量不相关文件的 token 白白浪费
- 质量下降：上下文被无关内容填满，影响 Claude 对真正重要代码的关注
- 速度变慢：上下文越大，响应越慢
.claudeignore 的作用：精准告诉 Claude 什么文件值得读，什么文件可以忽略。
格式和语法
.claudeignore 放在项目根目录，语法和 .gitignore 完全相同：
# 这是注释
# 忽略整个目录
node_modules/
dist/
build/
# 忽略特定文件类型
*.log
*.map
*.min.js
# 忽略特定文件
.env.production
secrets.json
# 例外：即使父目录被忽略，这个文件仍然包含
!important-config.json
基础模板：适合大多数项目
# 依赖和构建产物（最重要，必须排除）
node_modules/
vendor/
.venv/
venv/
__pycache__/
*.pyc
# 构建输出
dist/
build/
out/
.next/
.nuxt/
target/
*.class
*.jar
# 测试覆盖率和报告
coverage/
.nyc_output/
htmlcov/
test-results/
# 生成的文件
*.min.js
*.min.css
*.bundle.js
*.chunk.js
*.d.ts.map
# 日志和临时文件
*.log
*.tmp
*.cache
.DS_Store
Thumbs.db
# IDE 和编辑器文件
.idea/
.vscode/settings.json
*.swp
*.swo
# 锁文件（通常不需要 Claude 读）
package-lock.json
yarn.lock
pnpm-lock.yaml
poetry.lock
Gemfile.lock
按技术栈的专属配置
Next.js / React
# 构建产物
.next/
out/
*.d.ts
storybook-static/
# 测试
coverage/
playwright-report/
test-results/
# 生成
*.module.css.d.ts
Python / Django / FastAPI
# 虚拟环境
venv/
.venv/
env/
__pycache__/
*.pyc
*.pyo
*.pyd
# Django 特有
staticfiles/
mediafiles/
*.sqlite3
# 测试
htmlcov/
.pytest_cache/
Go
# 构建产物
bin/
pkg/
# 依赖缓存
vendor/ # 如果用 Go modules，vendor/ 通常不需要 Claude 读
Java / Spring Boot
target/
*.class
*.jar
*.war
.gradle/
build/
Rust
target/
Cargo.lock # 可选，取决于是否需要 Claude 分析依赖
进阶策略：按场景动态配置
不同任务需要不同的上下文。可以创建多个 .claudeignore 文件针对不同场景：
策略 1：前端任务时排除后端
在前端工作目录创建 .claudeignore：
# 在 /frontend/ 目录
# 处理前端任务时，排除后端代码
../backend/
../services/
../database/
策略 2：轻量模式和完整模式
轻量 .claudeignore（日常使用）：
# 排除最大的目录
node_modules/
dist/
build/
coverage/
*.log
完整 .claudeignore（深度分析时临时重命名为其他文件）：
# 只保留核心业务代码
node_modules/
dist/
build/
coverage/
*.log
*.test.ts # 先做实现再看测试
*.spec.ts
*.stories.tsx
docs/
什么文件不要排除
一些看起来可以排除但实际上很有价值的文件：
不要排除这些：
*.test.ts/*.spec.ts：测试文件往往包含用法示例和边界情况描述*.md文件：README、文档、CHANGELOG 包含重要上下文package.json（而不是 lock 文件）：依赖列表帮助 Claude 理解技术栈tsconfig.json、.eslintrc：配置文件说明项目规范Makefile、Dockerfile：构建和部署流程
可以有选择地排除：
package-lock.json（lock 文件细节通常不需要）*.min.js（压缩文件）storybook-static/（生成的 Storybook 构建）
实测：.claudeignore 节省多少 Token？
以一个典型的 Next.js 项目为例（有 node_modules，有 dist）：
| 配置 | Claude 能"看到"的文件 | 上下文消耗 |
|---|---|---|
| 没有 .claudeignore | ~50,000+ 文件 | 极高 |
| 基础 .claudeignore | ~500 文件 | 大幅降低 |
| 精细化 .claudeignore | ~100-200 核心文件 | 最低 |
精细化配置后，Claude 把有限的上下文全部花在真正重要的业务代码上，不仅省 Token，分析质量也更高。
组合使用：.claudeignore + Subagents
.claudeignore 排除大量文件，但有时需要临时访问某个被排除的文件怎么办？
不要临时修改 .claudeignore，用 Subagent 处理：
主 Session（有 .claudeignore 过滤）
├── Subagent：临时分析 package-lock.json 里的依赖树
└── 只把结果摘要返回，不把 lock 文件内容带入主 Session
这样主 Session 上下文保持干净，临时需要的信息通过 Subagent 隔离处理。
常见问题
.claudeignore 和 .gitignore 的区别：
.gitignore：Git 不跟踪的文件.claudeignore：Claude 不读取的文件- 两者可以内容相同，但用途不同，建议分开维护
能不能直接用 .gitignore？
Claude Code 会自动尊重 .gitignore，所以已经被 git 忽略的文件通常不会被 Claude 读取。但 .claudeignore 可以额外排除更多你不想让 Claude 看到的文件（比如某些 test fixture 数据，它们在 git 里但不需要 Claude 分析）。
配置完发现某个文件 Claude 找不到了？
检查 .claudeignore 是否误把那个文件或它的父目录排除了。
来源：morphllm.com Claude Code 最佳实践 | Anthropic 官方文档 | 整理：ClaudeEagle