.claudeignore 是 Claude Code 的文件排除配置，控制哪些文件不会被 AI 读取。
正确配置它可以保护隐私、提升性能、减少 AI 被无关代码干扰。
为什么需要 .claudeignore？
Claude Code 在分析项目时会扫描目录中的文件。默认情况下，它会读取：
- 所有源代码文件
- 配置文件
- 文档
- 包括你可能不想让它看到的东西
需要排除的常见情况：
.env文件中的 API Key 和数据库密码node_modules/等依赖目录（大量无关文件降低性能）- 构建产物（
dist/、build/） - 大型二进制文件或数据集
语法规则
.claudeignore 与 .gitignore 语法完全一致，学过 Git 就会用：
# 注释以 # 开头
# 忽略特定文件
.env
.env.local
secrets.json
# 忽略整个目录
node_modules/
dist/
build/
.next/
__pycache__/
# 通配符
*.log
*.pyc
*.min.js
# 忽略特定路径下的文件
src/generated/
data/raw/
# 取反（不忽略）
!src/generated/types.ts
项目类型最佳实践
Node.js / TypeScript 项目
# 依赖和构建产物
node_modules/
dist/
build/
.next/
.nuxt/
out/
# 环境变量（包含密钥）
.env
.env.local
.env.*.local
# 测试覆盖率报告
coverage/
.nyc_output/
# 日志
*.log
npm-debug.log*
# 包管理器缓存
.pnpm-store/
.yarn/cache/
Python 项目
# 虚拟环境
venv/
.venv/
env/
.env/
# 编译文件
__pycache__/
*.py[cod]
*.pyo
*.so
# 构建
dist/
build/
*.egg-info/
# 数据文件（通常很大）
data/raw/
data/processed/
*.csv
*.parquet
# 模型文件
models/
*.pkl
*.joblib
*.h5
Go 项目
# 编译产物
*.exe
*.exe~
bin/
# 依赖缓存
vendor/
# 测试缓存
.testcache/
单体仓库（Monorepo）
# 所有包的依赖
**/node_modules/
**/dist/
**/.next/
# 只让 Claude 看特定包
# 在特定包目录运行 Claude，或用 --add-dir 指定
# 大型资产目录
packages/assets/
apps/mobile/android/
apps/mobile/ios/
文件存放位置
.claudeignore 放在项目根目录，与 .gitignore 同级：
my-project/
├── .claudeignore ← 放这里
├── .gitignore
├── src/
├── package.json
└── ...
Claude Code 会自动检测并应用。
.claudeignore vs .gitignore 的区别
| 对比 | .gitignore | .claudeignore |
|---|---|---|
| 作用 | Git 不追踪的文件 | Claude 不读取的文件 |
| 语法 | 相同 | 相同 |
| 典型排除 | 构建产物、依赖 | 密钥、大型数据、生成代码 |
| 是否需要两个 | 是，各司其职 | 可以互补 |
两个文件都建议配置，.gitignore 排除不需要版本控制的文件，
.claudeignore 排除不应该让 AI 看到的文件（范围可能不同）。
验证排除规则
bash
# 在项目目录启动 Claude Code 后
claude
# 让 Claude 列出它能看到的文件
你：请列出这个项目中你能访问到的文件列表
# 确认敏感文件（如 .env）不在列表中也可以直接测试：
bash
# 查看 .claudeignore 是否影响到特定文件
claude "你能读取 .env 文件吗？"
# 如果配置正确，Claude 会说找不到该文件性能提升效果
在一个 Node.js 项目中添加 .claudeignore 排除 node_modules/ 后：
- 上下文大小减少 90%+（node_modules 通常占项目文件总量的绝大部分）
- 首次分析速度提升明显
- Claude 的回复更聚焦（不会被依赖库代码干扰）
来源：Claude Code 官方文档 - docs.anthropic.com/en/docs/claude-code