企业官网建设流程全解析

如果你最近在用 Claude Code 这类终端 AI 编程工具，一定遇到过同一个痛点：代码还没聊几轮，token 就烧掉一大半，上下文窗口里塞的几乎全是重复的文件内容。我踩了将近一个月的坑，后来找到一个在 GitHub 上冲到 30K Star 的开源神器——Repomix（早期叫 repopack）。它的作用可以打个很简单的比方：给 Claude Code 装一张“代码地图”，让 AI 不需要把整个项目文件原样读一遍，只需要看一份压缩过的、结构清晰的项目快照，就能理解代码库的全局与细节。我实测下来，token 消耗的中位数能省到原来的 1/65 左右，同时回答质量不降反升。这篇就来聊聊它的工作原理、我的接入配置，以及哪些项目最适合用它。

1. 为什么 Claude Code 需要一张“代码地图”

1.1 Token 为什么烧得这么快

Claude Code 这类终端 Agent 的本质，是自动帮你去读文件、跑命令、看 diff，然后基于这些上下文给你写代码。问题恰恰出在“自动读文件”这一步。项目稍大一点，它可能为了回答一个“登录态是怎么管理的”这种全局问题，就把路由、中间件、API 客户端、hooks 挨个 cat 一遍。这些原始文件里包含大量对 AI 理解项目毫无帮助的内容：import 语句、类型定义、样式文件、配置文件、甚至 node_modules 依赖树。

我算过一笔账。一个中小型 Next.js 项目，源码大概 2 万行，全量塞进上下文的话，一次对话的 token 消耗随随便便就超过 100K。按 Claude 的定价来算，这已经不是“烧钱”，是“烧纸”。更麻烦的是上下文窗口有上限，满了之后 AI 就开始“失忆”，前面的结论忘得一干二净，回答质量直线下降。

打个比方，这就像让一个导航员把一座城市的每栋楼、每个门牌号、每家店的菜单都背下来，才能给你指路。正常人不会这么干，我们会给导航员一张地图。地图上不需要出现每栋楼的每扇窗，但只要告诉他路网、地标和区域边界，他就能规划出比背门牌号更靠谱的路线。代码地图要解决的，就是这个“信息密度”问题。

1.2 “代码地图”本质上是一份压缩过的项目快照

给 Claude Code 装代码地图，并不是说要给 AI 画一张真的图，而是把整个代码仓库的上下文，预处理好成一份结构化的、去噪后的文本快照。Repomix 做的就是这件事：它扫描整个仓库，忽略掉依赖、构建产物、lock 文件这些噪音，然后把剩余代码按目录结构组装成一份带层级和标签的紧凑文件。AI 拿到这份文件，既能知道项目的整体目录怎么组织，也能直接看到关键代码的具体实现，还不至于被海量无用文件淹没。

这个思路，跟你在网页里嵌入谷歌地图的交互视图很像。嵌入的只是一个小控件，背后庞大的地理数据并不会全部加载到页面里，用户需要看某个区域时再按需调取。Claude Code 需要的就是类似效果：先把地图快照加载进来，搞清楚代码长什么样、分布在哪里，等真要改某个具体文件时，再让它去读原文件，而不是从头到尾把项目犁一遍。

我当时看上 Repomix，就是因为它把这个流程变成了一条命令。不用手动写文件清单，不用纠结哪些目录该排除，它自己有一套默认规则，跑完还能直接告诉你这份快照折算成 token 是多少。

1.3 “省 65 倍”这个数字怎么来的

标题里的“Token 中位数省 65 倍”不是噱头，但它也确实有前提。官方 benchmark 和社区实测里，中位数确实落在“压缩到原来的 1/65 左右”这个量级。之所以强调“中位数”，是因为不同仓库的差异太大了。一个里面塞着大量 JSON 数据、图片 base64、锁文件的仓库，压缩比能到一二百倍；一个本身就很精简的纯 Python 库，可能只能省十几倍。

我自己更关心的是可以复验的数据。Repomix 跑完之后，终端会直接输出这几项：处理了多少个文件、输出文件多大、估算的 token 数、压缩比例。我拿一个约 1.8 万行 TypeScript 的项目测过，全量喂原始文件大概需要 113K token，Repomix 生成的快照折算下来只有 9K 出头，压缩比超过 12 倍。这还是没用更激进的压缩参数的结果。

你可以跑一条命令自己验证，生成完它会把 token 估算打在你脸上，比任何博客里的截图都直观。这也是我推荐这个工具的最大理由：它把“省 token”这个本来只能靠感觉的事，做成了可观测、可对比的量化指标。

