将 Repomix 作为 Node.js 库使用：以编程方式打包代码库并集成 AI 工作流-平芜编程栈

将 Repomix 作为 Node.js 库使用：以编程方式打包代码库并集成 AI 工作流

【免费下载链接】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 不仅是命令行工具，还对外提供了一套完整的 Node.js/TypeScript 库 API，允许你在自己的应用、开发工具或 Web 服务中直接调用其打包能力，把任意本地目录或远程仓库转换为单一、AI 友好的输出文件。本文将以仓库文档 using-repomix-as-a-library.md 为核心骨架，结合 src/index.ts 等源码实现，讲解安装、pack()核心调用、配置选项、结果读取、远程仓库处理与打包（Bundling）注意事项，帮助你构建可复用的代码打包集成方案。

安装与前置条件

将 Repomix 作为依赖安装到你的项目中即可开始使用：

npm install repomix

Repomix 是原生 ESM 包，使用 TypeScript 编写并自带类型声明，因此无论是纯 JavaScript 还是 TypeScript 项目都能获得完整的类型提示。从当前仓库的 package.json 可以看出，repomix的 npm 包导出入口即 src/index.ts，它对外暴露了打包、文件收集、Git 处理、安全扫描、Token 计数、Tree-sitter 解析等一系列 API。

基础用法：实例化并调用 pack()

库 API 的最简用法是创建一个 Repomix 实例，然后调用pack()方法打包当前目录：

