1. 为什么 Claude Code 需要 claude-ignoreClaude Code 在本地项目里跑起来之后最让人心里发毛的不是它写错代码而是它太勤快——你让它改一个登录逻辑它顺手把.env、config/secrets.json、node_modules里的东西全读了一遍。上下文被塞满不说密钥、连接串、内部地址这些不该进模型的东西也跟着进去了。.gitignore管的是 git 提交管不了 Claude Code 读文件。所以社区里出现了claude-ignore这个工具它本质是一个 Claude Code 的PreToolUse 钩子在 Claude 调用Read工具之前先拦一道如果目标路径命中.claudeignore里的模式就直接以退出码 2 阻止这次读取。工作方式跟.gitignore很像但作用点是读文件这个动作。它适合谁三类人最需要一是本地项目里放了.env、证书、私钥的开发者二是 monorepo 里子目录规则不一样、想分层忽略的团队三是单纯嫌 Claude 读太多无关文件、想省 token 和上下文的人。这篇就把.claudeignore的写法、settings.json里 PreToolUse 钩子的骨架、以及用 TaoToken 统一 Key 接入的步骤串起来最后用 npm 脚本验证忽略规则到底有没有生效。2. 用 TaoToken 统一 Key 接入 Claude Code在配钩子之前先把模型入口理顺。Claude Code 默认走 Anthropic 官方端点但很多团队希望用一个统一的 Key 管理所有 AI 调用TaoToken 就是干这个的——它提供一个兼容 Anthropic 协议的 API 入口你拿一个 Key 就能在 Claude Code、脚本、其他工具里复用。先注册并拿到 Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key复制出来。这个 Key 就是后面所有配置里要填的东西。Claude Code 通过环境变量识别端点通常设置这两个export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥注意ANTHROPIC_BASE_URL用https://taotoken.net/api不要带 UTM 参数那是给网页链接用的API 端点保持干净。如果你不想每次开终端都 export可以写进~/.zshrc或~/.bashrc或者用 direnv 按项目加载。提示Key 不要硬编码进settings.json提交到仓库。环境变量或本地.env且.env本身在.claudeignore里才是正确姿势。配好之后可以先跑一次模型对话验证 Key 通不通https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 能正常返回就说明入口没问题。如果你后面要长期跑编码任务或 Agent可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按用量规划更省心。3. 安装 claude-ignore 并写 .claudeignore工具本身是个 npm 包全局装一次就能在所有项目里用npm install -g claudeignore装完确认一下命令在不在claude-ignore --version接下来在项目根目录初始化。推荐用自动配置cd your-project claude-ignore init这个命令做三件事如果项目里没有.claudeignore就从模板创建一个如果.claude/settings.json不存在就写入带钩子的配置如果settings.json已存在它不会覆盖而是把模板配置打印出来让你手动合并——这点很重要避免把你已有的钩子冲掉。.claudeignore的语法是 gitignore 风格支持#注释和空行。一个典型的本地项目可以这样写# 环境与密钥 .env .env.* *.secret *.pem *.key # 依赖与构建产物 node_modules/ dist/ build/ .next/ # 日志与本地数据 *.log logs/ tmp/ .cache/ # 编辑器与系统文件 .vscode/ .idea/ .DS_Store分层是它的核心特性Claude Code 从当前目录向上搜索把所有层级的.claudeignore都加载进来合并。也就是说你可以在 monorepo 根目录放一份全局规则在packages/payment/里再放一份只针对支付模块的规则越靠近根目录的优先级越高。这样不同子项目可以有各自的忽略策略不用挤在一个文件里。4. 配置 PreToolUse 钩子骨架自动init会帮你写好settings.json但理解结构才能排障。手动配置的话在项目根目录建.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Read, hooks: [ { type: command, command: claude-ignore } ] } ] } }逐字段解释一下。PreToolUse是钩子触发时机在工具调用之前。matcher指定匹配哪个工具这里写Read意思是只在 Claude 尝试读文件时触发如果你还想拦Edit或Bash可以再加一条 matcher。hooks数组里type是commandcommand就是实际执行的命令claude-ignore。claude-ignore被调用时Claude Code 会把工具调用的上下文通过 stdin 传进来工具解析出目标文件路径然后去比对所有.claudeignore里的模式。命中就退出码 2Claude Code 收到非零退出码会阻止这次读取没命中就退出码 0正常放行。注意matcher写错大小写或写成read都不会生效必须是Read。这是最常见的配了没用的原因之一。如果你项目里已经有别的 PreToolUse 钩子不要直接覆盖整个数组把claude-ignore这条追加进去{ hooks: { PreToolUse: [ { matcher: Read, hooks: [ { type: command, command: your-existing-hook }, { type: command, command: claude-ignore } ] } ] } }多个钩子按数组顺序执行任何一个返回退出码 2 都会阻止操作。5. 用 npm 脚本验证忽略规则是否生效配完不能靠感觉得验证。最直接的办法是手动模拟钩子调用把一段包含文件路径的 JSON 通过 stdin 喂给claude-ignore看退出码。先在package.json里加两个脚本{ scripts: { check-ignore: echo {\tool_name\:\Read\,\tool_input\:{\file_path\:\.env\}} | claude-ignore; echo \exit$?\, check-allow: echo {\tool_name\:\Read\,\tool_input\:{\file_path\:\src/index.ts\}} | claude-ignore; echo \exit$?\ } }跑第一个npm run check-ignore预期输出里exit2说明.env被成功拦截。跑第二个npm run check-allow预期exit0说明普通源码文件正常放行。如果两个都是 0那说明.claudeignore没被找到或者模式写错了如果两个都是 2检查是不是模式写得太宽比如写了*或者src把整个目录都盖住了。再补一个分层验证。在子目录packages/payment/下建一个.claudeignore写一行fixtures/然后从该子目录跑cd packages/payment echo {tool_name:Read,tool_input:{file_path:fixtures/mock.json}} | claude-ignore; echo exit$?应该返回 2。同时回到根目录跑同一个路径如果根目录的.claudeignore没写fixtures/那从根目录看这个文件是允许的——这就验证了分层规则确实按目录生效。6. 常见报错与排查清单钩子完全不触发。先确认.claude/settings.json的路径对不对必须是项目根目录下的.claude/文件夹不是用户级的~/.claude/。再确认matcher是Read。最后确认claude-ignore在 PATH 里which claude-ignore能查到。退出码一直是 0敏感文件没被拦。大概率是.claudeignore的位置或模式问题。claude-ignore从当前工作目录向上找.claudeignore如果你在子目录启动 Claude Code根目录的规则也会被加载但模式是相对各自文件所在目录解析的。用npm run check-ignore从项目根目录跑一遍排除路径干扰。settings.json被 init 覆盖了。claude-ignore init在文件已存在时只打印模板、不覆盖但如果你手动复制粘贴时把整个hooks对象替换了原有钩子就没了。改之前先git diff看一眼或者备份一份。模式写了但没匹配上。gitignore 风格里node_modules/带斜杠表示只匹配目录*.log匹配任意层级的日志文件。如果你写/dist带前导斜杠表示只匹配根目录下的dist子目录里的dist不匹配。这个和 gitignore 语义一致容易踩。Key 报 401 或连接失败。回到第 2 节检查ANTHROPIC_BASE_URL是不是https://taotoken.net/apiANTHROPIC_API_KEY有没有多余空格或换行。可以在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个 Key 对比测试。接入细节和协议说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 版本更新后钩子失效。钩子机制依赖 Claude Code 的 PreToolUse 支持升级后如果settings.json结构有变化对照官方文档重新核对字段。claude-ignore本身更新用npm update -g claudeignore。排查顺序建议固定成先which claude-ignore确认命令存在再npm run check-ignore确认退出码再看settings.json结构最后才怀疑 Key 和网络。这样能少走很多弯路。
