将 Repomix 作为 Node.js 库集成runCli、核心 API 与打包实践完全指南【免费下载链接】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 友好文件的 CLI 工具还对外导出了一套完整的 Node.js 库 API。本文基于官方开发指南website/client/src/fr/guide/development/using-repomix-as-a-library.md结合仓库源码系统讲解如何在你的 Node.js 应用中直接调用runCli处理本地目录与远程仓库、如何通过searchFiles/collectFiles/processFiles/TokenCounter等底层组件构建自定义的代码分析流水线以及将 Repomix 打进自己的产物时需要注意的外部依赖与 WASM 资源处理。读完本文你将能够把仓库 → AI 可读输出的能力无缝嵌入任何 Node.js 服务、脚本或 CI 工具中。安装 Repomix 依赖与其他 Node.js 库一样将 Repomix 作为依赖安装到项目中即可开始使用npm install repomix安装完成后可以从包入口导入所需的全部公开 API。仓库的模块出口定义在 src/index.ts它按功能分组导出了核心打包函数pack、文件流水线searchFiles/collectFiles/processFiles/sortPaths、Git 远程解析与安全检测工具、Token 计数TokenCounter、Tree-sitter 解析parseFile、配置加载loadFileConfig/mergeConfigs/defineConfig以及 CLI 层入口runCli/cli。[!NOTE] 当前文档描述的库 API 与main分支代码保持一致若你使用的是 npm 上发布的历史版本个别导出如runCli的签名可能略有差异请以安装版本的类型声明为准。基本用法通过 runCli 复用 CLI 全部能力最直接的集成方式是通过runCli函数。它的行为与命令行完全等价——实际上CLI 的 commander 入口最终也会调用同一个runCli见 src/cli/cliRun.ts 中的commanderActionEndpoint因此你可以用对象形式传入与命令行参数一一对应的选项import { runCli, type CliOptions } from repomix; // 以自定义选项处理当前目录 async function packProject() { const options { output: output.xml, style: xml, compress: true, quiet: true, } as CliOptions; const result await runCli([.], process.cwd(), options); return result.packResult; }runCli的签名是(directories: string[], cwd: string, options: CliOptions)directories要处理的目录列表默认[.]cwd相对路径的解析基准目录optionsCliOptions对象字段与 CLI 选项一一对应。从源码看runCli内部还会执行一系列预处理当output为-时自动切换为 stdout 模式src/cli/cliRun.ts第 339-342 行按quiet/verbose/stdout设置日志级别随后根据选项分派到远程仓库处理remote、watch 模式、MCP 服务等不同动作分支。这意味着作为库调用时你几乎可以获得 CLI 的全部行为包括输出样式、压缩、安全扫描、token 预算等。CliOptions的完整字段定义在 src/cli/types.ts常用的输出与过滤类选项包括选项类型作用outputstring输出文件路径-表示输出到 stdoutstylexml \| markdown \| json \| plain输出格式默认xmlcompressboolean使用 Tree-sitter 解析抽取类、函数、接口等核心结构removeComments/removeEmptyLinesboolean打包前剥离注释 / 删除空行include/ignorestring额外的 glob 包含 / 排除模式逗号分隔gitignore/dotIgnore/defaultPatternsboolean控制是否应用.gitignore、.ignore与内置默认忽略规则includeDiffs/includeLogsboolean在输出中加入 git diff 与提交历史tokenCountEncodingstring计数用编码默认o200k_basetokenBudgetnumber输出超过 N 个 token 时以非零码失败CI 防护quiet/verboseboolean日志级别控制remote/remoteBranch/remoteTrustConfigstring \| boolean远程仓库相关见下文深入理解 PackResult 返回结构runCli的返回值包含packResult其类型PackResult定义在 src/core/packager.ts。除了指南中列出的字段完整的PackResult还包括totalFiles处理的文件总数totalCharacters字符总数totalTokenstoken 总数评估 LLM 上下文窗口时非常关键fileCharCounts每个文件的字符数映射fileTokenCounts每个文件的 token 数映射gitDiffTokenCount/gitLogTokenCountdiff 与日志部分的 token 数outputFiles实际写入磁盘的输出文件路径数组配合splitOutput时会有多个suspiciousFilesResults/suspiciousGitDiffResults/suspiciousGitLogResults安全扫描发现的可疑文件如含 API Key、密码processedFiles处理后的文件内容列表ProcessedFile[]safeFilePaths/skippedFiles通过安全检查的路径与被跳过的文件信息。这些字段让调用方既能拿到总览指标也能逐文件审计内容非常适合做自定义报告或继续二次处理。处理远程仓库克隆、打包与配置信任runCli的remote选项允许直接传入仓库 URL支持 GitHub 完整 URL 或owner/repo简写来克隆并打包远程仓库import { runCli, type CliOptions } from repomix; // 克隆并处理一个 GitHub 仓库 async function processRemoteRepo(repoUrl) { const options { remote: repoUrl, output: output.xml, compress: true, } as CliOptions; return await runCli([.], process.cwd(), options); }远程流程的实际实现位于 src/cli/actions/remoteAction.ts。从源码可以看到几个值得注意的细节下载策略对 GitHub 仓库优先尝试以 HTTP 归档方式下载支持按分支/提交选择 ref超时 60 秒、重试 2 次失败后回退到git clone --depth 1浅克隆非 GitHub 仓库直接走 git clone。临时目录仓库被克隆到系统临时目录处理完成后的输出文件会被复制回当前工作目录随后清理临时目录。--config限制远程模式下--config必须是绝对路径防止从被克隆的仓库内部加载其自带的配置文件remoteAction.ts第 38-44 行。token 预算延迟校验远程模式会把 token 预算检查推迟到输出复制完成之后deferTokenBudgetCheck: true避免因超预算抛错导致临时目录中的产出被提前清理。关于远程配置信任的安全提示[!NOTE] 出于安全考虑远程仓库中的配置文件默认不会被加载。若要信任某个远程仓库的配置请在选项中添加remoteTrustConfig: true或设置环境变量REPOMIX_REMOTE_TRUST_CONFIGtrue。这一行为在remoteAction.ts中有明确的实现证据trustRemoteConfig cliOptions.remoteTrustConfig || process.env.REPOMIX_REMOTE_TRUST_CONFIG true当为false时会通过skipLocalConfig: true跳过对被克隆仓库内配置文件的加载同时只有显式信任时才会启用配置文件中的input.processors因为处理器会执行任意外部命令。此外信任决策本身也有持久化机制src/cli/prompts/remoteConfigTrustStore.ts 在$TMPDIR/repomix/trusted-remotes/下为每个仓库写入 sha256 标记文件且标记内容绑定配置文件的字节哈希——如果远程仓库之后修改了配置内容会触发重新确认。该目录还要求归属当前用户且不允许组/其他用户写isDirSafe检查防止共享主机上被预置标记绕过确认。使用核心组件构建自定义流水线当runCli的粒度不足以满足需求时可以直接使用 Repomix 的底层 API。它们同样从repomix包导出见 src/index.tsimport { searchFiles, collectFiles, processFiles, TokenCounter } from repomix; async function analyzeFiles(directory) { // 查找并收集文件 const { filePaths } await searchFiles(directory, { /* 配置 */ }); const rawFiles await collectFiles(filePaths, directory); const processedFiles await processFiles(rawFiles, { /* 配置 */ }); // 统计 token const tokenCounter new TokenCounter(o200k_base); // 返回分析结果 return processedFiles.map((file) ({ path: file.path, tokens: tokenCounter.countTokens(file.content), })); }这条流水线对应了pack()内部的主干流程src/core/packager.ts先searchFiles依据 include/ignore/.gitignore 规则发现文件再collectFiles读取文件内容随后processFiles执行压缩compress、注释剥离等变换。实际的pack()还会并行执行 git diff/log 获取、安全检查和指标计算最终生成输出。关于TokenCounter有两个实现细节值得留意见 src/core/metrics/TokenCounter.ts需要先init()countTokens在未初始化时会抛出TokenCounter not initialized. Call init() first.因为编码的 BPE 词表是懒加载的。文档示例中省略了await tokenCounter.init()实际使用时请务必在计数前调用。支持的编码定义在 src/core/metrics/tokenEncodings.ts包括o200k_baseGPT-4o、cl100k_baseGPT-3.5/4、p50k_base、p50k_edit、r50k_base。实现基于gpt-tokenizer并将所有文本按普通内容处理避免特殊 token 干扰计数。另外searchFiles还返回emptyDirPaths配合collectFiles的第二个参数根目录可以正确处理多根目录与相对路径解析这一点在构建多仓库聚合工具时尤其有用。打包注意事项外部依赖与 WASM 资源如果要在自己的应用里用 Rolldown、esbuild 等工具将 Repomix 打包进产物有两类资源需要特殊处理必须保持外部化的依赖tinypool它通过文件路径启动 worker 线程无法被打包器内联。仓库的真实打包脚本 website/server/scripts/bundle.mjs 中正是通过external: [tinypool]将其排除在 bundle 之外。必须复制的 WASM 文件web-tree-sitter.wasm→ 复制到与打包后 JS 相同的目录compress代码压缩功能依赖 Tree-sitterTree-sitter 各语言 WASM 文件 → 复制到REPOMIX_WASM_DIR环境变量指定的目录。bundle.mjs展示了完整的做法先用rolldown生成server.mjs全量 bundle与worker.mjs供 tinypool 使用的最小 worker bundle再把node_modules/web-tree-sitter/web-tree-sitter.wasm复制到输出根目录、把node_modules/repomix/tree-sitter-wasms/out下的所有语言.wasm文件复制到dist-bundled/wasm/。代码压缩功能在运行时通过REPOMIX_WASM_DIR定位语言文件在代码中也可以调用setWasmBasePath(path)显式指定路径见 src/core/treeSitter/loadLanguage.ts。真实案例Repomix 官网服务器Repomix 官方网站在线打包功能就是Repomix 作为库的典型落地服务器端实现位于 website/server/src/domains/pack/remoteRepo.ts。它的做法是先用parseRemoteValue解析用户输入的仓库地址并通过assertPublicHttpsRepoUrl强制只允许公开 HTTPS 仓库防止file://本地文件读取与指向内网的 SSRF 攻击以加固参数执行浅克隆禁用 HTTP 重定向、仅允许 https 协议调用从repomix包导入的runDefaultAction([tempDirPath], tempDirPath, cliOptions)完成打包website/server/src/domains/pack/remoteRepo.ts 第 94 行读取生成的输出文件内容并连同totalFiles、totalCharacters、totalTokens等元数据返回给前端同时按 URL格式生成缓存键以复用结果。这个案例同时展示了三个实践要点作为库消费时必须自行处理克隆与临时目录生命周期对外暴露的打包入口需要额外的 URL 校验与 git 参数加固PackResult的指标字段可直接用于响应用户请求。类似的还有处理上传 ZIP 的 website/server/src/domains/pack/processZipFile.ts可以作为处理不可信输入的参考实现。小结通过repomix包你可以把代码仓库 → 结构化、可注入 LLM 的输出这一能力以库的形式嵌入自己的应用runCli提供与 CLI 一致的一站式体验本地目录、远程仓库、多种输出格式、安全扫描、token 预算searchFiles/collectFiles/processFiles/TokenCounter则允许按需拼装流水线、实现自定义分析若需将 Repomix 打进自身产物记得把tinypool外部化并妥善复制 Tree-sitter 的 WASM 资源。源码层面src/index.ts 是查看全部公开 API 的入口src/core/packager.ts 与 src/cli/cliRun.ts 分别揭示了打包流水线与runCli的分派逻辑而 website/server/scripts/bundle.mjs 与 website/server/src/domains/pack/remoteRepo.ts 则是可以直接借鉴的生产级集成范例。【免费下载链接】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），仅供参考