import { Repomix } from 'repomix'; async function main() { // 初始化 Repomix 实例 const repomix = new Repomix(); // 打包当前目录 const result = await repomix.pack({ path: process.cwd(), output: { style: 'xml', filePath: 'output.xml', }, }); console.log(`成功打包 ${result.stats.files} 个文件`); console.log(`总 Token 数: ${result.stats.tokens}`); } main().catch(console.error);

从源码结构看，new Repomix().pack()这一层封装最终会落到 src/core/packager.ts 导出的底层pack()函数。后者是整个打包流程的中枢，其内部串联了以下关键步骤：

文件搜索：调用 fileSearch.ts 中的searchFiles，按 include/ignore 规则发现待打包文件；
路径排序：通过 filePathSort.ts 的sortPaths对路径去重排序；
并行收集与 Git 处理：collectFiles读取文件内容，同时getGitDiffs/getGitLogs并行获取 Git 差异与提交日志；
安全校验：调用 validateFileSafety.ts 在后台线程扫描可疑文件（如包含密钥），并将命中文件从结果中剔除；
文件处理与输出生成：执行压缩、注释移除等处理器，再由 produceOutput.ts 按指定风格生成并写入输出文件；
指标计算：通过 calculateMetrics.ts 在 worker 线程池中统计字符数与 Token 数。

pack()内部还做了多项性能优化：Token 计数缓存（tokenCountCache.ts）在搜索阶段即后台预加载，Git 变更统计也会预取以加速输出排序。整个流程结束后会原子化保存 Token 缓存，供后续运行复用。

配置选项详解

pack()接受完整的配置对象，涵盖输出、忽略与安全三大部分。下面的示例展示了最常用的配置项：

import { Repomix } from 'repomix'; async function main() { const repomix = new Repomix(); const result = await repomix.pack({ // 待打包的目录或文件路径 path: './src', // 输出配置 output: { style: 'markdown', filePath: 'output.md', removeComments: true, showLineNumbers: true, topFilesLength: 10, copyToClipboard: false, compress: false, }, // 忽略配置 ignore: { customPatterns: ['**/*.test.ts', 'node_modules/**'], respectGitignore: true, }, // 安全配置 security: { enabled: true, }, }); console.log(result); } main().catch(console.error);

上述配置项与 configSchema.ts 中定义的默认值一一对应，理解默认值有助于你判断哪些参数可以省略：

配置项	默认值	说明
`output.style`	`'xml'`	输出风格，可选`xml`/`markdown`/`json`/`plain`
`output.filePath`	`'repomix-output.xml'`	输出文件路径，随`style`变化（md/txt/json 对应不同默认名）
`output.removeComments`	`false`	是否移除代码注释
`output.showLineNumbers`	`false`	输出中是否显示行号
`output.topFilesLength`	`5`	文件摘要中展示的最大文件数量
`output.compress`	`false`	是否使用 Tree-sitter 提取类、函数、接口等核心结构
`output.copyToClipboard`	`false`	完成后是否复制到系统剪贴板
`output.includeEmptyDirectories`	未启用	是否在目录结构中包含空目录
`output.parsableStyle`	`false`	是否转义特殊字符以保证 XML/Markdown 合法性
`output.truncateBase64`	`false`	是否截断超长 Base64 内容
`output.tokenCountTree`	`false`	是否输出带 Token 计数的文件树
`output.git.includeDiffs`	`false`	是否包含 Git diff
`output.git.includeLogs`	`false`	是否包含 Git 提交日志
`ignore.useGitignore`	`true`	是否尊重`.gitignore`
`ignore.useDefaultPatterns`	`true`	是否启用内置默认忽略模式（node_modules、.git 等）
`ignore.customPatterns`	`[]`	自定义忽略 glob 模式，如`['*/.test.ts']`
`security.enableSecurityCheck`	`true`	是否启用安全扫描
`tokenCount.encoding`	`'o200k_base'`	Token 计数的编码方式

需要说明的是：当前仓库源码中security配置的字段名是enableSecurityCheck（见 configSchema.ts），文档示例中的security.enabled与之一致，都是开启安全扫描的语义；开启后打包过程中会检测疑似密钥、私钥等敏感内容并自动从输出中过滤。

读取打包结果

pack()返回的PackResult对象携带了完整的统计信息、输出文本与逐文件明细：

import { Repomix } from 'repomix'; async function main() { const repomix = new Repomix(); const result = await repomix.pack({ path: './src' }); // 读取统计信息 console.log(`文件总数: ${result.stats.files}`); console.log(`总行数: ${result.stats.lines}`); console.log(`总 Token 数: ${result.stats.tokens}`); // 读取输出内容（可直接送入 LLM） console.log(result.content); // 读取逐文件信息 result.fileInfos.forEach((fileInfo) => { console.log(`文件: ${fileInfo.path}`); console.log(`语言: ${fileInfo.language}`); console.log(`Token: ${fileInfo.tokens}`); }); } main().catch(console.error);

与底层 packager.ts 的PackResult相对照，库层PackResult是面向调用的精简视图，而底层实现还额外返回了totalFiles、totalCharacters、fileCharCounts、fileTokenCounts、processedFiles、safeFilePaths、skippedFiles、suspiciousFilesResults等字段，便于需要深度控制的高级用法直接调用 src/index.ts 导出的底层pack函数获取。

处理远程仓库

pack()同样支持直接传入远程仓库地址，内部会先克隆/下载仓库到临时目录再执行打包：

import { Repomix } from 'repomix'; async function processRemoteRepo(repoUrl: string) { const repomix = new Repomix(); const result = await repomix.pack({ remote: repoUrl, output: { style: 'xml', filePath: 'output.xml', }, }); return result; }

从 remoteAction.ts 的 CLI 实现可以确认远程下载的细节：优先通过 GitHub 归档接口快速下载，失败时自动回退到git clone；远程 URL 支持完整的https://或git@地址，也支持owner/repo简写（解析逻辑见 gitRemoteParse.ts）。

[!NOTE] 出于安全考虑，远程仓库内的配置文件默认不会被加载。若你信任该仓库的配置，需在选项中显式添加remoteTrustConfig: true，或设置环境变量REPOMIX_REMOTE_TRUST_CONFIG=true。这一设计避免了你尚未审查的远程代码通过repomix.config在本地执行任意命令（如input.processors定义的外部命令），是官方刻意保留的安全边界。

典型使用场景

将 Repomix 作为库的价值在于，你可以把"代码库 → AI 友好文件"的转换无缝嵌入自有流程。

集成到自定义开发工具

把打包结果直接送入 AI 分析服务，实现"选中项目 → 自动生成代码洞察"的能力：

import { Repomix } from 'repomix'; import { analyzeCode } from './ai-analyzer'; async function analyzeProject(projectPath) { const repomix = new Repomix(); const result = await repomix.pack({ path: projectPath }); // 将 Repomix 输出发送给 AI 分析服务 const analysis = await analyzeCode(result.content); return analysis; }

批量处理多个项目

顺序遍历目录中的每个子项目并分别打包，适合批量生成代码摘要或建立本地代码索引：

import { Repomix } from 'repomix'; import fs from 'fs/promises'; import path from 'path'; async function processProjects(projectsDir) { const repomix = new Repomix(); const projects = await fs.readdir(projectsDir); for (const project of projects) { const projectPath = path.join(projectsDir, project); const stats = await fs.stat(projectPath); if (stats.isDirectory()) { console.log(`正在处理 ${project}...`); const result = await repomix.pack({ path: projectPath, output: { filePath: `${project}-output.xml` } }); console.log(`完成 ${project}: ${result.stats.files} 个文件, ${result.stats.tokens} 个 Token`); } } }

集成到 Web 应用

在 Express 等服务端框架中暴露打包接口，接收上传的仓库并返回统计与内容，是构建"代码分析 SaaS"或"AI 编码助手后端"的常见形态：

import express from 'express'; import { Repomix } from 'repomix'; import multer from 'multer'; import path from 'path'; import fs from 'fs/promises'; const app = express(); const upload = multer({ dest: 'uploads/' }); app.post('/process', upload.single('repo'), async (req, res) => { try { const repomix = new Repomix(); const result = await repomix.pack({ path: req.file.path, output: { style: req.body.style || 'xml' } }); // 清理上传的临时文件 await fs.unlink(req.file.path); res.json({ stats: result.stats, content: result.content }); } catch (error) { res.status(500).json({ error: error.message }); } }); app.listen(3000, () => { console.log('服务运行于 3000 端口'); });

官方网站在此场景下就是真实的样板：仓库中的 website/server/src 即为网站服务端实现，它通过库 API 处理远程仓库打包请求，其打包编排逻辑位于 packAction.ts，可供参考。

API 参考与底层能力

Repomix 类

class Repomix { constructor(options?: RepomixOptions); async pack(options: PackOptions): Promise<PackResult>; }

PackOptions 类型

interface PackOptions { path?: string; // 本地目录或文件路径 output?: OutputOptions; // 输出风格、路径、压缩等 ignore?: IgnoreOptions; // 忽略规则 security?: SecurityOptions; // 安全扫描开关 remote?: RemoteOptions; // 远程仓库 URL }

PackResult 类型

interface PackResult { content: string; // 打包后的完整文本内容 stats: { files: number; // 文件数量 lines: number; // 总行数 tokens: number; // 总 Token 数 }; fileInfos: FileInfo[]; // 逐文件信息（路径、语言、Token 等） }

除了上述高层 API，src/index.ts 还导出了大量底层模块供高级集成直接使用：

runCli(options)/cli：以编程方式驱动完整 CLI，参数与命令行一致，适合需要复用 CLI 全部行为（如--stdout、--watch、--stdin）的场景；
searchFiles/collectFiles/processFiles：将打包流水线拆开单独调用，实现自定义文件处理链；
TokenCounter：独立的 Token 计数工具，默认编码o200k_base（见 configSchema.ts），可对任意文本计数；
parseFile/setWasmBasePath：Tree-sitter 代码解析与 WASM 路径配置，支撑compress功能；
loadFileConfig/mergeConfigs/defineConfig：加载并合并repomix.config.*配置文件，提供类型安全的配置定义；
runSecurityCheck：独立的安全扫描器；
defaultIgnoreList：内置默认忽略模式列表。

打包（Bundling）注意事项

如果你要使用 Rolldown、esbuild 等工具把引用了 Repomix 的代码打成生产 bundle，有几个特殊依赖与资源文件需要单独处理，否则运行时会报错：

必须保持 external 的依赖：

tinypool—— 它通过文件路径启动 worker 线程，无法被 bundle 内联。可在打包配置中显式声明external: ['tinypool']。

必须复制的 WASM 文件：

web-tree-sitter.wasm→ 复制到与打包后 JS 相同的目录。web-tree-sitter 按"JS 文件所在目录"查找该文件，缺少它会导致compress（代码结构提取）功能失效；
Tree-sitter 语言文件（tree-sitter-*.wasm）→ 复制到REPOMIX_WASM_DIR环境变量指定的目录，或通过setWasmBasePath()在代码中指定。

这一逻辑在仓库中有完整可运行的范例：website/server/scripts/bundle.mjs 是官方网站服务端的打包脚本，其中bundleAll()声明external: ['tinypool']，collectWasmFiles()负责把web-tree-sitter.wasm与@repomix/tree-sitter-wasms/out/下的全部语言 WASM 复制到dist-bundled/。底层加载逻辑见 loadLanguage.ts：当设置了REPOMIX_WASM_DIR或调用过setWasmBasePath()时，从该目录按tree-sitter-<语言>.wasm命名加载；否则回退到node_modules中的@repomix/tree-sitter-wasms包。

复制语言 WASM 时可参考脚本中的过滤方式（仅选取.wasm结尾的文件），确保目录与文件命名与 loadLanguage.ts 的查找规则保持一致，即可在任意打包环境中稳定启用代码压缩特性。

小结

通过本文，你已经掌握了 Repomix 库的核心用法：安装依赖后用repomix.pack()一行式打包本地或远程代码库；通过output、ignore、security三组配置精细控制输出内容；从PackResult中读取统计、文本与逐文件信息；并了解了在开发工具、批量任务、Web 服务中的三种典型集成模式。文中涉及的全部配置默认值、底层流水线步骤与打包注意事项均有当前仓库的源码与配置定义作为依据，你可以结合这些文件继续深挖每个参数背后的实现细节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考