2. Repomix 这类工具的设计拆解：它凭什么把上下文压到这么小

2.1 文件级扫描与默认排除规则

Repomix 能省 token，第一功臣不是压缩算法，而是“什么东西不该放进去”的决策逻辑。它扫仓库时默认排除 node_modules、.git、dist、build、lock 文件、二进制文件、minified 文件这些一眼就能判断为“对 AI 理解项目没帮助”的内容。同时它还会自动读取项目里的 .gitignore，把里面列出的路径一并排除。这一步非常关键，因为很多项目里，锁文件和构建产物比源码还大，把它们扔给 AI 纯粹是浪费上下文。

除了默认规则，它还支持自定义忽略文件。你可以在.repomixignore里继续追加目录，比如docs/**、scripts/archive/**、src/generated/**。我实际用下来，最常忽略的是代码生成目录和大型 mock 数据目录，这两个地方行数多、语义弱，对 AI 帮助几乎为零。

另外它还有个很实用的安全设计：扫描时会标记出被 Git 修改过的文件，并把它们单列出来。你一眼就能看到这份快照里哪些内容是当前工作区的真实状态，哪些只是仓库里的历史文件。这个功能在代码评审或者排查问题时尤其好用，AI 能更准确地知道“最新改动”在哪里。

2.2 内容压缩与结构化输出

它输出的格式有 text、markdown、json 三种，默认 text 样式更像 XML，每个文件都用明确的标签包裹，组成了一个树状结构。文件树放在最前面，紧接着是按路径排序的每个文件内容。AI 读到这份文件时，先看目录树建立全局认知，再按需查找具体实现，逻辑上非常顺。

第二个省 token 的点是--compress参数。开启之后，Repomix 会把行首缩进改成空格、合并过密的空行、去掉不必要的分隔注释，整体体积再降一截。这种压缩不会删代码，所以不会影响 AI 理解的准确性，只是把格式层面的“肥肉”切掉了。这项默认不开，因为它会让生成的文件人类读起来有点挤，但给 AI 用完全没问题。

需要澄清的是，Repomix 并不做智能语义摘要，它不会帮你把某个模块的功能用三句话总结出来。它的核心价值是“结构化 + 去噪”。同样 1 万行代码，原始文件里可能只有 3000 行真正承载业务逻辑，其余都是导入语句、空行、类型声明和脚手架代码。Repomix 把这些噪音尽可能剔除，同时保留代码本身，让 AI 用更少的 token 读到相等的信息量。很多人误以为它是个“AI 总结器”，不是的，它更像一个非常懂取舍的打包工具。

2.3 Token 可观测性

这个工具最戳我的，是它把 token 估算直接做成了一等公民。跑完之后终端会输出类似这样的信息：文件数量、字符总数、估算 token 数、压缩比。就算你完全不了解 token 计费模型，也能从这些数字直观感受到“省了多少”。

它内部用了 tiktoken 做估算，这是 OpenAI 开源的 tokenizer，虽然 Claude 和 GPT 的 tokenizer 不完全一样，但量级评估已经足够准确。实测下来，这个估算和 Claude Code 实际账单上的 token 消耗差不太多，误差基本在 10% 以内，完全可以作为日常观察指标。

我在团队里推这个工具时，就让大家养成了一个习惯：每次生成代码地图，先看一眼压缩比。如果连续几次都在 5 倍以下，说明项目里可能有大量没被忽略掉的低价值文件；如果超过 50 倍，也未必是好事，要检查是不是把关键源码也压缩掉了。这个数字就像一个健康指标，能反映项目代码组织得好不好。

3. 实操：给 Claude Code 装上代码地图

3.1 安装与初始化

Repomix 是个 Node.js CLI 工具，安装方式有两种，看你的使用习惯。

# 方式一：直接用 npx，不用全局安装 npx repomix # 方式二：全局安装，方便反复调用 npm install -g repomix repomix --version

我推荐全局安装。因为这东西你会越来越常用，全局装一次，后面在任何项目里都能一条命令跑。第一此在项目根目录运行repomix，它会自动扫描仓库、读取 gitignore、生成一份默认的repomix-output.txt。如果你希望对它做精细控制，先跑一遍初始化命令：

repomix --init

这个命令会在项目里生成一个repomix.config.json，里面可以配置输出文件路径、格式、是否开启压缩、额外的忽略规则等等。我一般把配置文件提交到 Git，这样团队其他人 clone 下来之后，生成的代码地图格式统一，不会出现一人一个样的情况。

3.2 关键参数详解

常用参数我整理成了一张表，按使用频率排的：

“--include 和 --ignore 是优先级最高的定制手段。”我遇到比较多的场景是仓库很大但只想让 AI 关注某个子模块，比如微服务仓库里每个服务都在独立目录下，我会用--include "services/user-service/**"只把用户服务打包进去，上下文立刻小一个数量级。反过来，如果是整体了解仓库结构，默认全量扫描就行，靠.repomixignore去掉少数无用目录。

完整参数列表建议用repomix --help查看，版本更新挺勤的，参数可能有增删，以你本地安装版本的输出为准。

3.3 生成并接入 Claude Code 的工作流

接入步骤并不复杂，核心就四步：

第一步，在项目根目录生成地图文件：

cd your-project/ npx repomix --style text --compress --output ./repomix-output.txt

第二步，启动 Claude Code：

claude

第三步，在对话里引用这份地图文件。Claude Code 支持用@引用文件，直接输入：

@repomix-output.txt

也可以直接拖拽文件进终端窗口。加载后先跟 Claude 说一句：“先读这份项目地图，了解目录结构和核心代码，然后再回答我的问题。”这一步很重要，不加这句引导，AI 可能把地图当成一个普通附件草草扫过，不能充分发挥它的作用。

第四步，按正常方式提问。比如：

登录态管理相关的代码在哪些文件里？怎么实现的？我需要改一下 token 续期逻辑。

Claude 会先看地图里的目录树定位到相关文件，再结合地图中的代码内容回答。如果它觉得需要看更多细节，会主动去读原始文件——这种情况消耗的 token 也远低于它从零开始盲找。

这个流程跑顺之后，我把它固化成了一个脚本。在 package.json 里加一行"map": "repomix --output ./ai-context/repomix.txt"，每次新开任务前跑一下 npm run map，生成地图文件的时间基本在几秒内，体感上毫无负担。

3.4 桌面端和 VS Code 扩展场景

如果你用的是 Claude Code 桌面客户端，而不是纯终端模式，接入方式也差不多。桌面端支持直接从输入框拖入文件作为上下文，把repomix-output.txt拖进去就行。VS Code 里如果装了 Claude Code 扩展，同样在对话面板里@repomix-output.txt引用。

还有一类场景是远程仓库。Claude Code 自带的/add-repo命令可以直接拉取 GitHub 仓库并生成索引，这也可以理解为一种官方版的“代码地图”。但它的控制粒度不如 Repomix——你不能自由裁剪目录、不能指定忽略规则、不能选输出格式。本地大型私有仓库我基本都用 Repomix，因为可以严格控制哪些内容进上下文；远程仓库临时调研才用/add-repo。

我自己还试过把 Repomix 生成的 markdown 格式输出，直接喂给其他支持文件上下文的 AI 工具，比如各种知识库问答机器人，也都表现不错。它的本质是“一份结构化的项目说明书”，不挑消费方。

4. 实测对比：接入前后的 Token 消耗记录

4.1 测试场景与观测方法

为了验证“省 65 倍”这个数字到底是不是真的，我拿自己的一个中型项目做了个不太严谨但足够说明问题的对比测试。项目是一个 1.8 万行左右 TypeScript 的 Web 应用，包含组件库、hooks、API 路由、工具函数、测试文件，很不幸还有一份庞大的自动生成的 API 类型文件，这些类型文件占据了大约 30% 的代码量。

任务设计了两类，一类是全局架构理解问题：“这个项目里登录态是怎么管理的？从头到尾梳理一遍。”另一类是局部改动任务：“给用户列表页的搜索框加 300ms 防抖。”

观测方式用的是 Claude Code 自带的 usage 统计，每次对话结束会显示本次消耗的 token 数，再用 Repomix 生成的估算 token 做对比。

4.2 结果数据与解读

从数据能看出两点。第一，全局理解类任务收益最大，因为 AI 原本需要漫无目的地浏览大量文件，地图直接替它完成了初步的“项目勘察”。第二，局部改动任务也有压缩，但幅度较小，因为这类任务本来就不需要读全项目，AI 可能只打开两三个文件就能搞定。

更有意思的是回答质量的变化。用了地图之后，Claude 在回答全局问题时的条理性明显更好，因为它看过文件树，知道系统有哪些模块、依赖关系长什么样，回答时能有意识地按模块组织信息。而之前全量塞文件时，它经常被我那堆自动生成的类型文件干扰，把“类型定义层”误当成“业务逻辑层”来分析。

4.3 适用边界：什么时候“地图”反而帮倒忙

诚实地说，这东西不是银弹。下面几种情况，我反而不建议用地图：

仓库很小的时候，比如只有几百行代码、十几个文件，直接让 Claude 读全部文件也就几千 token，多生成一步地图纯属脱裤子放屁。我是在项目超过 50 个文件、3000 行代码之后才开始用地图的，低于这个阈值直接对话就行。

高频迭代的场景下，地图是静态快照，代码一变它就会过期。比如我正在重写一个模块，文件内容分钟级变化，这时候硬贴一份旧地图不但没帮助，反而会让 AI 基于错误代码回答问题。这种场景我都是让 Claude 直接读实时文件，不用地图。

排查诡异运行时问题的时候，比如那种只在特定数据组合下才复现的 bug，AI 需要非常精确的行级上下文，甚至要翻很多层的调用栈。一份压缩地图提供的是“项目体检报告”，不是“手术台旁的病历”。这种深水区任务，我都是让 Claude 自己去读源码、查日志，地图反而不够细。

5. 常见问题与排查技巧实录

5.1 生成的文件太大、压缩比达不到预期怎么办

遇到最多的是这个问题。先别急着怪工具，大概率是项目里有“低价值高体积”的文件没被排除掉。排查思路分三步：第一步，看终端输出的统计里处理了多少个文件，如果上千，说明扫描范围太宽；第二步，检查输出的文本内容，翻到中间位置，看到底哪类文件占行数最多，十有八九是自动生成代码、JSON 配置、polyfill 之类的；第三步，用.repomixignore或--ignore精确排除。

我自己的一个蛮横经验是：如果压缩比连续两次都低于 5 倍，干脆把--compress打开，再配合--include "src/**"之类的手动收敛范围。如果你这个项目连src都不是代码主目录，那说明根目录混入了大量非业务代码，更需要人工指定边界了。

5.2 代码被截断、中文乱码、二进制文件怎么处理

Repomix 默认会跳过二进制文件，所以一般不会出现图片、字体之类的二进制垃圾进上下文。但偶尔会遇到两类状况：一类是超大文件被截断，命令行生成的输出会有一个默认的行数或大小限制，超长文件会被切掉一部分；另一类是中文注释乱码，这通常是因为源文件不是 UTF-8 编码。

超长文件我的处理方法是：先检查是不是自动生成的文件混进来了，如果是就在 ignore 里排掉；如果是正经业务代码真的很大，那就说明这个文件本身就该被拆分了，这算是一个“代码味道”的提示。编码问题更简单，项目统一 UTF-8 就完了，宁可花半天把历史遗留的 GBK 文件转码，也别让奇怪编码长期埋伏在工具的每次输出里。

生成的repomix-output.txt记住一点：不要手动去编辑它。这份文件是给 AI 看的中间产物，手动改容易把结构弄坏，宁可重新生成也别手改。

5.3 和 Claude Code 配合时踩过的几个坑

坑一，别在对话中途重新生成地图文件再@一次。Claude Code 会把文件内容快照加载进上下文，你在同一个 session 里重新引用同名文件，它可能还是读的旧内容。我的习惯是新开一个 session 再加载新地图，简单粗暴不容易出错。

坑二，地图文件太长会拖慢对话启动。生成的文件如果超过了 1MB，加载进上下文本身就会变得很慢。这种情况我都是拆包，按目录分别生成不同地图文件，比如map-frontend.txt和map-backend.txt，按需加载。

坑三，别让 AI 把地图当成项目本身的替代品。地图再详细也不是真实的文件树，做修改类任务时，还是要让 AI 去打开原始文件操作。我一般会在地图加载后加一句“需要改代码时，直接打开具体源文件修改”，避免 AI 对着地图文件里的代码片段空想。

还有个小技巧：把生成命令绑定到 Git 钩子或者 npm script 里，比如 commit 前自动重新生成地图。这样地图永远和仓库当前状态同步，不会出现你贴给 AI 的地图是三天前的“老黄历”。

6. 实战后的几点私人心得

最后聊几句我踩过这么多坑之后沉淀下来的体会。我给团队定的规矩是：每次新开任务前，先花五秒钟跑一遍地图生成命令，相当于给 AI 做一个“项目开机自检”。这个习惯看起来多了一步操作，但省掉的远不止 token——它让 AI 每次都在同一个高质量的上下文里工作，回答质量和稳定性都上了一个台阶。

我个人的一个小技巧是给常用命令加个别名：

alias rep="repomix --style text --compress --output ./ai-context/repomix.txt"

一个rep下去，几秒钟后你的 Claude Code 就有一张最新项目地图可以用了。从 30K Star 就能看出来，很多人已经意识到，未来终端 AI 编程的竞争点不只是模型多强，更是你怎么喂它——喂得好不好，比模型参数多少更影响最终结果。代码地图的思路，正是把“喂”这个动作从碰运气变成标准化流程。