Repomix 配置完全指南从配置文件格式到高级特性的一站式手册【免费下载链接】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 友好文件的工具而配置是掌控其打包行为的关键。本文以官方《Configuración》配置指南为主体结合 src/config/configSchema.ts、src/config/configLoad.ts 等核心源码系统讲解 Repomix 支持的所有配置文件格式、完整参数表、include/ignore 模式、二进制文件处理策略以及代码压缩、逐文件包含级别、文件处理器、Git 集成、安全检查等高级特性。读完本文你将能够从零搭建一份贴合项目需求的repomix.config并理解每一项配置背后的底层实现原理。配置的两种入口配置文件与命令行选项Repomix 可以通过配置文件或命令行选项两种方式配置。配置文件用于定制代码库处理与输出生成的各个方面输出格式、include/ignore 模式、高级选项等而命令行选项则用于临时覆盖或快速配置。两者的优先级关系非常明确命令行选项优先于配置文件。这一规则在源码的配置合并逻辑中得到印证——configLoad.ts 中的mergeConfigs函数按照默认配置 → 文件配置 → CLI 配置的顺序逐层展开合并后出现的配置会覆盖先出现的同名配置因此 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这一查找顺序在 configLoad.ts 的defaultConfigPaths数组中硬编码实现数组按 TS → JS → JSON 排序findConfigFile从头到尾依次检测文件是否存在返回第一个命中的路径。仓库根目录下的 repomix.config.json 正是当前项目自身使用的 JSON 格式配置示例。JSON 配置一键初始化在项目目录中执行以下命令即可快速生成默认配置repomix --init这会创建一个包含默认配置的repomix.config.json。你也可以创建全局配置文件当项目目录中找不到本地配置时它会被自动用作兜底repomix --init --globalTypeScript 配置最佳开发体验TypeScript 配置文件提供完整的类型检查与 IDE 支持是体验最好的配置方式。安装前提要使用 TypeScript/JavaScript 配置或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/**], }, });defineConfig是官方提供的类型安全辅助函数其实现位于 configSchema.ts本质上是一个恒等函数(config: RepomixConfigFile) config。它本身不执行任何逻辑全部价值在于让 TypeScript 编译器基于RepomixConfigFile类型对你的配置对象做静态校验从而在写配置的瞬间就发现拼写错误或类型不匹配。TypeScript 配置的优势✅ 完整的 TypeScript 类型检查在 IDE 中即时反馈✅ 优秀的自动补全与 IntelliSense✅ 支持使用动态值时间戳、环境变量等动态值示例// repomix.config.ts import { defineConfig } from repomix; // 基于时间戳生成输出文件名 const timestamp new Date().toISOString().slice(0, 19).replace(/[:.]/g, -); export default defineConfig({ output: { filePath: output-${timestamp}.xml, style: xml, }, });JavaScript 配置JavaScript 配置文件与 TypeScript 完全等效同样支持defineConfig与动态值。实现原理从源码看TS 与 JS 配置文件在加载时都经由 jiti 运行时转译执行见 configLoad.ts 的defaultJitiImport因此行为完全一致而 JSON/JSON5/JSONC 文件则被直接读取内容后交给 JSON5 解析器处理configLoad.ts。需要注意的是TS/JS 配置属于可执行代码加载即运行这一点在远端仓库信任机制中尤为重要详见下文文件处理器的安全模型。配置选项完整参考表下表汇总了 Repomix 支持的全部配置项、说明与默认值默认值可在 configSchema.ts 的repomixConfigDefaultSchema中逐一核对选项说明默认值input.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是否按所选样式方案对输出进行转义。便于解析但可能增加 token 数falseoutput.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是否从受支持的文件类型中移除注释可降低噪音与 token 数falseoutput.removeEmptyLines是否移除输出中的空行以降低 token 数falseoutput.showLineNumbers是否给每行添加行号便于引用代码的特定部分falseoutput.truncateBase64是否截断长 base64 数据字符串如内嵌图片以降低 token 数falseoutput.copyToClipboard是否在保存文件的同时将输出复制到系统剪贴板falseoutput.splitOutput按单部分最大字节数将输出拆分为多个编号文件如1000000表示约 1MB。CLI 接受500kb、2mb这类可读大小。保证每个文件低于上限且不会把一个源文件拆到两个部分未设置output.tokenBudget当打包输出超过该 token 数时以非零退出码失败。作为 CI/Agent 上下文限制的保护输出仍会生成未设置output.topFilesLength摘要中展示的 Top 文件数设为0则不展示摘要5output.includeEmptyDirectories是否在仓库结构中包含空目录falseoutput.includeFullDirectoryStructure使用include模式时是否展示完整目录树仍遵循 ignore 模式而只处理被 include 的文件。为 AI 分析提供完整仓库上下文falseoutput.git.sortByChanges是否按 git 变更数对文件排序变更最多的文件排在最后trueoutput.git.sortByChangesMaxCommits统计 git 变更时最多分析的 commit 数限制历史深度以保性能100output.git.includeDiffs是否在输出中包含 git 差异分别展示工作区变更与暂存区变更falseoutput.git.includeLogs是否在输出中包含 git 日志展示带日期、消息与文件路径的提交历史falseoutput.git.includeLogsCount输出中包含的 git 日志 commit 数50include使用 glob 模式 指定要包含的文件[]ignore.useGitignore是否使用项目.gitignore中的模式trueignore.useDotIgnore是否使用项目.ignore中的模式trueignore.useDefaultPatterns是否使用默认忽略模式node_modules、.git 等trueignore.customPatterns使用 glob 模式 指定额外忽略模式[]security.enableSecurityCheck是否使用 Secretlint 执行安全检查以检测敏感信息truetokenCount.encodingOpenAI 兼容的 token 计数编码如 GPT-4o 用o200k_baseGPT-4/3.5 用cl100k_base基于 gpt-tokenizero200k_base关于默认值的两个实现细节输出文件名跟随样式自动调整defaultFilePathMapconfigSchema.ts定义了各样式对应的默认文件名xml→repomix-output.xml、markdown→repomix-output.md、plain→repomix-output.txt、json→repomix-output.json。在 configLoad.ts 中若用户未显式设置filePath合并后的输出路径会被自动调整为与所选style匹配的文件名。tokenCount.encoding是受限枚举而非任意字符串schema 中通过v.picklist(TOKEN_ENCODINGS)校验configSchema.ts支持值来自 tokenEncodings.ts配置了不支持的编码会在加载时报错。JSON5 语法支持配置文件支持 JSON5 语法允许注释单行与多行均可对象与数组末尾的尾逗号不带引号的属性名更灵活的字符串语法这也是为什么上面的参数表示例中能直接写// processors: [...]这类注释。注意JSON5 解析同样应用于.json文件见 configLoad.ts因此普通repomix.config.json也支持注释与尾逗号这一点对 Git 合并冲突的处理非常友好。Schema 验证与编辑器智能提示可以通过在配置文件中添加$schema属性启用 schema 验证{ $schema: https://repomix.com/schemas/latest/schema.json, output: { filePath: repomix-output.md, style: markdown } }这为支持 JSON schema 的编辑器提供自动补全与验证能力。仓库中已发布的 schema 生成文件可在 website/client/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: 用于打包文件的自定义头部信息。, 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, // 模式也可以在 .repomixignore 中指定 customPatterns: [ additional-folder, **/*.log ], }, security: { enableSecurityCheck: true }, tokenCount: { encoding: o200k_base } }这份示例与仓库根目录下的 repomix.config.json 结构完全一致可以作为你项目配置的起点模板。配置文件查找位置与优先级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 JSONWindowsTypeScript%LOCALAPPDATA%\Repomix\repomix.config.ts、.mts、.ctsJavaScript%LOCALAPPDATA%\Repomix\repomix.config.js、.mjs、.cjsJSON%LOCALAPPDATA%\Repomix\repomix.config.json5、.jsonc、.jsonmacOS/LinuxTypeScript~/.config/repomix/repomix.config.ts、.mts、.ctsJavaScript~/.config/repomix/repomix.config.js、.mjs、.cjsJSON~/.config/repomix/repomix.config.json5、.jsonc、.json全局目录的具体计算逻辑在 globalDirectory.ts 中Windows 优先取%LOCALAPPDATA%\RepomixmacOS/Linux 下若设置了XDG_CONFIG_HOME则使用$XDG_CONFIG_HOME/repomix否则回退到~/.config/repomix。命令行选项优先于文件配置。另外两个加载细节值得注意显式指定--config path时该路径被无条件信任并加载configLoad.ts找不到文件会直接报错。在远程仓库模式--remote下仓库内自带的配置文件默认会被跳过并给出安全提示只有显式传入--remote-trust-config才会加载——因为 TS/JS 配置是可执行代码见 configLoad.ts 的isExecutableConfigPath判断。Include 包含模式Repomix 支持使用 glob 模式 指定要包含的文件实现更灵活强大的文件选择使用**/*.js包含任意目录下的所有 JavaScript 文件使用src/**/*包含src目录及其子目录中的所有文件组合多个模式如[src/**/*.js, **/*.md]包含src下的 JavaScript 文件与所有 Markdown 文件在配置文件中指定包含模式{ include: [src/**/*, tests/**/*.test.js] }或者使用命令行选项--include进行一次性过滤。Ignore 忽略模式Repomix 提供了多种设置忽略模式的方式用于在打包过程中排除特定文件或目录.gitignore默认情况下会使用项目.gitignore文件与.git/info/exclude中列出的模式。可通过ignore.useGitignore配置或--no-gitignore命令行选项控制。.ignore可以在项目根目录使用.ignore文件格式与.gitignore相同。该文件被 ripgrep 与 the silver searcher 等工具共同尊重减少了维护多个忽略文件的需求。可通过ignore.useDotIgnore配置或--no-dot-ignore控制。默认模式Repomix 内置一份常见的排除文件/目录清单如 node_modules、.git、二进制文件等。可通过ignore.useDefaultPatterns配置或--no-default-patterns控制完整清单见 src/config/defaultIgnore.ts。.repomixignore可以在项目根目录创建.repomixignore文件定义 Repomix 专属的忽略模式格式与.gitignore相同。自定义模式通过配置文件的ignore.customPatterns选项指定额外忽略模式可被命令行选项-i, --ignore覆盖。优先级顺序从高到低自定义模式ignore.customPatterns忽略文件.repomixignore、.ignore、.gitignore与.git/info/exclude位于嵌套目录时更深目录中的文件优先级更高位于同一目录时这些文件按无特定顺序合并默认模式当ignore.useDefaultPatterns为真且未使用--no-default-patterns时这种分层设计允许按项目需求灵活配置排除项在确保排除敏感文件与大型二进制文件、防止机密信息泄露的同时帮助优化最终打包文件的大小。.repomixignore示例# 缓存目录 .cache/ tmp/ # 构建输出 dist/ build/ # 日志 *.log默认忽略模式清单当ignore.useDefaultPatterns为真时Repomix 自动忽略常见模式例如node_modules/** .git/** coverage/** dist/**完整清单远比上述几行庞大从 defaultIgnore.ts 可以看到它还覆盖了版本控制目录.hg、.svn、各类构建输出.next、.nuxt、build/Release、缓存目录.parcel-cache、.webpack.cache、编辑器文件.idea、.vscode、*.swp、环境变量文件.env、锁文件package-lock.json、yarn.lock、Cargo.lock等、各语言运行时产物__pycache__、venv、target以及 Repomix 自身的输出**/repomix-output.*与旧版**/repopack-output.*。二进制文件处理二进制文件如图片、PDF、编译产物、压缩包等会被特殊处理以保证输出保持高效的纯文本形式文件内容二进制文件不会被包含进打包输出保证输出为纯文本、对 AI 处理高效目录结构二进制文件的路径会被列在目录结构区让你对仓库结构有完整认知这一策略确保你既能获得仓库结构的完整视图又能保持面向 AI 消费的高效纯文本输出。示例若仓库包含logo.png与app.jar它们会出现在目录结构区它们的内容不会出现在文件区目录结构输出src/ index.ts utils.ts assets/ logo.png build/ app.jar这样 AI 工具就能理解这些二进制文件存在于项目结构中而无需处理其二进制内容。注意可使用input.maxFileSize配置项默认 50MB控制文件大小阈值超过该阈值的文件会被整体跳过。50MB 这个默认值定义在 configSchema.tsv.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 50 * 1024 * 1024)。高级特性代码压缩Tree-sitteroutput.compress: true启用的代码压缩功能利用 Tree-sitter 智能提取关键代码结构同时移除实现细节在保留结构信息的同时帮助降低 token 数。主要收益显著降低 token 数保留类与函数签名保留 import 与 export保留类型与接口定义移除函数体与实现细节实现原理从 fileProcessContent.ts 可以看到压缩流程会调用parseFile解析文件并产出压缩结果压缩是best-effort的——当语言不受支持、解析失败或遇到异常文件时parseFile返回undefined此时会保留未压缩的原始内容单个文件的失败绝不会中断整个打包过程。更多细节与示例参见代码压缩指南。逐文件包含级别output.patternsoutput.compress对每个文件应用统一级别而output.patterns允许你按 glob 从配置文件控制每个文件的详细程度。每条目用 glob 选择文件匹配方式与include/ignore一致并覆盖全局output.compress设置{ output: { compress: false, // 全局默认值充当通用兜底 patterns: [ { pattern: docs/**/*, compress: true }, { pattern: website/**/*, directoryStructureOnly: true } ] } }每个文件最终解析为三个级别之一完整内容默认包含文件的完整内容压缩compress: true内容经过与output.compress相同的 Tree-sitter 压缩流程仅目录结构directoryStructureOnly: true文件列在目录结构中但内容块被完全省略规则模式按数组顺序求值第一个匹配的模式生效匹配模式的标志覆盖全局output.compress。匹配但未设置任何标志的模式强制该文件为完整内容可用于白名单——把某些文件从全局压缩中豁免同一模式同时设置两个标志时directoryStructureOnly优先于compress没有任何模式匹配时应用全局行为完整内容或output.compress为真时压缩该选项仅在配置文件中可用没有对应的 CLI 选项。其解析逻辑见 fileLevelResolve.tsresolveFileLevel函数用 minimatchdot: truePOSIX 路径形式逐条匹配directoryStructureOnly→compress→full依次判定。文件处理器input.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值需搭配合适的pattern模式command作用**/*.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的命令在首次使用时下载工具。实现细节见 fileProcessorRun.ts处理器命令默认超时为 60 秒DEFAULT_FILE_PROCESSOR_TIMEOUT_MS因为npx tool {file}冷缓存时可能花将近一分钟下载包单个命令的标准输出上限被提升到 64MB并发的外部进程数被限制在min(8, CPU 核数)通过模块级信号量在多个根目录并发打包时统一约束超时后使用SIGKILL强制结束命令 shell。::: warning 安全警告 文件处理器会执行配置文件中的任意命令因此遵循严格的信任模型它们仅在本地 CLI 运行中执行——Repomix 假定你工作目录下的配置属于你自己这与 npm 脚本或 Makefile 的信任边界相同。同理如果你在未事先审查他人仓库的repomix.config.json的情况下在其中运行repomix其处理器命令会在你的机器上执行。请先审查不可信仓库的配置再打包。它们对库 APIpack()/runCli()、MCP 服务器与托管网站是禁用的这些入口都无法执行配置中的命令。对远程仓库--remote克隆仓库的配置——包括其中的处理器——只有显式传入--remote-trust-config时才被信任。没有该标志远程配置根本不会被加载。上述门控机制在源码中体现为enableFileProcessors字段它不属于配置文件字段而是由真实 CLI 入口注入configSchema.ts因此库调用方、MCP 与托管网站默认关闭applyFileProcessors在门控关闭时直接原样返回文件fileProcessorRun.ts。活跃的处理器会在启动时被记录下来让未知配置中的意外处理器可见。由于命令会在启动时与错误消息中打印请通过环境变量如$TOKEN引用凭据——它们以未展开的形式记录——而不要直接写在命令里。 :::其他注意事项不建议将改变格式的处理器与output.compress、output.removeComments或output.patterns中的compress同时作用于同一文件这些步骤按文件的原始扩展名选择语言处理器会在转换后的内容上执行错误语言的处理。同理Markdown 输出会按原始扩展名标注代码块语言例如 JSON→TOON 的文件仍标注为json。压缩是 best-effort 的解析失败时会静默回退到转换后的内容使用--watch时匹配文件在每次重建时都会重新处理即每次都会重新执行命令超时时 Repomix 会终止命令的 shell命令自行派生的常驻后台子进程可能残留运行处理器只看到文本文件二进制文件在预处理前已被排除其输出按 UTF-8 读取Git 集成output.git配置提供强大的 Git 相关能力sortByChanges为真时文件按 Git 变更数修改过该文件的 commit 数排序变更最多的文件排在输出末尾帮助优先关注最活跃开发的文件。默认truesortByChangesMaxCommits统计文件变更时最多分析的 commit 数。默认100includeDiffs为真时在输出中包含 Git 差异分别包含工作区变更与暂存区变更让读者看到仓库中的待处理变更。默认falseincludeLogs为真时在输出中包含 Git 提交历史展示每个 commit 的日期、消息与文件路径帮助 AI 理解开发模式与文件间关系。默认falseincludeLogsCountgit 日志中要包含的最近 commit 数。默认50配置示例{ output: { git: { sortByChanges: true, sortByChangesMaxCommits: 100, includeDiffs: true, includeLogs: true, includeLogsCount: 25 } } }安全检查当security.enableSecurityCheck启用时Repomix 使用 Secretlint 在将内容写入输出前检测代码库中的敏感信息防止意外暴露API 密钥访问令牌私钥密码其他敏感凭据安全扫描的实现位于 src/core/security 目录其中 securityCheck.ts 负责扫描编排securityCheckWorker.ts 是执行扫描的工作线程具体匹配规则来自 secretlint.d.ts 所描述的类型化 Secretlint 规则集。注释移除当output.removeComments设为true时注释会从受支持的文件类型中移除以减小输出体积并聚焦核心代码内容。这在以下场景尤为有用处理注释极多的代码尝试降低 token 数聚焦代码结构与逻辑从 fileProcessContent.ts 可以看到注释移除通过getFileManipulator(rawFile.path)按文件扩展名获取对应的语言操纵器执行属于 CPU 密集型操作会被送入 worker 线程处理。受支持语言与详细示例参见注释移除指南。相关资源命令行选项——完整的 CLI 参考CLI 选项覆盖文件配置输出格式——每种输出格式的细节安全——Repomix 如何检测敏感信息代码压缩——用 Tree-sitter 降低 token 数GitHub 仓库处理——远程仓库的选项【免费下载链接】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），仅供参考