企业官网建设流程全解析

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/repomix

Repomix 是一款将整个代码仓库打包为单个 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 支持多种配置文件格式以获得最大的灵活性，并在加载时按照以下优先级自动查找（前一种格式不存在时才继续查找下一种）：

1. TypeScript（repomix.config.ts、repomix.config.mts、repomix.config.cts）
2. JavaScript / ES Module（repomix.config.js、repomix.config.mjs、repomix.config.cjs）
3. JSON（repomix.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 --global

TypeScript 配置：最佳开发体验

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中逐一核对）：

关于默认值的两个实现细节

• 输出文件名跟随样式自动调整：defaultFilePathMap（configSchema.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 按照以下顺序查找配置文件：

1. 当前目录的本地配置文件（优先级：TS > JS > JSON）
   • TypeScript：repomix.config.ts、repomix.config.mts、repomix.config.cts
   • JavaScript：repomix.config.js、repomix.config.mjs、repomix.config.cjs
   • JSON：repomix.config.json5、repomix.config.jsonc、repomix.config.json
2. 全局配置文件（优先级：TS > JS > JSON）
   • Windows：
     • TypeScript：%LOCALAPPDATA%\Repomix\repomix.config.ts、.mts、.cts
     • JavaScript：%LOCALAPPDATA%\Repomix\repomix.config.js、.mjs、.cjs
     • JSON：%LOCALAPPDATA%\Repomix\repomix.config.json5、.jsonc、.json
   • macOS/Linux：
     • TypeScript：~/.config/repomix/repomix.config.ts、.mts、.cts
     • JavaScript：~/.config/repomix/repomix.config.js、.mjs、.cjs
     • JSON：~/.config/repomix/repomix.config.json5、.jsonc、.json

全局目录的具体计算逻辑在 globalDirectory.ts 中：Windows 优先取%LOCALAPPDATA%\Repomix；macOS/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覆盖。

优先级顺序（从高到低）：

1. 自定义模式（ignore.customPatterns）
2. 忽略文件（.repomixignore、.ignore、.gitignore与.git/info/exclude）：
   • 位于嵌套目录时，更深目录中的文件优先级更高
   • 位于同一目录时，这些文件按无特定顺序合并
3. 默认模式（当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.ts：v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 50 * 1024 * 1024)。

高级特性

代码压缩（Tree-sitter）

output.compress: true启用的代码压缩功能利用 Tree-sitter 智能提取关键代码结构，同时移除实现细节，在保留结构信息的同时帮助降低 token 数。

主要收益：

• 显著降低 token 数
• 保留类与函数签名
• 保留 import 与 export
• 保留类型与接口定义
• 移除函数体与实现细节

实现原理：从 fileProcessContent.ts 可以看到，压缩流程会调用parseFile解析文件并产出压缩结果；压缩是best-effort的——当语言不受支持、解析失败或遇到异常文件时，parseFile返回undefined，此时会保留未压缩的原始内容，单个文件的失败绝不会中断整个打包过程。

更多细节与示例参见代码压缩指南。

逐文件包含级别（output.patterns）

output.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.ts：resolveFileLevel函数用 minimatch（dot: true，POSIX 路径形式）逐条匹配，directoryStructureOnly→compress→full依次判定。

文件处理器（input.processors）

input.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：等待命令的最大毫秒数。默认60000（60 秒）。注意npx在冷缓存下载包时可能需要额外时间
• onError：命令非零退出或超时时的处理方式。"fail"（默认）中止整个打包；"skip"记录警告并回退到文件原始内容

示例命令（每个command值需搭配合适的pattern）：

由于第一个匹配的模式生效，每个文件只应用一个处理器——例如对**/*.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，其处理器命令会在你的机器上执行。请先审查不可信仓库的配置再打包。
• 它们对库 API（pack()/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 数）排序，变更最多的文件排在输出末尾，帮助优先关注最活跃开发的文件。默认：true
• sortByChangesMaxCommits：统计文件变更时最多分析的 commit 数。默认：100
• includeDiffs：为真时，在输出中包含 Git 差异（分别包含工作区变更与暂存区变更），让读者看到仓库中的待处理变更。默认：false
• includeLogs：为真时，在输出中包含 Git 提交历史，展示每个 commit 的日期、消息与文件路径，帮助 AI 理解开发模式与文件间关系。默认：false
• includeLogsCount：git 日志中要包含的最近 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