Repomix 配置完全指南从 JSON 到 TypeScript掌控输出、忽略规则与高级特性【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomixRepomix 是打包整个代码库为单一 AI 友好文件的工具。本篇指南以官方 Configuration 文档为主体系统讲解 Repomix 的配置体系支持 TypeScript / JavaScript / JSON 多种格式的配置文件如何被查找与合并、每个配置项的含义与默认值、include/ignore 规则的正确写法以及代码压缩、逐文件包含级别、文件处理器、Git 集成、安全检查等高级特性。读完本文你将能够为不同项目场景编写出可复现、可维护、可精准控制 token 消耗的repomix.config.*配置。配置入口配置文件与命令行选项Repomix 可以通过配置文件或命令行选项进行配置。配置文件用于定制 Repomix 处理与输出代码库的各个方面两者遵循一个基本规则命令行选项优先于配置文件设置。因此配置文件适合沉淀项目的默认行为而 CLI 参数适合一次性覆盖例如临时只打包某个目录。配置文件格式Repomix 支持多种配置文件格式并会按固定优先级自动查找以兼顾不同开发习惯TypeScriptrepomix.config.ts、repomix.config.mts、repomix.config.ctsJavaScript / ES Modulerepomix.config.js、repomix.config.mjs、repomix.config.cjsJSONrepomix.config.json5、repomix.config.jsonc、repomix.config.json在 src/config/configLoad.ts 中可以看到这份完整候选列表加载器会按照 TS → JS → JSON 的顺序逐个检查文件是否存在命中即停止。仓库的测试夹具目录 tests/fixtures/config-ts 与 tests/fixtures/config-js 中提供了.ts、.mts、.cts、.js、.mjs、.cjs、.json等各格式的真实示例可作为编写参考。JSON 配置在项目目录中执行初始化命令即可生成一份包含默认设置的repomix.config.jsonrepomix --init如果希望生成一份全局配置作为找不到本地配置时的回退则使用repomix --init --globalTypeScript 配置TypeScript 配置文件提供最佳的开发体验完整的类型检查、IDE 自动补全与智能提示并且支持动态值时间戳、环境变量等。安装要求要在配置中使用defineConfig需要把 Repomix 安装为开发依赖npm install -D repomix基础示例// repomix.config.ts import { defineConfig } from repomix; export default defineConfig({ output: { filePath: output.xml, style: xml, removeComments: true, }, ignore: { customPatterns: [**/node_modules/**, **/dist/**], }, });动态值示例利用 TypeScript 的执行能力可以生成基于时间戳的文件名// repomix.config.ts import { defineConfig } from repomix; // Generate timestamp-based filename const timestamp new Date().toISOString().slice(0, 19).replace(/[:.]/g, -); export default defineConfig({ output: { filePath: output-${timestamp}.xml, style: xml, }, });JavaScript 配置JavaScript 配置文件与 TypeScript 完全一致支持defineConfig与动态值。从源码角度看两者在加载时都经由 jiti。正因为 JS/TS 配置本质是可执行代码仓库对远程仓库的配置加载做了严格限制未显式传入--remote-trust-config时克隆下来的远程仓库配置根本不会被加载configLoad.ts。配置文件位置与加载顺序Repomix 查找配置文件的顺序如下当前目录的本地配置文件优先级 TS JS JSONTypeScriptrepomix.config.ts、repomix.config.mts、repomix.config.ctsJavaScriptrepomix.config.js、repomix.config.mjs、repomix.config.cjsJSONrepomix.config.json5、repomix.config.jsonc、repomix.config.json全局配置文件优先级同样为 TS JS JSONWindows%LOCALAPPDATA%\Repomix\repomix.config.ts及.mts、.cts、.js、.mjs、.cjs、.json5、.jsonc、.jsonmacOS / Linux~/.config/repomix/repomix.config.ts及上述同类扩展名全局目录的计算逻辑在 src/config/globalDirectory.ts 中Windows 使用%LOCALAPPDATA%\RepomixLinux/macOS 则优先尊重XDG_CONFIG_HOME环境变量$XDG_CONFIG_HOME/repomix未设置时才回退到~/.config/repomix。此外还可以用--config path显式指定配置文件此时该路径会被直接加载并忽略自动查找configLoad.ts。命令行选项始终覆盖配置文件中的同名设置。配置的三层合并模型从源码看最终生效的配置由三层合并而成configLoad.ts默认配置定义在 configSchema.ts 的repomixConfigDefaultSchema中所有缺省项在此兜底文件配置即repomix.config.*中声明的字段CLI 配置命令行传入的字段优先级最高。合并时逐层覆盖其中output.git、ignore.customPatterns、include等会被特殊处理如 ignore 的自定义模式按 base → file → cli 顺序拼接合并而非整体替换最终通过 valibot schema 校验后得到完整配置。一个值得注意的细节是当未显式设置filePath时Repomix 会根据output.style自动调整输出文件名defaultFilePathMap定义了每种 style 对应的默认文件名xml→repomix-output.xml、markdown→repomix-output.md、plain→repomix-output.txt、json→repomix-output.json见 configSchema.ts。配置选项总览下表完整列出配置文件的全部选项、说明与默认值OptionDescriptionDefaultinput.maxFileSize最大可处理的文件大小字节。超过此大小的文件将被跳过适用于排除大型二进制文件或数据文件5000000050MBinput.processors有序的{ pattern, command, timeout?, onError? }数组在打包前运行外部命令转换匹配的文件如 JSON→TOON。第一个匹配的 glob 生效。会运行任意命令因此仅限本地 CLI 运行远程仓库需--remote-trust-config。详见下文文件处理器未设置output.filePath输出文件名支持 XML、Markdown、纯文本格式repomix-output.xmloutput.style输出样式xml、markdown、json、plain不同格式对不同 AI 工具各有优势xmloutput.filePathStyle输出中文件路径的展示方式target-relative保持相对于各目标根目录cwd-relative保持相对于当前工作目录target-relativeoutput.parsableStyle是否根据所选样式 schema 对输出进行转义提升可解析性但可能增加 tokenfalseoutput.compress是否使用 Tree-sitter 进行智能代码提取在保留结构的同时降低 token 数falseoutput.patterns逐文件包含级别。有序的{ pattern, compress?, directoryStructureOnly? }数组第一个匹配的 glob 生效并覆盖全局output.compress。详见下文逐文件包含级别未设置output.headerText文件头部自定义文本可用于为 AI 工具提供上下文或指令nulloutput.instructionFilePath包含详细 AI 处理指令的文件路径nulloutput.fileSummary是否在开头包含摘要文件数、大小等指标trueoutput.directoryStructure是否在输出中包含目录结构帮助 AI 理解项目组织trueoutput.files是否包含文件内容。设为 false 时仅输出结构与元数据trueoutput.removeComments是否移除受支持文件类型中的注释可减少噪音与 tokenfalseoutput.removeEmptyLines是否移除空行以减少 tokenfalseoutput.showLineNumbers是否给每行添加行号便于引用具体代码falseoutput.truncateBase64是否截断长 base64 数据字符串如图片以减少 tokenfalseoutput.copyToClipboard是否在保存文件的同时复制输出到系统剪贴板falseoutput.splitOutput按每部分最大大小拆分输出为多个编号文件如1000000约 1MB。CLI 接受人类可读大小如500kb、2mb。保证每个文件在限制内且不跨文件拆分未设置output.tokenBudget打包输出超过该 token 数时以非零退出码失败作为 CI/Agent 上下文限制的守卫输出仍会生成未设置output.topFilesLength摘要中展示的 top 文件数设为 0 则不显示摘要5output.includeEmptyDirectories是否在仓库结构中包含空目录falseoutput.includeFullDirectoryStructure使用include模式时是否展示完整目录树仍遵循 ignore 模式同时只处理被包含的文件为 AI 分析提供完整仓库上下文falseoutput.git.sortByChanges是否按 git 变更次数排序文件变更多的文件排在底部trueoutput.git.sortByChangesMaxCommits分析 git 变更时检查的最大提交数限制历史深度以保性能100output.git.includeDiffs是否在输出中包含 git diffs工作区与暂存区变更分别展示falseoutput.git.includeLogs是否在输出中包含 git 日志含日期、消息、文件路径的提交历史falseoutput.git.includeLogsCount包含的 git log 提交数50include要包含的文件的 glob 模式列表[]ignore.useGitignore是否使用项目.gitignore中的模式trueignore.useDotIgnore是否使用项目.ignore文件中的模式trueignore.useDefaultPatterns是否使用默认忽略模式node_modules、.git 等trueignore.customPatterns附加的自定义忽略 glob 模式[]security.enableSecurityCheck是否使用 Secretlint 执行安全检查以检测敏感信息truetokenCount.encodingOpenAI 兼容分词编码如 GPT-4o 用o200k_base、GPT-4/3.5 用cl100k_base由 gpt-tokenizer 驱动o200k_base以上默认值与约束均可在 src/config/configSchema.ts 的 schema 定义中找到一一对应例如maxFileSize被限制为正整数并默认 50MB、sortByChangesMaxCommits默认 100、tokenCount.encoding是受支持编码的枚举默认o200k_base。schema 同时限定了style只能是xml | markdown | json | plain、filePathStyle只能是target-relative | cwd-relative非法值会在加载/合并阶段直接报错。JSON5 语法支持配置文件支持 JSON5 语法因此可以享受以下便利注释单行与多行对象与数组中的尾随逗号不带引号的属性名更宽松的字符串语法注意这里的 JSON5 解析同样应用于.json与.jsonc文件见 configLoad.ts所以即使使用标准.json扩展名写注释也不会报错。Schema 校验为配置文件添加$schema属性即可启用 schema 校验{ $schema: https://repomix.com/schemas/latest/schema.json, output: { filePath: repomix-output.xml, style: xml } }这为支持 JSON schema 的编辑器提供了自动补全与校验能力。仓库内同时提供了本地 schema 生成脚本website/client/scripts/generateSchema.ts对应产物可在 website/client/src/public/schemas 中查看。完整配置示例以下是一个完整的repomix.config.json示例涵盖了所有常用配置项{ $schema: https://repomix.com/schemas/latest/schema.json, input: { maxFileSize: 50000000, // processors: [ // { pattern: **/*.json, command: npx toon-format/cli {file} } // ] }, output: { filePath: repomix-output.xml, style: xml, filePathStyle: target-relative, parsableStyle: false, compress: false, headerText: Custom header information for the packed file., fileSummary: true, directoryStructure: true, files: true, removeComments: false, removeEmptyLines: false, topFilesLength: 5, showLineNumbers: false, // patterns: [ // { pattern: docs/**/*, compress: true }, // { pattern: website/**/*, directoryStructureOnly: true } // ], truncateBase64: false, copyToClipboard: false, includeEmptyDirectories: false, git: { sortByChanges: true, sortByChangesMaxCommits: 100, includeDiffs: false, includeLogs: false, includeLogsCount: 50 } }, include: [**/*], ignore: { useGitignore: true, useDefaultPatterns: true, // Patterns can also be specified in .repomixignore customPatterns: [ additional-folder, **/*.log ], }, security: { enableSecurityCheck: true }, tokenCount: { encoding: o200k_base } }Include 模式精确控制打包范围Repomix 支持使用 glob 模式指定要包含的文件实现更灵活的文件选择使用**/*.js包含任意目录下的所有 JavaScript 文件使用src/**/*包含src目录及其子目录下的所有文件组合多个模式如[src/**/*.js, **/*.md]同时包含src下的 JS 文件与所有 Markdown 文件在配置文件中声明 include 模式{ include: [src/**/*, tests/**/*.test.js] }或使用--include命令行选项进行一次性过滤。从源码看include 模式会被转义后交给 globby 执行文件搜索src/core/file/fileSearch.ts当没有任何 include 模式时默认回退为**/*搜索所有文件。include与 CLI 传入的模式会被拼接合并而非互相覆盖这也是CLI 覆盖配置规则的一个例外。Ignore 模式五种排除机制与优先级Repomix 提供多种方式设置忽略模式用于在打包过程中排除特定文件或目录.gitignore默认使用项目.gitignore文件与.git/info/exclude中的模式。可通过ignore.useGitignore设置或--no-gitignoreCLI 选项控制。.ignore可在项目根目录使用.ignore文件格式与.gitignore相同。该文件被 ripgrep、the silver searcher 等工具共同尊重可减少维护多份忽略文件。通过ignore.useDotIgnore设置或--no-dot-ignoreCLI 选项控制。默认模式Repomix 内置一份常见的排除清单node_modules、.git、二进制文件等。通过ignore.useDefaultPatterns设置或--no-default-patternsCLI 选项控制完整清单见 src/config/defaultIgnore.ts。.repomixignore在项目根目录创建.repomixignore文件以定义 Repomix 专属忽略模式格式与.gitignore相同。自定义模式通过配置文件的ignore.customPatterns指定额外忽略模式可用-i, --ignore命令行选项覆盖。优先级顺序从高到低自定义模式ignore.customPatterns忽略文件.repomixignore、.ignore、.gitignore与.git/info/exclude位于嵌套目录时更深目录中的文件优先级更高位于同一目录时这些文件按任意顺序合并默认模式当ignore.useDefaultPatterns为 true 且未使用--no-default-patterns这套机制能灵活地按项目需求排除文件通过剔除安全敏感文件与大型二进制文件来优化打包体积同时防止机密信息泄露。在实现层面这些 ignore 文件会被解析为 globby 的 ignore 参数其中控制文件自身.gitignore等会被特殊延迟处理再过滤避免忽略规则反向泄漏这些文件见 fileSearch.ts。注意二进制文件默认不会包含在打包输出的内容中但它们的路径会出现在输出的 Repository Structure 部分从而在保持输出高效文本化的同时提供完整的仓库结构概览详见下文二进制文件处理。.repomixignore示例# Cache directories .cache/ tmp/ # Build outputs dist/ build/ # Logs *.log默认忽略模式当ignore.useDefaultPatterns为 true 时Repomix 自动忽略常见模式node_modules/** .git/** coverage/** dist/**完整清单位于 src/config/defaultIgnore.ts除上述示例外还包括版本控制目录.hg/**、.svn/**、依赖目录**/bower_components/**、vendor/**、日志**/*.log、npm-debug.log*、缓存.eslintcache、.parcel-cache/**、构建产物build/**、out/**、环境变量文件.env、编辑器目录.idea/**、.vscode/**、以及各语言生态的锁文件package-lock.json、yarn.lock、pnpm-lock.yaml、Cargo.lock、Gemfile.lock、go.sum等与 Python/Rust/Go 相关产物还包含 Repomix 自身输出**/repomix-output.*与历史遗留的**/repopack-output.*。二进制文件处理图片、PDF、编译产物、压缩包等二进制文件会被特殊处理以维持高效、文本化的输出文件内容二进制文件的内容不会包含在打包输出中保证输出为纯文本且适合 AI 处理目录结构二进制文件的路径会列在目录结构部分提供仓库的完整概览例如仓库中包含logo.png与app.jar时它们会出现在 Directory Structure 部分其内容不会出现在 Files 部分Directory Structure 输出示例src/ index.ts utils.ts assets/ logo.png build/ app.jar这样 AI 工具既能了解二进制文件存在于项目结构中又无需处理其二进制内容。注意可通过input.maxFileSize默认 50MB控制文件大小阈值超过该限制的文件会被完全跳过。高级特性代码压缩Code Compression开启output.compress: true后Repomix 使用 Tree-sitter 智能提取核心代码结构、移除实现细节在保留重要结构信息的同时显著降低 token 数。核心收益显著减少 token 数保留类与函数签名保留 import/export保留类型定义与接口移除函数体与实现细节更详细的原理与示例参见代码压缩指南。从源码实现看src/core/file/fileProcessContent.ts 与 src/core/treeSitter/parseFile.ts压缩流程为先按文件扩展名猜测语言加载对应的 tree-sitter WASM 解析器与语言查询queries 定义在 src/core/treeSitter/queries 下按语言拆分如queryTypescript.ts、queryPython.ts解析出 AST 后用各语言的解析策略src/core/treeSitter/parseStrategies捕获结构化片段再按行号排序、去重、合并相邻片段后输出。压缩是尽力而为的遇到不支持的语言、解析失败或 WASM 异常时会静默回退到未压缩内容单个文件的失败不会中断整个打包流程。压缩在 worker 线程中执行与注释移除同属重量级变换阶段之后才在主线程应用truncateBase64 → removeEmptyLines → trim → showLineNumbers等轻量变换。逐文件包含级别Per-file Inclusion Levelsoutput.compress对每个文件应用单一级别而output.patterns允许你按 glob控制每个文件的详细程度。每个条目按与include/ignore相同的方式匹配文件并覆盖全局output.compress设置{ output: { compress: false, // global default acts as the catch-all patterns: [ { pattern: docs/**/*, compress: true }, { pattern: website/**/*, directoryStructureOnly: true } ] } }每个文件会解析为三个级别之一完整内容默认包含文件的完整内容压缩compress: true内容经过与output.compress相同的 Tree-sitter 流水线仅目录结构directoryStructureOnly: true文件仅列在目录结构中内容块完全省略规则模式按数组顺序求值第一个匹配的模式对给定文件生效匹配模式的标志覆盖全局output.compress。匹配但未设置任何标志的模式会强制该文件为完整内容可用于在全局compress下白名单某些文件同一模式同时设置时directoryStructureOnly优先于compress无模式匹配时应用全局行为完整内容或output.compress为 true 时压缩该选项仅支持配置文件没有对应的 CLI 标志。源码中该逻辑位于 src/core/file/fileLevelResolve.ts用 minimatchdot: true按数组顺序匹配命中即返回directory-only/compress/full三者之一全部未命中才回退到全局output.compress。打包器会先按各目标根目录的相对路径解析级别并预计算再重写路径为展示形式避免多根目录或filePathStyle导致 glob 匹配基准漂移fileProcess.ts 中directory-only级别的文件直接从内容输出中剔除。文件处理器File Processorsinput.processors在文件打包之前运行外部命令转换文件内容。每个条目按 glob 匹配文件匹配方式同include/ignore并用命令的标准输出替换匹配文件的内容。这对 token 削减或格式转换非常有用例如把 JSON 转换为 TOON、压缩 SVG、把 notebook 转为纯脚本。{ input: { processors: [ { pattern: **/*.json, command: npx toon-format/cli {file} } ] } }工作原理Repomix 将每个匹配文件的内容写入临时文件并把其路径替换到命令的{file}占位符中占位符是必需的命令通过 shell 执行因此支持管道与npx等工具。命令的标准输出成为文件的新内容随后像普通文件一样流经后续流水线安全检查、token 计数、输出生成模式按数组顺序求值第一个匹配的模式生效——一个文件至多被一个处理器转换不进行链式处理每个处理器的选项timeout等待命令的最大毫秒数默认6000060 秒。注意冷缓存时npx下载包可能耗时更久onError命令以非零状态退出或超时时的行为。fail默认中止整个打包skip记录警告并回退使用文件原始内容示例命令每个command值配合合适的patternPatterncommand作用**/*.jsonjq -c . {file}压缩 JSON去除空白**/*.jsonnpx toon-format/cli {file}转换 JSON 为 TOON一种紧凑的 token 高效格式**/*.svgnpx svgo -i {file} -o -压缩 SVG**/*.ipynbjupyter nbconvert --to script --stdout {file}把 Jupyter notebook 转换为纯 Python 脚本由于第一个匹配的模式生效每个文件只应用一个处理器——例如**/*.json应只选jq或 TOON 转换器之一。命令必须将转换后的内容写入标准输出且被调用工具需在你的PATH中基于npx的命令首次使用时会下载工具。⚠️安全警告文件处理器会运行配置文件中的任意命令因此遵循严格的信任模型它们仅在本地 CLI 运行时执行此时 Repomix 假定工作目录中的配置是你自己的——这与 npm script 或 Makefile 的信任边界相同。与这些工具一样如果你未先审查其repomix.config.json就在他人获取的仓库中运行repomix其中的处理器命令会在你的机器上执行。打包不受信任的仓库前请先审查其配置。它们在库 APIpack()/runCli()、MCP 服务器与托管站点中被禁用这些场景均无法从配置运行命令。对远程仓库--remote克隆仓库的配置——因而也包括其中的处理器——仅在显式传入--remote-trust-config时才被信任否则远程配置根本不会加载。启动时会打印活跃的处理器因此来自陌生配置的意外处理器是可见的。由于命令会在启动时与错误信息中打印请通过环境变量如$TOKEN引用凭据环境变量打印时不会展开而不要将其内联在命令中。补充说明不建议在同一文件上组合改变格式的处理器与output.compress、output.removeComments或output.patterns的compress这些步骤按文件原始扩展名分派语言处理器会在转换后的内容上运行错误语言的处理器。同理Markdown 输出按原始扩展名标注代码围栏例如 JSON→TOON 的文件围栏标注为json。压缩是尽力而为的解析失败时会静默回退到转换后的内容。使用--watch时匹配的文件在每次重建时都会被重新处理命令也会随之重新执行。超时时 Repomix 会杀掉命令的 shell命令自行派生的常驻后台进程可能残留运行。处理器只能看到文本文件二进制文件在处理前已被排除其输出按 UTF-8 读取。Git 集成output.git配置提供强大的 Git 感知特性sortByChanges为 true 时文件按 Git 变更数修改过该文件的提交数排序变更多的文件位于输出底部帮助优先关注活跃开发的文件。默认truesortByChangesMaxCommits统计文件变更时分析的最大提交数。默认100includeDiffs为 true 时在输出中包含 Git 差异工作区与暂存区变更分别展示让读者看到仓库的待提交变更。默认falseincludeLogs为 true 时在输出中包含 Git 提交历史每个提交的日期、消息与文件路径帮助 AI 理解开发模式与文件关联。默认falseincludeLogsCountgit 日志中包含的最近提交数。默认50示例配置{ output: { git: { sortByChanges: true, sortByChangesMaxCommits: 100, includeDiffs: true, includeLogs: true, includeLogsCount: 25 } } }这些功能的底层实现在 src/core/git 目录gitLogHandle.ts负责提交历史采集、gitDiffHandle.ts负责差异采集采集到的内容会额外参与 token 计数与安全检查。安全检查Security Checks当security.enableSecurityCheck开启时Repomix 使用 Secretlint 在内容进入输出前检测敏感信息防止意外泄露API 密钥访问令牌私钥密码其他敏感凭据实现上src/core/security/securityCheck.ts安全检查由 worker 线程执行文件内容与 git diff/log 内容会一起被批处理每批 50 项送入 Secretlint 检测可疑文件会被标记并在输出中提示。安全检查还覆盖 git diff 与 git log 引入的内容避免变更中夹带密钥被漏检。完整的安全说明参见安全指南。注释移除Comment Removaloutput.removeComments设为true时受支持文件类型中的注释会被移除从而减小输出体积、聚焦核心代码。适用场景处理注释密集的代码尝试减少 token 数聚焦代码结构与逻辑受支持的语言与详细示例参见注释移除指南。实现上注释移除基于 tree-sitter 的语言级 AST 操作src/core/treeSitter/parseStrategies 下的各语言策略在 worker 线程中与压缩同阶段执行且removeEmptyLines会在注释移除之后运行从而清理掉注释移除产生的空行src/core/file/fileProcess.ts。相关资源命令行选项参考 —— 完整 CLI 参考CLI 选项覆盖配置文件设置输出格式 —— 每种输出格式的细节安全 —— Repomix 如何检测敏感信息代码压缩 —— 用 Tree-sitter 降低 token 数远程仓库处理 —— 远程仓库相关选项【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
